Skip to content

Configuration

View Markdown~28,453 tokens

Settings go in caudra.toml. It has two places, and both are optional:

  • Global: ~/.config/caudra/caudra.toml
  • Project: .caudra/caudra.toml (relative to your working directory)

When both exist, project settings override global ones field by field. A few settings are global-only, and their descriptions say so. Caudra notices when either file changes while it runs, see Hot reload. /reload reads both files again, except for the experimental switches, which apply from startup.

In the terminal UI, /settings edits most tables of the global caudra.toml for you and keeps your comments. Each key shows its description, its allowed values and default, and when an edit applies. Its [?] opens the key's section of this page, and / filters every tab by key or table name.

Settings apply in this order, and each layer overrides the ones before it:

  1. Built-in defaults
  2. Global caudra.toml
  3. Global init.lua, only with Lua plugins turned on
  4. Project .caudra/caudra.toml
  5. Project .caudra/init.lua, only with Lua plugins turned on
  6. Command-line flags

Remote sessions load only the client's global configuration. They skip both project layers, project environment files, and project MCP configuration. Remote project context uses a bounded declarative asset manifest instead. See Remote Workspaces.

caudra.toml holds the settings that only you write. A file stays separate from it when Caudra also writes the file, when the file decides where credentials or processes go, or when it has its own rules for trust, errors, or privacy.

FileScopeHoldsKept separate becauseReference
caudra.tomlglobal, projectsettings, and in the global file the [experimental] switchesIt is the main file, and only you write itcaudra config example caudra
permissions.tomlglobal, projectpermission rules for tools and MCP serversIt has its own error rule: a file that fails to load denies every tool callcaudra config example permissions
mcp.tomlglobal, projectMCP serversCaudra writes it when /mcp turns a server on or off, and it starts processescaudra config example mcp
providers.tomlglobalmodel providers, their models, and their accountscaudra auth login and caudra auth logout write it, and it can hold API keyscaudra config example providers
workcell.tomlglobalprofiles for direct remote Workcell connections (needs experimental.remote_workcell)It decides where credentials go, so it has to be a private filecaudra config example workcell
sandboxes.tomlglobalmanaged sandbox providers, networks, transfers, and profiles (needs experimental.sandboxes)The /sandbox manager writes it, and it has to be a private filecaudra config example sandboxes
init.luaglobal, projectLua code that sets up plugins (needs experimental.lua_plugins)It is a program, not settings-
.envglobal, projectenvironment variables, such as API keys, for any the environment does not setIt holds secrets-
commands/global, projectcustom slash commands, one Markdown file eachEach command is a file of its own-

caudra config files lists where each file lives on your machine and whether it is there. caudra config example FILE prints the reference of a TOML file, such as caudra config example mcp. See caudra config.

[ui]
splash_animation = true
mouse_scroll_lines = 5
theme = "tokyonight"
[ui.tool_output_lines]
bash = 8
read = 5
[agent]
max_output_lines = 3000
[provider]
default_model = "anthropic/claude-sonnet-4-6"
allowed_models = ["anthropic/*", "openai/gpt-5"]
excluded_models = ["*/*-preview"]
[storage]
max_log_files = 5
[plugins.bash]
timeout_secs = 180
[plugins.index]
max_file_size_mb = 4

All fields are optional. A file starts with version = 5, and Caudra upgrades one without it, see Config file versions. Typos in field names and values of the wrong type cause an error right away, with the file and line.

For every setting in one file, with its type, default, and description, see Reference configs or run caudra config example.

provider.allowed_models is a list of glob patterns for qualified provider/model-id specs. * also matches /, so opencode/* includes nested model IDs. When the list is empty or omitted, every model is allowed. provider.excluded_models removes matching models after that, so exclusions always win. A project list replaces the matching global list. Omit it to inherit, or use [] to clear it. The policy applies to selectors, CLI and API model changes, delegation, and caudra models.

A string value in a global config file can read an environment variable. Write {env:NAME} where the value goes, and Caudra puts the value of NAME there when it reads the file. This keeps a secret or a machine-specific value out of the file:

[telemetry]
endpoint = "https://{env:OTEL_HOST}"
headers = { authorization = "Bearer {env:OTEL_TOKEN}" }
  • It works in the global caudra.toml, permissions.toml, mcp.toml, providers.toml, and workcell.toml. sandboxes.toml keeps every value as written.
  • A reference can be the whole value or part of it, and one value can hold several. Only string values expand, so keys, numbers, and booleans cannot come from the environment.
  • Caudra looks in the process environment first, then in the global .env. A project .env never supplies a value.
  • An unset variable is an error that names the file, the line, and the variable. At startup, a bad caudra.toml stops startup and a bad providers.toml exits. A bad permissions.toml fails closed and denies every tool call. A bad mcp.toml loads none of its servers, and /mcp shows the error. An edit that breaks a file while Caudra runs follows the hot reload rules instead.
  • A project file under .caudra/ cannot hold a reference, and Caudra refuses to load it. A project MCP server on a public HTTPS URL connects without review, so a reference there could send your secret to a server the repository chose.
  • ${env:NAME}, the PowerShell form, stays as written, so shell commands and permission patterns can use it.
  • When Caudra writes a file, such as /mcp turning a server off or caudra auth login adding a provider, the reference stays in the file rather than its value.

A string value in a global config file can also hold the contents of a file. Write {file:PATH} where the value goes, and Caudra puts the file's text there, with spaces and line breaks trimmed from both ends. This suits a secret that a password manager or a deployment tool keeps in a file:

[telemetry]
headers = { authorization = "Bearer {file:~/.secrets/otel-token}" }
  • The same files accept it, and the rules for environment variables apply to it too. Only string values expand, a project file under .caudra/ cannot hold one, ${file:PATH} stays as written, and Caudra writes the reference back rather than the contents.
  • A relative path starts at the directory of the config file that holds it. ~ followed by / stands for your home directory, and so does ~\ on Windows.
  • Caudra removes . and .. from the path as written before it reads the file. After a symlinked directory, .. goes back to the directory that holds the link, as on Windows, rather than to the parent of its target. A symlinked file is followed.
  • A path can hold {env:NAME}, such as {file:{env:CREDENTIALS_DIRECTORY}/otel-token}. Caudra uses the variable's value as written, so a ~ in it is a plain name.
  • On Windows, write a path with backslashes in a single-quoted TOML string, such as '{file:C:\Users\me\otel-token}', or use forward slashes. A double-quoted string needs every backslash doubled. A path such as \secrets\otel-token starts at the root of the config file's drive, and UNC paths such as \\server\share\otel-token work.
  • The file must be a regular file in UTF-8, at most 1 MiB. A path cannot contain }, or start or end with a space.
  • A missing or unreadable file is an error that names the config file, the line, and the path Caudra tried, never the contents. The config file then fails to load, with the same effect as an unset variable.
  • Caudra does not watch the file. It reads it again when it reloads the config file that names it, such as after you edit that file or run /reload.

While the terminal UI runs, Caudra watches its config files, skill and command directories, and system prompt profiles. It applies an edit shortly after you save it. One line in the footer then says what reloaded, what still needs /reload or a restart, and which file failed to load. For caudra.toml it names the tables whose values changed. It names files and keys and never shows a value from them. A save that changed nothing says nothing, and so do Caudra's own writes, such as turning a server off in /mcp. Headless runs and ACP read configuration once, at startup.

What changedWhen it applies
caudra.toml[decisions], [web], [websearch], ui.show_decisions, plugins.skill.pstack, plugins.skill.mattpocock, and plugins.skill.emil at once, in every open session. [agent] settings and [autopilot] limits from the next turn. Other tables after /reload. [experimental] after a restart.
permissions.tomlBefore the next tool call.
mcp.tomlAt once. New servers start, even when Caudra started with none. Removed and disabled servers stop, and changed servers restart. The other servers keep running.
providers.tomlThe next time Caudra reads it, such as when a model list opens. An edit to the active decision endpoint applies at once, and removing its table turns decisions off.
decisions/permission.jsonAt once. See Question overrides.
SkillsAt once.
System prompt profilesFrom the next turn.
Custom commandsAt once.
Workflows and automationsCaudra reads them again each time it lists, launches, or arms one.
workcell.toml and sandboxes.tomlAfter /reload.
init.luaAfter /reload, which runs it again. A changed script never runs by itself.
Global .env{env:NAME} references follow it at once. [websearch] takes up both its references and the backend variables it leaves to the environment, such as SEARXNG_URL. Shell commands and other keys read from the environment keep their startup values until a restart.
Files that {file:PATH} readsWhen the config file that names them reloads. Caudra does not watch them.
Project .envAfter a restart.

A remote workspace session keeps the permissions and commands of its workspace. Its project files apply after /reload.

Every request starts with the tool definitions, then the system prompt, then the conversation. Providers cache that prefix, so a turn pays full price only for what is new since the previous request. A change to the tool definitions or the system prompt breaks the match at that point, and the provider reads the whole conversation again at full price. With Claude, a cached token costs a tenth of a fresh one and writing the cache costs a quarter more than a fresh one, so the prompt of that request costs about twelve times what a hit would. /usage shows it as a drop in the cache hit rate.

So Caudra fixes the tool definitions and the system prompt when a conversation sends its first request, and keeps both byte for byte until it rebuilds them. What Caudra enforces follows your edits at once, whatever the model was told. Permissions, MCP servers, and which tools can run follow the files. The model learns of a change from a reminder appended to the conversation, which costs only its own tokens.

A rebuild takes the configuration as it is at that moment. With nothing pending, that gives the same bytes, and the cache holds. With something pending, that one request reads the whole conversation at full price, however many edits are pending. Edits to instruction files and notes that other sessions add to memory count as pending too.

Caudra rebuilds at these moments, where the request changes or the cache is gone anyway:

MomentWhy then
CompactionThe conversation is new.
Switching model or providerEach model keeps its own cache.
Switching the system prompt profileThe system prompt changes with it.
Changing the thinking levelClaude's cache of the conversation does not survive a change to the thinking settings.
Switching modeThe first switch to plan adds the plan tool. Later switches rebuild the same definitions, so the cache holds unless an edit is pending.
The cache expiresClaude keeps a cache for five minutes after the last request that used it. Caudra counts from the end of the turn, so it rebuilds a little late rather than too early. Other APIs give no fixed lifetime, so Caudra never rebuilds on a timer for them.

It also rebuilds at moments you choose, where the cached conversation can still be warm:

  • a conversation revert, which moves the conversation back to an earlier message
  • /cd, which loads the instruction files and memory of the new directory
  • /reload, which applies everything at once

MCP servers never change the definitions. The code tool is always there, and the servers and their tools reach the model in a # MCP servers reminder instead. A server that connects, fails, or changes its tools changes only that reminder.

To keep the cache through a long task, save your edits and let the next rebuild take them in. When the model needs a change right away, such as a tool you turned back on, run /reload and pay for one full read.

Until the next rebuild, a # Configuration changed reminder tells the model how the configuration differs from what it was given. It arrives with your next message and lists:

  • tools that are gone. A call to one fails.
  • tools that are new, with the first sentence of their description. They become callable at the next rebuild.
  • tools whose definition changed, such as the skill tool when a skill appears. A call follows the current definition.
  • the system prompt, as a diff that the model applies to what it reads.

Each reminder states the whole difference, so the newest one replaces the others. When the configuration matches what the model was given again, because you put a file back or a rebuild took the change in, a short reminder tells the model to disregard the earlier notice. Instruction files and memory have reminders of their own, # Instructions changed and # Memory updated, which follow the same rules.

An edit that fails to load keeps the last valid version in force, and the footer names the file and the error. A red chip such as [caudra.toml invalid] stays in the status bar until the file loads again. Click it to see the error and what Caudra does meanwhile. A system prompt profile that fails to load shows as [system prompts invalid], and a session that uses it keeps the version it loaded. permissions.toml is the exception. Caudra denies every tool call until the file loads again, so a broken edit never leaves an older, looser policy in force.

The agent and the repository can both write .caudra/, so a project change that grants access waits for you. An edit to the project rules in permissions.toml invalidates project trust, and its allows stay off until you review them in /permissions. A project MCP server that needs review waits in /mcp until you approve the changed definition. No dialog opens by itself while you work. A [review permissions] or [review MCP] chip in the status bar opens the review when you are ready. A change that only removes access applies at once.

Each one starts in the middle of a session, with the cache warm.

You add the analytics server of the HTTP example to ~/.config/caudra/mcp.toml while a github server runs. The footer shows Reloaded mcp.toml, and the server starts at once. The tool definitions stay as they were, so the next request reads the conversation from the cache. With your next message the model gets the server list again, now with analytics in it:

<system-reminder>
# MCP servers
Call these with the `code` tool: `await <server>.<tool>(...)`. This list is complete: do not guess other names.
## analytics (connected, 1 tool)
- run_query(*, sql: str) -> Any: Run a read-only SQL query against the warehouse.
## github (connected, 1 tool)
- list_issues(*, owner: str, repo: str) -> Any: List the open issues of a repository.
</system-reminder>

The model can call the new tool through code at once.

You turn a server off in /mcp. Caudra writes mcp.toml itself, so the footer stays quiet. The server stops at once, and the next server list leaves it out. The definitions stay as they were, so the cache holds. When it was the last enabled server, a short reminder tells the model to disregard the list.

You press Tab to plan while MCP servers run. Plan mode keeps the code tool and refuses each server call it does not allow, so MCP servers do not change the definitions. Only the first switch to plan changes them, by adding the plan tool, and that request reads the whole conversation at full price.

You add to caudra.toml:

[agent]
disabled_tools = ["websearch", "analytics.*"]

The footer shows Reloaded caudra.toml · [agent] from the next turn. From the next turn Caudra refuses calls to websearch and to every tool of the analytics server. The definitions keep them until the next rebuild, and the reminder lists them as gone. The cache holds.

You change a line in ~/.config/caudra/system-prompts/review.md while a session uses the review profile. The footer shows Reloaded system prompts. The system prompt the model was given stays as it was, and the reminder carries the change as a diff:

The system prompt changed. The diff below is authoritative: apply it to what the system prompt says, and follow the result.
+1 -1
--- system prompt
+++ system prompt
Prioritize correctness bugs, regressions, and missing tests.
- Do not edit files unless the user explicitly asks.
+ Do not edit files. Report each finding with its file and line.

Each later edit sends a new reminder with the whole difference so far. After a large rewrite, every small edit that follows repeats the long diff, so run /reload once to fold the rewrite into the system prompt.

/system-prompt shows the prompt as the provider received it, so it keeps the old text until the next rebuild. A notice above it says that the profile changed since.

You create ~/.config/caudra/skills/git-release/SKILL.md. The footer shows Reloaded skills. The list of skills is part of the skill tool's description, so the reminder shows that description as a diff with the new skill in it. The skill tool reads the skill directories each time it runs, so the model can load the new skill right away. The cache holds.

You add a rule to AGENTS.md. The model gets an # Instructions changed reminder with the change as a diff, and the system prompt keeps the text it was built with until the next rebuild. The cache holds. See Instruction files.

A typo in permissions.toml leaves the definitions and the system prompt as they were, since neither carries your permission rules. Every tool call is denied until the file loads again, the footer names the error, and a red [permissions.toml invalid] chip stays in the status bar. The cache holds.

You save a change and put the file back before your next message. The model hears of neither. When a turn ran in between, the model got the reminder, and the next turn adds a short one telling it to disregard the earlier notice.

Some features are experimental and stay off until you turn them on. Each one has its own switch in the [experimental] table of the global caudra.toml:

[experimental]
workflows = true
automations = true
KeyDefaultTurns on
workflowsfalseWorkflows: the workflow tool, the workflow commands and inspector, and the caudra-workflow-dev skill.
sandboxesfalseManaged sandboxes: caudra sandbox, caudra auth sandbox, --sandbox, /sandbox, and the workbench Transfer view. Sandboxes bring their own connection to Workcell and do not need remote_workcell.
remote_workcellfalseDirect remote Workcell connections: the --workcell-* flags and caudra auth workcell.
lua_pluginsfalseEvery use of Lua: plugins, the Lua API, global and project init.lua, and the caudra-plugin-dev skill. --no-plugins still turns Lua off for one run.
cross_session_messagingfalseLocal cross-session messaging: the list_sessions, send_message, publish_message, read_topic, and work_assignment tools, /peers, /messages, /topics, /groups, caudra message, live session inboxes, consumer groups, and the message history. Both processes must opt in.
automationsfalseAutomations: scripts that act on session events when their conditions hold, within the limits in [automations], and the caudra-automation-dev skill. Messaging triggers and actions also need cross_session_messaging, and workflow triggers and actions also need workflows.

Each switch is independent, so turning one on never turns on another. A missing file, table, or key leaves a switch off, and an unknown key is an error. caudra remote and /remote work when either sandboxes or remote_workcell is on, and each session checks the switch for its own source.

Only the global file may hold [experimental]. Caudra rejects a project .caudra/caudra.toml that contains the table, even an empty one, so a repository cannot opt you in. Lua, tool allowlists, and saved sessions cannot turn a feature on either.

Caudra reads the switches once at startup and keeps them until it exits. /reload, session switches, and ACP sessions all use the startup values. When the table changes on disk, Caudra shows a notice asking for a restart.

A feature that is off is hidden and does no work. Its tools, commands, shortcuts, help entries, and status chips are gone, and startup skips it. Asking for it directly, such as typing its command or passing its flag, fails with a message that names the switch. A saved session attached to a sandbox or a remote workspace does not resume while its switch is off, and it never falls back to local execution. Turning a feature off keeps its data and leaves external resources alone, so a running sandbox keeps running until you stop it.

Earlier releases read settings from init.lua through caudra.setup(). Caudra now runs init.lua only when lua_plugins is on. With Lua off, Caudra shows one notice that names each init.lua it skipped. It does not read, run, or change those files.

To migrate, move the table you passed to caudra.setup() into the caudra.toml of the same scope. Keys and values stay the same. Top-level values come first, and each nested table becomes a TOML table:

caudra.setup({
always_fast = true,
ui = { theme = "tokyonight" },
agent = { disabled_tools = { "websearch" } },
})
always_fast = true
[ui]
theme = "tokyonight"
[agent]
disabled_tools = ["websearch"]

Lists become arrays, and deeper tables become dotted headers such as [agent.steering.rules.repetition]. Quote a key that holds other characters, as in [agent.steering.models."openai/gpt-5"]. Leave out any key you set to nil.

To keep using init.lua, set lua_plugins = true under [experimental]. Its caudra.setup() values then apply on top of the caudra.toml of the same scope, in the order shown above.

FieldTypeDefaultDescription
always_yoloboolfalseStart every session with YOLO mode (skip permission prompts, deny rules still apply); global config only
always_autoboolfalseStart every session with Auto permission mode (preserve required prompts and screen unmatched calls); global config only. Screening runs only while a decision endpoint is active
always_fastboolfalseStart every session with fast mode, on the models that sell a fast tier (ignored otherwise)
always_thinkingbool | stringunsetStart every session with extended thinking (true/"adaptive", "off", an effort level ("minimal" to "max"), or a token budget)
FieldTypeDefaultEnvMinDescription
splash_animationbooltrue--Show splash animation on startup
scrollbarbooltrue--Show vertical scrollbar in scrollable areas
touchstringauto--Touch-friendly pointer handling: auto, on, or off. Widens the scrollbar's hit zone so a finger can tap it, scrolls one line per wheel event instead of mouse_scroll_lines, and leaves text selection to the terminal. Auto detects Termux around Caudra itself, which SSH does not carry, so set this to on when reaching Caudra from a phone over SSH
notificationsstringauto--Terminal notification method: auto, osc9, bell, or off. Auto reports OSC 7501 program status when supported, otherwise uses OSC 9 or BEL. Native Herdr or Orca reporting takes precedence in their panes. Explicit osc9, bell, and off skip program status detection
mathstringunicode--How LaTeX maths renders: unicode (approximate with Unicode) or raw (show the LaTeX source)
mermaidstringunicode--How mermaid flowcharts render: unicode (draw them with box-drawing characters) or off (leave the fence as code)
inline_imagesstringauto--How the transcript draws images that view_image reads, image_generate saves, and markdown names with ![alt](path): auto (Kitty graphics where the terminal supports them, coloured quadrant blocks anywhere else), kitty, blocks, sextants (sharper blocks, for fonts and terminals that draw Unicode 13 sextants, such as Ghostty, kitty, WezTerm, and foot), or off (show only the caption; false also turns them off). Markdown images are read from local files only and never fetched
flash_duration_msu6410000--Duration of ordinary status-bar messages (ms). Confirmation prompts use a fixed 3-second window
which_key_delay_msu64250--How long Ctrl+X waits before listing the chords it can still reach (ms). 0 shows the list at once
tooltipsbooltrue--Show a tooltip when the mouse rests on a footer chip, a composer, queue or permission prompt control, an icon, a cut-off name or a paste token
typewriter_ms_per_charu644--Typewriter effect speed (ms/char)
mouse_scroll_linesu323-1Lines per mouse wheel scroll
scroll_card_linesu3210--Rows of body a shell, code or task card draws. The window follows new output while it sits at the bottom and pauses when scrolled up. Click inside a window to give it the wheel, which passes back to the transcript at either edge, and drag the bar in its last column to move it directly. 0 turns scrolling off, restoring the ui.tool_output_lines budget for those tools. A write is never windowed: it is drawn whole at any setting, as the file it created or as the diff of what it replaced
always_collapsedstring[]["file_read", "file_glob", "file_grep", "file_index", "webfetch", "source_code_context", "source_code_refs", "history.search", "history.read", "history.sessions", "tool_output", "skill", "execution_environment", "list_sessions", "read_topic", "automation", "memory_read", "plan_read", "workflow_read", "task_control_read"]--Tools whose card never opens on its own: the call stays a single row in every view mode until you click it. A server-qualified name still matches, so file_read also covers mcp_File_read. A code snippet's history calls are named history.search, history.read, and history.sessions, and its host.environment call is execution_environment. memory_read, plan_read, workflow_read, and task_control_read cover only the calls of memory, plan, workflow, and task_control that read, and leave the calls that change something open. The bare tool name covers all of its calls. Set to [] to opt out
max_input_linesu3220-1Maximum visible input lines
show_thinkingbooltrue--Show full model reasoning live and persisted. Turn this off to start every reasoning block collapsed behind a Thinking or Thought header that can be clicked to expand
thinking_linesu3210--Rows of body an open reasoning block draws. The window follows the reasoning while it streams and pauses when scrolled up, and a footer reports how much sits above and below. Click inside a window to give it the wheel, which passes back to the transcript at either edge, and drag the bar in its last column to move it directly. Click the footer to follow again. A finished block rests on its last rows until you move it. 0 draws every block whole
show_remindersbooltrue--Show the messages Caudra writes into the conversation on your behalf: standing reminders, goal check-ins, nudges, and continuations. Each is one dim row that expands on click to the exact text the model was sent. Turn this off to keep the transcript to the conversation alone
show_decisionsbooltrue--Show what the decision engine changed or is deciding. A decision about a tool call is a chip on the call's card, such as ◆ reranking… while the engine works and ◆ reranked once it answers, and clicking the chip shows the candidates and scores behind it under the card's header. A decision about a turn, such as a skill suggestion or a skipped goal check, is a row that expands on click. Failures say the default applied, and shadow marks what a feature in shadow mode would have done. The model never sees them
clock_formatStringsystem--Clock format for timestamps: "12h", "24h", or "system" (follow the OS preference, 24h when unknown)
update_checkbooltrueCAUDRA_ENABLE_UPDATE_CHECK-Check GitHub releases in the background at interactive startup and show a banner above the prompt when a newer version is available. Uses a shared 24-hour cache and never installs automatically. Set false to disable
update_channelstringauto--Release channel: auto follows stable from a stable build and preview from a prerelease, including graduation to stable. stable excludes prereleases. preview includes prereleases and stable releases
changelog_on_updatebooltrue--After an update, show what is new in the releases since the one you last ran, once, the next time the terminal UI starts with nothing else to show. /changelog shows the notes at any time. Set false to keep them to /changelog
default_modestringplan--Mode a new terminal UI session opens in: plan, where the agent writes only the plan file until you switch, or build. A resumed session reopens in the mode it was left in, and /new in an idle tab keeps that tab's mode. --print and ACP always start in build
themestringunset--Name of the color theme to load at startup, overriding the theme you last picked with /theme. Unset keeps your last pick
theme_lightstringunset--Light theme to pair with theme, in place of the one from the pairing table or for a theme that has no pair. theme becomes the dark half

Name of the color theme to load at startup, overriding the theme you last picked interactively. If unset, Caudra keeps your last selection, which starts out as caudra-dark. An unknown name is ignored with a warning.

Available themes: ayu_dark, ayu_light, ayu_mirage, carbonfox, catppuccin_frappe, catppuccin_latte, catppuccin_macchiato, catppuccin_mocha, caudra-dark, caudra-light, dark_daltonized, dracula, everforest_dark, fleet_dark, github_dark, gruvbox, gruvbox_light, kanagawa, kanagawa_ink, kanagawa_plum, material_darker, monokai_pro, night_owl, nightfox, nord, onedark, rose_pine, rose_pine_dawn, rose_pine_midnight, rose_pine_moon, solarized_dark, solarized_light, tokyonight, vscode_dark_plus, zenburn.

You can add your own themes too. Drop a <name>.toml file into themes/ inside your Caudra config directory, for example ~/.config/caudra/themes/. If it reuses a built-in name, yours wins.

Themes use 24-bit colors, but not every terminal can show them. Caudra checks the environment, terminfo, and the terminal itself, and when truecolor is missing it quietly falls back to the closest of the 256 classic terminal colors. If detection gets it wrong, set CAUDRA_TRUECOLOR=1 to force truecolor or CAUDRA_TRUECOLOR=0 to force the fallback.

Some themes ship as a light and dark pair: ayu_dark and ayu_light, catppuccin_mocha and catppuccin_latte, caudra-dark and caudra-light, gruvbox and gruvbox_light, rose_pine and rose_pine_dawn, solarized_dark and solarized_light. Choosing either half makes Caudra ask the terminal whether it is in light or dark mode and show the half that matches. Caudra changes halves as soon as the terminal reports a new mode, for example when your desktop switches to dark mode. A terminal that cannot report its mode is asked for its background color instead. Themes outside these pairs stay as you left them.

Caudra asks again every ten minutes, and also when the terminal regains focus or changes size, so reattaching a multiplexer to another terminal updates the theme. Following the terminal only changes the running session, and the theme you saved from /theme stays saved. A terminal that answers neither question is asked for its background color only a few times. After that, Caudra asks only whether it is in light or dark mode.

Mosh drops the request for mode reports before it reaches your terminal. Turn the reports on yourself when you connect, and off again when you leave:

Terminal window
printf '\033[?2031h'; mosh user@host; printf '\033[?2031l'

Light half to use in place of the one from the pairing table, or to give a theme that has no pair. ui.theme becomes the dark half:

[ui]
theme = "tokyonight"
theme_light = "catppuccin_latte"

Leave ui.theme unset to pair the light theme with whatever you last picked from /theme.

Enabled by default in the interactive UI. Caudra checks GitHub releases in the background at startup. When a newer version is available, a one-line banner above the prompt names it and the command that installs it, in every session of that process. A shared on-disk cache reuses successful checks for 24 hours across processes, with backoff after failures. Headless and ACP runs do not start an update check. Nothing is installed without asking.

Click the banner's text or run /update to install the release. Caudra asks first, then stops every session, runs the installer in the terminal, and restarts on the same tabs with the flags it was started with. Work that was running is interrupted, and agent.resume_interrupted decides whether it resumes. If nothing is installed, the sessions reopen with a warning. An --ephemeral run, and Windows, where the install finishes after Caudra exits, exit instead of restarting. A Homebrew, Nix, or Cargo installation is updated through its package manager instead.

Click the banner's × or run /update dismiss to hide it in every session until Caudra exits. The dismissal is not saved, so the next start shows the banner again while the release is still newer.

GitHub receives your source IP address and normal request metadata, including a caudra user agent. The check sends no session data, machine identifier, or current version.

Set ui.update_check = false to disable startup checks. CAUDRA_ENABLE_UPDATE_CHECK=0 disables them for one run. CAUDRA_ENABLE_UPDATE_CHECK=1 checks even when the config says false, and it asks GitHub instead of reading the cache, so a release published since the last check shows at once. Its answer refreshes the cache for later starts. An empty value leaves the config in effect. A normal run still contacts your model provider and sends web searches to Exa when the agent uses websearch. Long-running sessions also check models.caudra.ai daily for a newer model list unless models.refresh is false.

The default, "auto", follows stable releases from a stable build and preview releases from a prerelease build. "stable" excludes prereleases. "preview" includes both prereleases and stable releases, so a preview can graduate to its stable release. After graduation, "auto" follows stable releases.

Run caudra update --channel auto, caudra update --channel stable, or caudra update --channel preview to update manually. An explicit update bypasses the startup cache and opt-out. The banner's command names the channel the check used, with auto resolved to stable or preview.

Enabled by default. The first interactive start after an update opens the release notes for every release since the one that ran before. It opens once per update, even with several Caudra processes running. A start that runs a prompt from the command line, exits when it is done, or opens on a login or trust dialog leaves the notes to the next start. A new install shows no notes. Caudra reads this setting at startup.

/changelog opens the same notes at any time, and /changelog all opens every release. Press g in the modal to switch between the two, and o to open the release you are reading on GitHub. The same notes are on the Release notes page.

How many terminal rows of output an open card shows per tool before it says how many it is holding back. A line that wraps spends a row for each row it wraps to, so an abridged card is the same height whatever its lines are. Clicking the card shows all of it regardless. All values are usize with a minimum of 1.

The bash, code, and task entries apply only when ui.scroll_card_lines is 0. Above that, those tools draw a fixed window of that many rows instead, and the budget here goes unused. write does not reach a file_write that created a file, whose body is that file and is always drawn whole. It is also a floor rather than a bound for anything drawn as a diff, since a diff is already only the part that changed: an edit, a patch, and an overwrite are drawn whole until they run long, and raising write past that point is what makes this number matter to them. No entry reaches an MCP call's card, which opens with its arguments and its whole answer.

FieldDefaultTools
bash5shell
code5code
task12task, task_control
index3file_index, source_code_context, source_code_refs
grep3file_grep, file_glob
read3file_read
write7file_write, file_edit, file_apply_patch, image_generate, memory, plan
web3webfetch, websearch
other3automation, batch, execution_environment, list_sessions, publish_message, question, read_topic, request_secret, send_message, skill, todo_write, tool_output, view_image, work_assignment, workflow
FieldTypeDefaultMinDescription
system_prompt_profileStringbuiltin-Default user system prompt profile from the system-prompts config directory
max_output_bytesusize512001024Host-enforced default max tool-result size (bytes)
max_output_linesusize200010Host-enforced default max tool-result lines
compaction_bufferu32 | string20%, or 10% when the model's window excludes output. On a window that includes output, at least the model's output allowance, up to half the window-Context reserved for compaction: token count or percent of the context window (e.g. "20%")
compaction_instructionsStringunset-Extra instructions appended to the compaction summary prompt
post_compaction_instructionsStringunset-Extra instructions the agent receives after any compaction (e.g. re-read plan.md)
compaction_requirementsbooltrue-Append a # User requirements section to every compaction summary: what the user asked for, constrained, and decided, read from their own messages and answered questions across every earlier compaction, and extracted by the Extract model so the conversation model never sees the request
background_reminder_turnsu320-Committed main-agent response groups between unchanged active background-work reminders; 0 disables periodic refresh only, not state-change or post-compaction reminders
todo_reminderbooltrue-Before the main agent hands control back with pending or in-progress todos and no background work running, remind it once per run, repeating the full todo list, to verify the work and update the list
work_nudge_compactionsu322-Compactions within one request, with no work started since it, before Caudra reminds the agent to act: make a change or delegate one in build mode, write the plan or ask in plan mode, report in a read-only task. Repeated at every compaction after that. 0 disables
shell_wait_nudge_minutesu3230-Minutes a background shell may run before Caudra asks the agent waiting on it whether to keep waiting or to check whether the command hangs. Repeated at every further interval while it runs. Foreground shells are never nudged. 0 disables
task_model_choicebooltrue-Let the main agent choose a model and reasoning level for each task call, such as when you ask it to run work on a named model. When off, task has no model or thinking argument and tasks run on the Subagent model or a profile's pin
deferred_questionsbooltrue-Let the main agent ask a question without waiting for the answer, so it keeps working while the form waits for you. The answer reaches it later, and you can also put a waiting question off with F4. When off, every question waits for its answer
shell_foreground_limit_secsu646001How long a shell call waits for its command before a command still running moves to the background and the call returns a receipt; the command keeps running until it exits or reaches its own timeout
shell_etabooltrue-Show an ETA on a shell card and in /shells, from a small model trained on this machine's past shell runs. It only labels the command: timeouts and delivery never change. When off, nothing is predicted or recorded
generate_titlesbooltrue-Name a new session by summarizing its first prompt with the Title model
summarize_memorybooltrue-Summarize memory notes in the background with the Memory model, so the memory view in the system prompt stays within its budget. When off, new notes reach the view only as titles and memory search still finds them
memory_nudgesbooltrue-Remind the main agent to save a memory note after a failed command passes, a long search ends in an edit, the user corrects it, or the context nears compaction. Reminders thin out as the project's notes grow and stop once the agent saves notes without them
stale_read_checkbooltrue-Block a write to a file that changed on disk since it was read, and point a failed edit or patch at the change
tool_json_repairbooltrue-Repair malformed tool JSON syntax locally, with one bounded isolated model fallback; independent of eager dispatch
eager_tool_dispatchbooltrue-Start tools and batch children as soon as their complete arguments arrive, instead of waiting for the whole message
shell_output_filterbooltrue-Filter completed model-facing shell output with built-in rules
shell_workdir_redirectbooltrue-Refuse shell commands with a leading literal cd ... && in favor of the shell workdir parameter. Set to false to disable this nudge independently of shell_native_redirect
shell_native_redirectstringenforce-What happens when a shell command only re-implements a native tool, such as bare rg or cat: enforce refuses it and names the tool to call instead, annotate only logs the finding, off disables the check. A command using any flag the native tool cannot express is never affected
image_modelstringsunburst-GPT Image 2.5 model behind image_generate: sunburst is the most capable and the better editor, flare is faster at the same price
cache_warmingstringoff-Keep the prompt cache from expiring by re-sending the last request with no output, on the Anthropic API only: running while a run waits on a long tool, subagent, question or permission prompt, idle also for up to 30 minutes after it ends, off never. Each refresh is billed as a cache read; global config only
resume_interruptedstringauto-What reopening a session does with work Caudra stopping cut off (a crash, a kill, or quitting mid-turn): auto resumes the main turn and its tasks at once, ask offers to, off only says what was interrupted. auto asks instead when a resume already crashed once, when the work is older than resume_max_age_hours, or when automatic wakes are suppressed
resume_max_age_hoursu64241Hours after which resume_interrupted = "auto" asks before resuming interrupted work instead of resuming it
continual_learningbooltrue-Learn from your conversations in the background: after enough new prompts, the Learn model reads them and keeps durable conventions, setup facts and preferences in the instruction files and memory notes. A project config can turn it off, never on
learning_targetsstring[]["project", "local", "global", "memory"]-Where continual learning may write: project (the committed AGENTS.md), local (AGENTS.local.md), global (~/.config/caudra/AGENTS.md), memory (memory notes). A project list can only narrow the global one
disabled_toolsstring[][]-Tools to withhold from the model: built-in names, server.tool, or server.* for a whole MCP server. A project list extends the global one
FieldTypeDefaultMinDescription
inboundstringauto-Inbound cross-session messages: auto accepts only compatible trusted peers, accept allows wider delivery, hold requires approval, refuse rejects messages. Project settings may only tighten policy: accept < auto < hold < refuse. Needs experimental.cross_session_messaging; accepting messages can start billable turns
inbound_per_minuteusize641Most peer messages a session admits per minute from all senders together. Project settings may only lower it
sender_per_minuteusize161Most peer messages a session admits per minute from one sending session. Project settings may only lower it
publish_per_minuteusize161Most topic and broadcast publications a session sends per minute. Project settings may only lower it
max_fanoutusize321Most live sessions one topic or broadcast publication reaches. Extra recipients are skipped and counted. Project settings may only lower it
history_daysu64301Days the shared message history keeps a message. The newest message on each topic outlives this until history_max_messages evicts it. Global config only
history_max_messagesu64500001Most messages the shared message history keeps; the oldest go first. Global config only
FieldTypeDefaultDescription
passstring[][]Host variables forwarded to local shell commands: exact names or NAME_* prefixes, never a bare *. Values come from Caudra's environment and the global .env, never a project .env
settable{}Values set for local shell commands; {env:NAME} reads Caudra's environment and {file:PATH} a file. Wins over pass

These choose which host variables reach local shell commands, and /env edits them. Only the global caudra.toml may hold this table. Caudra rejects a project .caudra/caudra.toml that contains it, even an empty one, so a repository cannot forward your credentials to the commands it asks for. A sandbox forwards its guest's variables instead, set per profile.

Automatic steering repairs unusable model output and can add bounded guidance about repeated behavior or needlessly long tool paths. Every rule is enabled by default. Configure overrides in the [agent.steering] table. All fields are optional.

FieldTypeDefaultMinMaxDescription
enabledbooleantrue--Master switch for automatic steering, including truncation recovery and repeat-policy blocking.
max_recoveriesinteger3201024Corrective continuations per externally initiated invocation. Zero prevents optional recovery continuations.
max_advisoriesinteger401024Advisory injections per invocation. Zero suppresses advisories.
max_stalled_turnsinteger501024Consecutive turns carrying neither a tool call nor visible text before the run ends, whichever rule intervened. Zero disables the backstop.
rulestable{}--Overrides by rule name, listed below. Omission uses built-in defaults.
modelstable{}--Up to 256 exact provider/model-id keys, each with its own overrides.
Rule in rulesBehavior
truncationContinue output cut off by the response token limit, up to 3 corrective requests per externally initiated invocation.
empty_responseContinue after empty output, with separate per-episode limits after recent tools and while idle.
repeated_tool_callRefuse the third consecutive identical top-level tool name/input before execution. Native batch children do not acquire this hard blocker.
protocol_mismatchCorrect an explicit provider tool-use indication with no actual tool calls, up to 2 continuations per episode.
missing_task_reportRequest a missing task summary or required structured report, up to 2 corrections.
abandoned_turnContinue a turn that ended by announcing work the response never performed, up to 2 continuations per episode. Spending the allowance accepts the text rather than failing the turn.
repetitionAdvise on short exact tool cycles, including normalized native batch leaf calls, or repeated normalized assistant text.
tool_planningAdvise after consecutive failed tool attempts across responses, including attempts with different tools or inputs. Any successful tool result ends the failure episode. Repeating a successful call is insufficient.
relative_pathsSuggest up to two shorter relative forms when file, patch, source-code, or shell workdir paths spell out the working directory or its parent. The hint appears once per context.

Recovery and advisory budgets are separate. Advisory rules allow at most 4 total injections per invocation. Repetition and tool-planning advisories each wait a default cooldown of 3 completed model responses.

Tool-planning evidence starts after the last response containing any successful tool result, including results outside the retained batch window. A background admission ends the failure episode without proving that the background work succeeded. Later terminal outcomes do not retroactively change that admission into a failed attempt.

Relative-path evidence is the latest response only, and the hint yields to repetition and tool-planning advisories. While an earlier hint remains in context, even across user turns, no new hint is added. Once compaction removes it, another hint appears only if a later response uses absolute paths again. A suggestion climbs at most one directory with ../. Local sessions get suggestions only when the working directory the model sees is the canonical project path. Remote workspaces, sandboxes, and source-code scopes get suggestions inside the working directory only. Paths with backticks, angle brackets, control characters, or invisible Unicode formatting characters are never quoted. Caudra never rewrites the paths a model sends.

An empty-response episode lives in the transcript tail, so it survives a restore and a new invocation. A message typed into a stall is answered, but it does not refill the budget: only a response carrying a tool call or visible text ends the episode. max_stalled_turns bounds the turns that interleaved rules spend between them, independently of any single rule's allowance.

Advisories only accompany an independently scheduled next request. They never reopen a valid final answer. Tool-looking prose, JSON, XML, code fences, and quoted examples do not independently trigger protocol correction. Caudra does not scrape tool names or arguments from text and execute them. Only actual tool calls pass through normal validation and authorization. Ordinary assistant answers do not have to be JSON.

Each table at agent.steering.rules.<rule> accepts these common fields:

FieldTypeDefaultDescription
enabledbooleantrueExplicit false disables this rule.
promptstringunsetUse built-in guidance when omitted. Custom text must be nonblank and at most 16,384 UTF-8 bytes.

Custom prompts replace guidance only. They are literal user-configured text, without template expansion or executable expressions. They do not change triggers, budgets, enforcement, or factual tool-failure information. A custom prompt cannot authorize a tool or turn a rejected call into an executed one.

The remaining fields are integers. All ranges are inclusive. Set enabled = false to disable a rule rather than setting a positive threshold to zero.

Field under rulesDefaultRangeUnit and meaning
truncation.max_attempts31–1024Actual truncation-correction requests per externally initiated invocation, shared across truncation episodes.
empty_response.max_after_tools31–1024Empty-output continuations per episode after recent tool results.
empty_response.max_idle21–1024Empty-output continuations per episode without recent tool results.
empty_response.max_barren11–1024Continuations per episode after a response that carried no content at all. Clamped by the limit above; repeating an unchanged request is not a retry.
empty_response.recent_tool_window51–4096Non-padding history messages inspected for recent tool results.
repeated_tool_call.threshold32–1024Consecutive identical top-level calls. Refuse the call reaching this threshold.
protocol_mismatch.max_attempts21–1024Protocol corrective continuations per episode.
missing_task_report.max_attempts21–1024Additional report-correction prompts per task invocation.
abandoned_turn.max_attempts21–1024Continuations per episode after a turn that announced work instead of doing it.
repetition.window241–4096Recent normalized leaf tool calls retained for cycle detection.
repetition.cycle_repeats32–1024Exact repetitions of a tool cycle needed for an advisory.
repetition.max_cycle42–1024Maximum cycle length in leaf calls. Candidate cycle lengths start at 2.
repetition.text_window81–4096Recent completed assistant responses retained for text repetition.
repetition.text_repeats32–1024Matching nontrivial normalized assistant responses needed for an advisory.
repetition.cooldown31–1024Completed model responses between this rule's advisories.
tool_planning.after_calls61–1024Number of most recent leaf tool calls that must all have failed since the last response containing a successful result.
tool_planning.after_responses31–1024Distinct completed model responses represented by those failed calls.
tool_planning.cooldown31–1024Completed model responses between this rule's advisories.
relative_paths.min_saved_chars121–1024Characters a relative form must save over its absolute path before the path is suggested.

Validation also requires:

  • repetition.window >= repetition.max_cycle * repetition.cycle_repeats.
  • repetition.text_window >= repetition.text_repeats.
  • tool_planning.after_calls >= tool_planning.after_responses.

Unknown fields, invalid types, out-of-range values, and impossible threshold/window combinations are rejected, even for disabled rules. Cooldowns count completed model responses, not seconds, stream chunks, tool children, or injected messages. Advisory eligibility excludes synthetic messages, empty markers, reasoning-only padding, and private title, compaction, or evaluator requests. Advisory evidence is the responses to the request in flight: a new user message ends it, as a compaction or a model change does, so an ordinary conversation is never advised. Recent-pattern windows reset with it, without refilling an active invocation's budgets.

Tool-planning guidance asks the model to reconsider its tool choices and identify the next useful action. It does not switch Plan Mode or require a todo list.

This example disables repetition guidance globally, then enables it with a higher threshold for one exact model and adjusts that model's tool-planning guidance:

[agent.steering.rules.repetition]
enabled = false
[agent.steering.models."openai/gpt-5".rules.repetition]
enabled = true
text_repeats = 4
[agent.steering.models."openai/gpt-5".rules.tool_planning]
after_calls = 8
prompt = "Reassess your recent tool choices. Choose a different useful action if these calls are not helping."

Model entries accept enabled, max_recoveries, max_advisories, max_stalled_turns, and rules with the same types and limits as the global fields. They cannot contain another models table. Omitted fields inherit through the resolution order below.

Keys are case-sensitive exact IDs, at most 512 UTF-8 bytes each. Use a nonempty provider and model suffix separated by /. Additional slashes inside the suffix are allowed, but every segment must be nonempty. Whitespace, control characters, *, ?, [, ], {, }, and backslashes are rejected. Matching requires no authentication or model discovery. There are no glob overrides, provider-wide layers, capability guesses from model names, or Lua detector callbacks.

Global and project settings merge field by field, with project values taking precedence. Model maps merge by exact key and rules merge by rule name and field. Omission inherits. Explicit false and 0 survive merging. An empty table does not clear inherited entries. Disable an inherited model policy or rule with enabled = false.

After merging, resolve against the effective routed model for Chat, Plan, or a delegated task:

  1. Start with built-in policy and rule defaults.
  2. Apply explicit global fields and rule fields.
  3. Apply explicit matching model fields and rule fields.

A child resolves its own effective model using the inherited unresolved configuration, rather than inheriting the parent's resolved policy or runtime counters.

A new externally initiated main-agent or task invocation gets its own allowance. An explicit user/caller resume starts a fresh bounded invocation. Automatic continuations, internal retries, task report-correction prompts, compaction, and mid-run queued instructions do not refill the active allowance, including when report correction constructs a fresh agent. Separately delegated children have independent allowances. Counters are not durable across process restarts or explicit task resume.

Charge one recovery for a completed-response-to-next-request transition caused by empty or truncated output, all-invalid tool calls, a response consisting entirely of repeat-policy refusals, an explicit protocol mismatch, or a missing task report. Corrective tool-error feedback can supply the guidance without a supplemental prompt and still consumes the transition. Malformed-argument and schema repair use this allowance without a separate rule table. Per-rule limits apply underneath the combined recovery cap.

A mixed batch with useful successful siblings proceeds normally. It is not replayed or charged once per child. Transport and authentication retries, ordinary tool execution failures, permission denials, normal successful tool progress, explicit goal evaluation, and manual steering are separate from model-format recovery. The recovery budget does not bound every possible agent loop. Outer turn limits and cancellation still apply.

At most one supplemental steering message is added per request. Recovery takes priority, then repetition, tool planning, and relative paths. Advisory exhaustion only suppresses hints. Recovery exhaustion with an unmet output contract reports a failure and retains partial output, except for abandoned_turn, which stops intervening and lets the turn end. A valid captured structured task report remains usable after an empty tail, but cancellation, transport/permission failures, and hard outer-limit failures do not become success.

abandoned_turn reads the tail of a response that called no tool and would otherwise end the turn. It fires on a text stopping at a bare colon, or on a last sentence that opens on an intent to act. It does not fire on a question, an offer, a completion, or a promise deferred behind another event, and code spans and quoted prose are removed before any of that is matched. It also stays quiet while a task, background job, or workflow is still running, because that work's report wakes the agent to continue. Tool-looking prose is not executed here either; the rule only decides whether to ask for one more response.

The resolved enabled = false disables automatic recovery, including truncation, advisories, and repeat-policy blocking. It leaves malformed-input rejection, schema validation, permissions, mode restrictions, cancellation, explicit goals, manual steering, and compaction policy intact. A rule-level switch disables only that rule. Zero budgets prevent the corresponding continuations or hints without bypassing input validation or repeat-policy enforcement.

Truncation recovery counts corrective requests, not ordinary responses or tool rounds. Each request consumes one attempt from rules.truncation.max_attempts and one recovery from max_recoveries. Automatic report-correction prompts and compaction do not refill either allowance. The last allowed correction may complete the answer. If another correction is needed, exhaustion reports an error with partial output and usage retained, including when max_recoveries = 0.

Disabling the master switch or setting rules.truncation.enabled = false stops with the truncated outcome instead of requesting a continuation. Disabled or exhausted truncation does not fall through to empty-response repair, even when the truncated response is empty. An unresolved truncated task result remains cut short rather than reopening through report repair. A valid structured report can still satisfy the task's report contract. Cancellation, queued user instructions, and outer turn limits take priority over automatic steering.

FieldTypeDefaultMinDescription
default_modelStringunset-Default model identifier (e.g. anthropic/claude-sonnet-4-6)
allowed_modelsstring[][]-Glob patterns for permitted qualified model specs; empty permits all models
excluded_modelsstring[][]-Glob patterns for excluded qualified model specs; exclusions take precedence
connect_timeout_secsu64101HTTP connect timeout (seconds)
stream_timeout_secsu6430010Longest the server may send nothing before the request is abandoned (seconds)
FieldTypeDefaultEnvDescription
refreshbooltrueCAUDRA_MODELS_REFRESHCheck for signed model updates daily in long-running sessions. A project may only disable refresh. The environment variable accepts 0/1, false/true, no/yes or off/on. Cached models remain usable when disabled
urlStringunset-Global-only signed model file URL. Project values are ignored. Requires HTTPS, or HTTP to loopback. The signature is fetched from the same URL with .sig appended. Takes effect after a restart
FieldTypeDefaultEnvMinDescription
max_log_bytes_mbu64200-1Max total log size (MB)
max_log_filesu3210-1Max number of log files to keep
max_eager_load_mbu641024CAUDRA_MAX_EAGER_LOAD_MB64Largest session Caudra will hydrate when opening one (MB), counted in uncompressed payload bytes rather than disk or memory. A session past this refuses to load; trim it or raise this
log_levelstringinfo--Minimum severity written to the log file: trace, debug, info, warn, or error. RUST_LOG overrides it
input_history_sizeusize100-10Number of input history entries to retain
ephemeralboolfalse--Store session data in a temporary directory removed when Caudra exits
FieldTypeDefaultDescription
group_bystringdirectoryEvaluate policies per working directory (directory) or across every session (none)
sweep_interval_hoursu6424Hours between background sweeps. A sweep reclaims freed space, and applies trim and forget when they are set. 0 disables the sweep; caudra storage commands still work
trimtable{}Sessions outside this policy lose file revert, retained tool outputs, archives, and large rich outputs but stay resumable. Empty means never trim automatically
forgettable{}Sessions outside this policy are deleted. Empty means never delete automatically

trim and forget are keep policies in restic forget terms: keep_last, keep_hourly, keep_daily, keep_weekly, keep_monthly, keep_yearly take a count, and keep_within plus keep_within_hourly through keep_within_yearly take a duration such as "90d" or "2y5m7d3h". A session is kept when any rule matches. An empty forget policy disables automatic deletion. See Sessions for what each tier keeps and how the sweep runs.

FieldTypeDefaultMinDescription
enabledbooltrue-Record each tool call's file changes so file revert can undo them, locally and remotely. false turns recording and file revert off and keeps records already made. --no-snapshots overrides this for one run
max_bytes_mbu645121Most file data one change record may cover, and the size each workspace's change store is trimmed to. A record over it is refused and its call runs unrecorded. Values above the store's limit are lowered to it, and locally that limit is the default
max_filesu64500001Most files one change record may cover, counted after ignore rules. A record over it is refused and its call runs unrecorded. Values above the store's limit are lowered to it, and locally that limit is the default
max_file_bytes_mbu641001Largest file a change record stores. A larger file is left unrecorded, and a file revert across a call that changed it stops with a conflict. Values above the store's limit are lowered to it, and locally that limit is the default

A change record that would cover more than max_files files or max_bytes_mb of file data is refused, and its call runs without a record. A file over max_file_bytes_mb is left unrecorded. Values above the store's limits are lowered to them, and zero is rejected. See Sessions for what a record covers.

FieldTypeDefaultEnvDescription
enabledboolfalseCAUDRA_ENABLE_TELEMETRYMaster switch
metrics_exporterstringnoneOTEL_METRICS_EXPORTERWhere metrics go: otlp, console, none, or a comma-separated mix
logs_exporterstringnoneOTEL_LOGS_EXPORTERWhere events go: otlp, console, none, or a comma-separated mix
protocolstringunsetOTEL_EXPORTER_OTLP_PROTOCOLOTLP protocol: grpc, http/protobuf, or http/json. Required when an exporter is otlp
endpointstringunsetOTEL_EXPORTER_OTLP_ENDPOINTCollector endpoint. HTTP appends /v1/metrics and /v1/logs
headerstable{}OTEL_EXPORTER_OTLP_HEADERSExtra headers sent with every export
timeout_msinteger10000OTEL_EXPORTER_OTLP_TIMEOUTPer-export request timeout (ms)
compressionstringnoneOTEL_EXPORTER_OTLP_COMPRESSIONPayload compression: gzip or none
metrics_protocolstringunsetOTEL_EXPORTER_OTLP_METRICS_PROTOCOLMetrics-only protocol override
metrics_endpointstringunsetOTEL_EXPORTER_OTLP_METRICS_ENDPOINTMetrics-only endpoint, used verbatim with no path appended
metrics_headerstable{}OTEL_EXPORTER_OTLP_METRICS_HEADERSMetrics-only headers, merged over headers
metrics_timeout_msintegerunsetOTEL_EXPORTER_OTLP_METRICS_TIMEOUTMetrics-only request timeout (ms)
logs_protocolstringunsetOTEL_EXPORTER_OTLP_LOGS_PROTOCOLLogs-only protocol override
logs_endpointstringunsetOTEL_EXPORTER_OTLP_LOGS_ENDPOINTLogs-only endpoint, used verbatim with no path appended
logs_headerstable{}OTEL_EXPORTER_OTLP_LOGS_HEADERSLogs-only headers, merged over headers
logs_timeout_msintegerunsetOTEL_EXPORTER_OTLP_LOGS_TIMEOUTLogs-only request timeout (ms)
metrics_interval_msinteger60000OTEL_METRIC_EXPORT_INTERVALHow often metrics are exported (ms)
metrics_export_timeout_msinteger30000OTEL_METRIC_EXPORT_TIMEOUTDeadline for one metrics export, retries included (ms)
logs_interval_msinteger5000OTEL_LOGS_EXPORT_INTERVAL, OTEL_BLRP_SCHEDULE_DELAYHow often queued events are flushed (ms)
logs_max_queue_sizeinteger2048OTEL_BLRP_MAX_QUEUE_SIZEEvent queue capacity. Events are dropped and counted when it is full
logs_max_export_batch_sizeinteger512OTEL_BLRP_MAX_EXPORT_BATCH_SIZEMaximum events per export request
logs_export_timeout_msinteger30000OTEL_BLRP_EXPORT_TIMEOUTDeadline for one events export, retries included (ms)
metrics_temporalitystringdeltaOTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEMetric temporality: delta or cumulative
service_namestringcaudraOTEL_SERVICE_NAMEservice.name on the exported resource
resource_attributestable{}OTEL_RESOURCE_ATTRIBUTESExtra resource attributes, your place for team or environment labels
metrics_include_session_idbooltrueOTEL_METRICS_INCLUDE_SESSION_IDAttach session.id to metrics. Turn off to keep metric cardinality low
metrics_include_versionboolfalseOTEL_METRICS_INCLUDE_VERSIONAttach app.version to metrics
log_user_promptsboolfalseOTEL_LOG_USER_PROMPTSInclude prompt text in caudra.user_prompt events. Off by default
log_tool_detailsboolfalseOTEL_LOG_TOOL_DETAILSInclude tool input in caudra.tool_result events. Off by default
content_max_lengthinteger10240CAUDRA_OTEL_CONTENT_MAX_LENGTHCharacter cap on any logged prompt or tool input

Every field also has an environment variable, shown in the Env column, and the variable wins. See Telemetry for the full picture.

FieldTypeDefaultDescription
backendstringautoWhat creates and removes worktrees for /worktree: auto uses Herdr inside a Herdr pane, Orca inside an Orca terminal, and git elsewhere, git always runs git
directorystring<data dir>/worktreesWhere git-created worktrees go, as <directory>/<repository>/<branch>. A leading ~/ is your home directory

Inside a Herdr pane, auto asks Herdr to create and remove worktrees, so each one opens as a grouped Herdr workspace. Inside an Orca terminal, auto asks Orca, so each one appears in Orca's worktree list. directory applies only to worktrees git creates. See Worktrees for what /worktree does with each backend.

FieldTypeDefaultEnvDescription
modestringfallbackWORKCELL_WEBSEARCH_MODEHow the ready backends answer: single uses the first ready one, fallback tries them in order when one fails, and all lets the model pick one, trying them in order when it does not
backendsstring[]the comma-separated list in WORKCELL_WEBSEARCH_BACKEND, else ["exa-mcp"]WORKCELL_WEBSEARCH_BACKENDBackends in priority order: exa-mcp, searxng, exa, brave, kagi, or serpapi. A backend that is not set up correctly is skipped with a warning. An empty list turns websearch off

Global-only: a project caudra.toml that sets [websearch] fails to load, because the table holds credentials and decides where search queries go. Each backend reads its settings from its own table below. A key left unset reads the variable in its Env column, from Caudra's environment or the global .env, never a project .env. Prefer {env:NAME} or {file:PATH} references over a credential written in the file. Edits apply at once while the terminal UI runs, and /settings edits them for you. See Web search.

FieldTypeDefaultEnvDescription
urlstringunsetSEARXNG_URLSearXNG base URL, HTTPS when a credential is set and never with credentials in it
api_keystringunsetSEARXNG_API_KEYAPI key sent to SearXNG; set at most one of api_key, bearer_token, or user and password
bearer_tokenstringunsetSEARXNG_BEARER_TOKENBearer token sent to SearXNG
userstringunsetSEARXNG_USERBasic authentication user, set with password
passwordstringunsetSEARXNG_PASSWORDBasic authentication password, set with user
FieldTypeDefaultEnvDescription
api_keystringunsetEXA_API_KEYExa API key
FieldTypeDefaultEnvDescription
api_keystringunsetBRAVE_API_KEYBrave Search API key
FieldTypeDefaultEnvDescription
api_keystringunsetKAGI_API_KEYKagi API key
FieldTypeDefaultEnvDescription
api_keystringunsetSERPAPI_API_KEYSerpApi API key
enginestringunsetSERPAPI_ENGINESerpApi engine: google or bing

The [decisions] table holds the settings every decision endpoint shares: deadlines, logging, features, and thresholds. The endpoints themselves are [decisions.<name>] tables in the global providers.toml, and the engine runs only while one of them is active. caudra auth login --decision adds one and makes it active. See Decision endpoints. With no active endpoint, Caudra still validates this table. It starts no engine, sends no decision requests, reads no engine credentials, and leaves decision logs untouched. No passive feature or decision logging is enabled by default. Explicit workflow decide() calls and the MCP decide() and rerank() helpers need an active endpoint but no passive feature.

These settings are global-only. Projects may set individual features to "off", set log = false, or keep or shorten inherited log retention. Other project overrides are errors, even when they repeat a global value. Disabling globally required Auto screening or its active content screening restores prompting for eligible Auto calls. base_url, protocol, model, api_key_env, and allow_http are not accepted here. The error for each one shows the providers.toml table that replaces it. The upgrade comments out allow_remote, because configuring an endpoint is now the consent to send decision context to it.

FieldTypeDefaultDescription
timeout_msinteger10000Positive decision-request deadline in milliseconds, separate from shell execution timeouts. Tool search and every reranking feature except memory recall use rerank_timeout_ms instead.
rerank_timeout_msinteger3000Positive deadline in milliseconds for tool search and the reranking features, per 16 candidates a request judges. A request holds up to 64, so a full one waits up to four budgets. Memory recall keeps timeout_ms because it delays the start of a turn. A decide() or rerank() call from a workflow or a code snippet may ask for up to the larger of the two.
logbooleanfalseRetain bounded decision records in the local caudra.db.
log_retention_daysinteger90Positive retention period for decision records.
featurestable{}Per-feature modes below.
thresholdstable{}Probability thresholds, all finite and within 0–1 inclusive.

Both protocols send text only. OpenAI maps native boolean questions to predicates, retaining the true and false criteria in the instruction text. Answers normalize to the same typed results, so workflows and MCP snippets read the same answers under either protocol. A refusal fails the whole evaluation without applying partial answers.

Caudra retries HTTP 408, 429, and 5xx responses at most twice. Each retry waits for the delay the server requests in retry-after-ms or Retry-After, or else for an exponential backoff that starts near half a second. No retry waits past the request deadline, so under the default 10000 ms timeout_ms most retries need a short server-requested delay. Connection failures, 401, 422, and other client errors fail at once.

Tool search and the reranking features judge up to 64 candidates in one request and use rerank_timeout_ms (default 3000 ms) for every 16 of them instead. Memory recall keeps timeout_ms because it delays the start of a turn. A decide() or rerank() call from a workflow or an MCP snippet may ask for up to the larger of the two.

Redaction is best effort. Decision context can include commands, task text, tool output, and candidate descriptions. Review what you send and any exports before sharing them. See decision advice and logging.

off disables the feature. shadow collects predictions without applying them. advise adds caution or suggestions. enforce applies only the feature-specific behavior listed below, never permission grants or relaxed executor restrictions. Unsupported modes are configuration errors. YOLO bypasses permission advice, Auto screening, and permission-related shell-effect checks. Content screening, tool search, skill selection, goal prescreening, subagent routing, the question-tool nudge, and the reranking features still follow their feature settings in YOLO. Deterministic denies and hard restrictions still apply.

FeatureDefaultSupported modesBehavior beyond shadow
permission_adviceoffoff, shadow, adviseAdd warnings to an existing permission prompt without delaying the answer.
auto_screeningoffoff, shadow, enforceEscalate an eligible Auto call to a prompt on a flag or engine failure. Only enforce lets Auto run scripts and other lines that cannot be checked command by command. No answer channel means denial.
shell_effectoffoff, shadow, adviseWarn about possible project writes during Plan review only when shell_writes is configured. Never establish read-only authority.
content_screeningoffoff, shadow, advise, enforceScreen web, MCP and code output for text that tries to instruct the agent. advise adds caution to a flagged result and tightens upload/credential Auto screening for the session; the content stays available. enforce does the same, and also withholds from the model a flagged result, or one it could not screen in full, with a notice saying why. You still see the result on its card.
skill_suggestionsoffoff, shadow, adviseSuggest a shortlisted skill. The agent still chooses whether to load it.
goal_prescreenoffoff, shadow, enforceSkip an unlikely-to-pass goal evaluation within the continuation budget and continue work. Only the normal evaluator can certify completion.
subagent_routingoffoff, shadow, enforceChoose a model job for a new unpinned subagent from its task label, mode, profile, and a redacted prompt excerpt. Explicit jobs, models chosen on the task call, profile pins, and continuations keep their routing.
question_tool_nudgeoffoff, shadow, adviseAt a main-session handoff with a usable question tool, advise adds one visible reminder per user-input episode to ask a live user question through that tool. Shadow only evaluates. Uses a redacted, bounded request and reply excerpt; uncertainty and failures leave the reply unchanged.
memory_searchoffoff, shadow, enforceRerank the memory tool's keyword matches against the agent's query and omit those judged unrelated, saying how many were omitted. Sends the query and each candidate note's name, heading, and a redacted body excerpt.
history_searchoffoff, shadow, enforceRerank session history search's keyword matches against the agent's query, drop those judged unrelated, and return the rest best first. Sends the query and each candidate's kind, tool, date, session title, and a redacted excerpt.
memory_recalloffoff, shadow, adviseRemind the agent of at most three saved notes likely relevant to a new user message, a todo step it starts, an unmet goal, or the work after compaction, without loading them. Sends a redacted excerpt of the request and of the open todos, the previous request when this one is short, and an unmet goal with the evaluator's reason, and each keyword-matched note's name, heading, and redacted excerpt.
memory_duplicatesoffoff, shadow, adviseWhen a new memory note is written, name existing notes that may cover the same topic in the write receipt. The write itself is never blocked or changed. Sends redacted excerpts of the new note and of keyword-matched notes.
memory_nudgeoffoff, shadow, adviseJudge whether a new user message corrects the agent or states a rule for the project. When it does and agent.memory_nudges allows a reminder, the agent is reminded to save a note. Sends redacted excerpts of the message and of the reply before it.
compaction_retentionoffoff, shadow, enforceDuring compaction, keep the tool results most relevant to the active goal, open todos, and latest request instead of only the newest, and keep the most relevant part of a long result. Sends redacted goal, todo, and request excerpts, and each recent result's tool name with redacted input and output excerpts.
output_pointersoffoff, shadow, adviseWhen a saved tool output was truncated, point the agent to at most two omitted line ranges likely to matter. Nothing extra is removed. Sends redacted excerpts of the in-progress todos, latest request, tool input, and omitted lines.
source_code_contextoffoff, shadow, enforceIn local sessions, judge the first 64 code-context rows against the task and keep only those judged relevant, best first. Sends the task and each row's symbol name, kind, path, line span, and reference counts, never source text.

Flag thresholds trigger at or above the configured value. Goal prescreening uses an at-or-below comparison. Content screening requires both signals in the same chunk. After content is flagged, Auto uses 75% of auto_flag for upload and credential flags.

FieldTypeDefaultDescription
permission_flagfloat0.85Probability for a permission warning.
auto_flagfloat0.85Probability for escalating an eligible Auto call.
content_injectionfloat0.9Probability that sampled content attempts instruction injection.
content_addressed_to_agentfloat0.9Probability that sampled content addresses the agent.
routing_confidencefloat0.9Confidence required for skill suggestions. Subagent routing picks the Fast model when this much difficulty probability is at or below routine work, and the Best model when this much is on open-ended work. Memory duplicates and output pointers name a candidate only at or above this relevance probability.
goal_skip_belowfloat0.05Skip an evaluator at or below this completion probability, within the continuation budget.
shell_writesfloatunsetOptional project-write warning threshold. Omission leaves the warning disabled. No built-in enforcement threshold.
question_tool_nudgefloat0.85Minimum noul score for a question-tool reminder. Provisional, not a calibrated probability; advise only, and errors or uncertainty never reopen the turn.
relevance_floorfloat0.1Relevance probability below which an enforcing rerank feature prunes or demotes a candidate. Memory search omits it, compaction retention keeps a newer result in its place, and tool search ranks it after the candidates judged relevant, in keyword order. A list the engine could not judge is never emptied.
recall_confidencefloat0.75Relevance probability a note needs before memory recall names it in a reminder.

question_tool_nudge defaults to off and supports off, shadow, and advise. It checks an attempted final prose reply for a live request for the user to clarify, choose, supply information, or approve a next step. It needs a configured engine and a usable question tool with an answer channel in the main session. Subagents and frontends without that channel are excluded. YOLO does not disable it. Once the plan is saved in plan mode, the nudge stays off until the next user message. A question answer cannot leave plan mode, so the plan is approved through the plan menu, autopilot, or the client's mode switch.

In shadow, the prediction leaves the reply unchanged. In advise, a score at or above decisions.thresholds.question_tool_nudge (default 0.85) adds a normal system reminder asking the assistant to use question for the outstanding answer. The original reply stays in history. The reminder follows the show_reminders display preference and can occur at most once per genuine user-input episode. Synthetic reminders, retries, and resume do not renew that allowance. It never fabricates a tool call, an answer, or approval. While autopilot is engaged, its delegate answers the form that the reminder leads to.

The request contains redacted excerpts of the current visible reply and relevant user request within the 1,500-byte serialized state limit. Long replies retain an opening and a larger tail, so questions in the omitted middle can be missed. Errors, timeouts, invalid answers, and scores below the threshold leave the reply unchanged.

Tool search, memory_search, history_search, memory_recall, memory_duplicates, compaction_retention, output_pointers, and source_code_context use the engine as a reranker. A cheap first pass, such as keyword matching, picks the candidates. The engine then answers one true or false relevance question per candidate, and Caudra orders, prunes, or names candidates by the probability it returns. The feature table above lists what each one sends.

One request holds up to 64 candidates, each with an opaque ID such as c00, so the engine reads the shared question and query once. memory_search, history_search, and source_code_context judge up to 64 candidates; the others judge up to 16. A request waits one rerank_timeout_ms for every 16 candidates it holds. Candidate text is redacted and cut to a fixed size before it is sent, and every question tells the engine to treat the candidate as data rather than instructions. The request state, such as the query, task, or goal, stays within the 1,500-byte state limit.

Enforcing features compare each probability with thresholds.relevance_floor (default 0.1). Tool search only reorders, putting candidates at or above the floor first. source_code_context keeps the rows at or above the floor, best first, and leaves out the rest and the rows past the first 64, unless none clears the floor. memory_search omits matches below the floor and names them. history_search drops matches below the floor and returns the rest best first, as Ranking describes. compaction_retention keeps the same number of tool results as without the engine, choosing them by relevance, and never drops a result it could not otherwise drop. Advisory features name a candidate only at or above thresholds.routing_confidence (default 0.9).

When any request fails, is refused, times out, or is cancelled, or the decision service changes while it runs, the feature behaves as if it were off. In shadow, requests are sent and logged without effect. With log = true, an enforcing feature records rerouted when the order it used differs from the first pass, and an advisory feature records advised when it named a candidate. Workflows and MCP snippets can rerank their own candidates with rerank(): see workflows and MCP. See also memory relevance.

Only the permission question set currently supports a user-global file override: ~/.config/caudra/decisions/permission.json. It must be a regular JSON file no larger than 64 KiB, retain all required question IDs as noul, and pass question validation. It is read when a base URL is set and permission advice or Auto screening is enabled. Projects cannot supply this override. Other feature question sets have no file override. While the terminal UI runs, an edit to the file applies at once, and a file that fails to load keeps the questions in use, see Hot reload.

FieldTypeDefaultMinMaxDescription
turns_per_houru32201600Most turns automations may start in one session per rolling hour, shared by all of its automations
max_unattended_turnsu32unset110000Stop automation-started turns after this many since the last human input. Human input resets the count, and unset means no cap
allow_private_networkboolfalse--Let http() in automations reach loopback and private network hosts. Without it, automations reach public hosts only

Automations are experimental and need automations = true under [experimental]. Only the global caudra.toml may hold this table. Caudra rejects a project .caudra/caudra.toml that contains it, even an empty one, so a repository cannot raise these limits or let automations reach a private network.

FieldTypeDefaultMinMaxDescription
max_continuationsu32100010000Most continuations autopilot may send per engagement before it ends. 0 removes the limit
max_costf64unset--Most spending in USD per autopilot engagement, counting API-billed spend only. Must be positive, and unset means no cap
max_minutesu32unset1525600Most wall-clock minutes per autopilot engagement while the session is open. Unset means no cap
error_retriesu325020Retries for transient provider errors during an autopilot engagement

Limits for autopilot. Only the global caudra.toml may hold this table. Caudra rejects a project .caudra/caudra.toml that contains it, even an empty one.

FieldTypeDefaultDescription
allow_private_hostsstring[][]Exact HOST:PORT targets on loopback or private networks that webfetch may reach, such as "localhost:3000" or "[fd7a::1]:80". The port is required
allow_private_networksstring[][]Networks webfetch may reach on any port: loopback, private, cgnat, tailscale, or a CIDR such as "10.20.0.0/16". Every private address a name resolves to must be inside one

webfetch reaches only the public internet unless this table names private targets as well. It applies to local sessions. A remote workspace or a sandbox keeps the public-internet rule. Only the global caudra.toml may hold this table. Caudra rejects a project .caudra/caudra.toml that contains it, even an empty one, so a repository cannot point the model at your network.

[web]
allow_private_hosts = ["100.64.0.2:8787", "localhost:3000", "[fd7a::1]:80"]
allow_private_networks = ["tailscale", "10.20.0.0/16"]

An allow_private_hosts entry admits one host name or address on one port, whatever the name resolves to. An allow_private_networks entry admits any port, and a name only when every address it resolves to is public or inside a listed network. It takes a CIDR or one of these names:

NameAddresses
loopback127.0.0.0/8 and ::1
private10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and fc00::/7
cgnat100.64.0.0/10
tailscale100.64.0.0/10 and fd7a:115c:a1e0::/48

No name covers link-local addresses, which hold the cloud metadata service at 169.254.169.254. A CIDR can still name them. No entry admits an unspecified or a multicast address.

An http URL to a listed target stays http, because a local server often has no certificate. Other http URLs are still upgraded to https. A redirect may lead to a listed target only from a URL the list admitted too, so a public page cannot send webfetch into your network. When a local webfetch refuses a private target, its error names the HOST:PORT to add to allow_private_hosts and links to this section, so the model can tell you what to change. The hint is the same whether or not this table exists.

With a proxy set in HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY, a request to a listed target goes through the proxy unless NO_PROXY names its host. The proxy then resolves the name, so a special-use name such as localhost passes only through an allow_private_hosts entry. Each fetch reads the list once, when it starts, and an edit applies to the next fetch in every open session. See Hot reload.

The plugins table turns bundled features and plugins on or off and passes options to them. All bundled features are on by default. Set enabled = false to turn one off.

Each feature checks its own options at startup. A typo, a wrong type, or an unknown plugin name gives you a clear error right away.

enabled = false turns off the tools that key produced, under the names they are registered with today, so plugins.bash turns off shell and plugins.edit turns off file_edit and file_apply_patch. To name a tool directly, use agent.disabled_tools, described in Disabling tools.

This table is for built-in tools only, and it works without Lua. Your own plugins go in ~/.config/caudra/lua/ and need lua_plugins turned on. See Plugins.

[plugins.bash]
timeout_secs = 180
[plugins.websearch]
enabled = false

file_index executes as a native Workcell tool, and this table keeps the plugins.index key it was configured under. The file-size limit accepts 1 through 16 MiB to bound parser memory and work.

FieldTypeDefaultMinMaxDescription
max_file_size_mbinteger2116Refuse to index files larger than this many MiB.

skill executes as a native Caudra tool. This table keeps its existing configuration key.

FieldTypeDefaultDescription
plugin_devbooleanfalseOffer the builtin caudra-plugin-dev skill for writing caudra plugins. Needs experimental.lua_plugins.
workflow_devbooleantrueOffer the builtin caudra-workflow-dev skill for writing and running workflows. Needs experimental.workflows.
automation_devbooleantrueOffer the builtin caudra-automation-dev skill for writing automations. Needs experimental.automations.
docsbooleantrueOffer the builtin caudra-docs skill: this build's user documentation, loaded one page or section at a time.
pstackbooleanfalseOffer the bundled pstack: its skills as the pstack skill, the /pstack: commands, the pstack-poteto-agent and pstack-comment-sicko task profiles, and its scripts as pstack calls in code.
mattpocockbooleanfalseOffer Matt Pocock's bundled skills (grilling, TDD, diagnosing bugs, code review, specs, tickets): the mattpocock skill and the /mattpocock: commands.
emilbooleanfalseOffer Emil Kowalski's bundled design-engineering skills (animation, motion review, UI stress tests, prototypes, mobile polish, Swift): the emil skill and the /emil: commands.

task executes as a native Caudra tool. This table keeps its existing configuration key.

FieldTypeDefaultMinDescription
max_concurrentinteger81Max concurrently running subagents.

If a value is below its minimum or above its maximum, Caudra shows a ConfigError with the field name, the value, and the bound it crossed.

Caudra follows platform directory conventions. On Linux and macOS that is XDG. On Windows, config, data, state, and logs all live under Roaming AppData (Windows has no separate state dir in this layout).

PurposeLinux / macOSWindows
Config~/.config/caudra/%APPDATA%\caudra\
Data~/.local/share/caudra/%APPDATA%\caudra\
State~/.local/state/caudra/%APPDATA%\caudra\
Logs~/.local/logs/caudra/%APPDATA%\caudra\
Cache~/.cache/caudra/%LOCALAPPDATA%\caudra\
Scratch$TMPDIR/caudra/%TEMP%\caudra\

Config holds caudra.toml, permissions.toml, mcp.toml, providers.toml, workcell.toml, sandboxes.toml, init.lua, .env and commands/. State holds sessions, the images and PDFs they refer to in media/, auth tokens, memories, plans, model-job bindings, sandbox lifecycle records, transfer recovery journals, and the backups Caudra saves before it upgrades a file. The install script puts the binary under %LOCALAPPDATA%\caudra on Windows; that is separate from these runtime dirs.

Scratch holds work that belongs outside your project, such as a file the model writes while thinking or a temporary a command leaves behind. Each project gets its own subdirectory, named by the project directory plus a three-word phrase derived from its path, as in caudra-heroic-easy-grouse. Two checkouts sharing a name get different phrases, so they cannot overwrite each other. The phrase is derived rather than drawn at random, so a project returns to the same directory on every run. Caudra creates it at startup and points TMPDIR, TMP, and TEMP at it, so every command Caudra runs puts its own temporary files there instead of the shared temp root. The model is told the path, and writing anywhere under the scratch root needs no approval. Paths beside the root still ask.

The choice of subdirectory is fixed when Caudra starts. /cd moves the project without moving it, which is why approval covers the whole root rather than one project's share of it. Directories are owner-only, and Caudra refuses to use one that turns out to be a symlink. Nothing sweeps them, so they live as long as your system keeps its temp root.

State that belongs to one project sits under …/state/caudra/projects/<project-id>/, where the id is the project directory name plus a hash of its path. Memory notes and plan-mode documents both live there, so removing that directory clears everything Caudra kept for the project.

Development builds compiled with debug assertions use caudra-debug for every platform directory. This keeps global config, sessions, auth, logs, and caches separate from release builds. Per-project .caudra/ directories remain shared.

Set CAUDRA_NAMESPACE to choose the directory name yourself instead of letting the build profile pick it. The value is a single directory name, so CAUDRA_NAMESPACE=caudra-review reads and writes ~/.config/caudra-review/, ~/.local/state/caudra-review/, and the rest. Use it to give a run its own config and session store, or to point a debug build at your release directories. A value that cannot be a directory name, such as one holding a path separator or .., stops Caudra with an error rather than falling back. An empty value counts as unset. Per-project .caudra/ directories are unaffected.

Each TOML config file starts with a top-level version, the version of its format. A file without the key predates versioning, so Caudra reads it as version 1 and adds the key when it upgrades the file. workcell.toml and sandboxes.toml always required the key and reject a file without it. A build that finds a newer version than it reads refuses the file instead of guessing what it means, with an error that says the file needs a newer Caudra and where its backup is.

FileVersionWithout versionNewer than this build reads
caudra.toml5Read as version 1Caudra stops with an error
permissions.toml2Read as version 1Fails closed. Tool calls are denied until the file is fixed
mcp.toml2Read as version 1Servers from that file do not start, and Caudra shows the error
providers.toml1Read as version 1Caudra stops with an error
plugin.toml1Read as version 1Every permission of that plugin is denied
workcell.toml1RejectedRejected with an error
sandboxes.toml1RejectedRejected with an error

When a release changes a format, it raises the version and Caudra upgrades older files as it reads them. A renamed key or tool name gets its new name, and a removed key is commented out rather than deleted. If an old key and its new name are both set, or the upgraded file would not load, Caudra leaves the file unchanged and shows the error.

init.lua, which runs only with Lua plugins turned on, has no version because it is a script. To share one init.lua across releases, branch on caudra.version().

At startup, Caudra rewrites each global file that is behind its format, after it saves a backup. It does this only while no other Caudra process is running, because an older Caudra that is still open would refuse the upgraded file the next time it reloads it. While another session is open, Caudra reads the file upgraded in memory and leaves it unchanged on disk. A notice names the open sessions, and the next start tries again. Until then, saving to that file from inside Caudra fails with an error that says how to finish the upgrade. That covers /env, switching a feature in /decisions, turning a server on or off in /mcp, saving a key in /login, and the /sandbox manager.

Caudra never rewrites the files in a project's .caudra/ directory on its own, because they are usually committed and your teammates may run an older Caudra. It reads them upgraded in memory and shows a notice that names the command to update them.

caudra config migrate upgrades the global files on demand, and --project adds the project files of the current directory. It prints what changed in each file and where the backup is. While another Caudra process is running it writes nothing, lists the open sessions, and exits with an error. --dry-run prints each change with a diff and writes nothing, so it works while sessions are open. After --project, teammates need the same Caudra release or a newer one to read the files.

Every line the upgrade changes gets a comment above it with the Caudra release, the date, what changed, and why. The comments you wrote on that line stay below a lone #. A removed key stays as a commented-out line. For example, this file:

# My settings
[ui.tool_output_lines]
# keep code output short
python_execution = 40
[agent]
defer_builtin_tools = true

reads like this after the upgrade:

# My settings
# Added by Caudra 0.2.0-preview.12 on 2026-10-20: the format version of this file, which Caudra now requires.
version = 5
[ui.tool_output_lines]
# Upgraded by Caudra 0.2.0-preview.12 on 2026-10-20: renamed `ui.tool_output_lines.python_execution` to `code`, because the `code` tool now runs plain computation.
#
# keep code output short
code = 40
[agent]
# Upgraded by Caudra 0.2.0-preview.12 on 2026-10-20: retired `agent.defer_builtin_tools`, because the tools it deferred are now `code` modules (`image`, `host`, `workflow`, `automation`).
# defer_builtin_tools = true

Before Caudra rewrites a file, it copies the original byte for byte into backups/ in the state directory. Backups are owner-only, and Caudra never deletes them. The time in a name is UTC, so a later upgrade never overwrites an earlier backup.

BackupPath under backups/
A global config fileconfig/global/<file>.v<from>.<YYYYMMDDTHHMMSSZ>.bak
A project config fileconfig/projects/<project-id>/<file>.v<from>.<YYYYMMDDTHHMMSSZ>.bak
caudra.db before a schema upgradecaudra.db.v<from>.bak
caudra.db before caudra permissions repair-review --applycaudra.db.permission-review-<ID>.bak

<from> is the version the file had, and <project-id> is the same id as in the project's state directory. Database backups that earlier releases made stay beside caudra.db.

A database backup from schema 44 on refers to its images and PDFs in media/ rather than holding them. Prune never removes a media file that a backup refers to, so backups keep their media, and caudra storage prune reports the space that only backups keep. To restore such a backup, copy it over caudra.db in a state directory that still has the media/ directory the backup was made with. Prune caches the hashes each backup refers to in <backup>.media, and deletes that file once you delete its backup.

An older Caudra cannot read a file at a newer version. To go back to an older release, copy the backup over the file, for example:

Terminal window
cp ~/.local/state/caudra/backups/config/global/caudra.toml.v1.20261020T101500Z.bak ~/.config/caudra/caudra.toml

caudra rollback restores only the previous binary. The restored file loses any change made after the upgrade. The next time a newer Caudra starts with no other session open, it upgrades the file again.

On top of the project instruction files Caudra loads from the git root down to the cwd (AGENTS.md, CLAUDE.md, and friends; see Context), you can add:

  • AGENTS.local.md in any of those project directories for per-directory preferences (gitignored)
  • ~/.config/caudra/AGENTS.md for preferences that apply to all projects

All of these are added to the system prompt at the start of every session.

The memory tool keeps project notes as Markdown files under the state directory, scoped per project:

…/state/caudra/projects/<project-id>/memories/

That is ~/.local/state/caudra/… on Linux and macOS and %APPDATA%\caudra\… on Windows. The Memory model summarizes the notes in the background for the view in the system prompt. Set agent.summarize_memory to false to stop that spend. Memory covers the journal, the view, and the /memory inspector.

Related pages: Skills, CLI, Providers.

Website privacy and analytics