Configuration
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:
- Built-in defaults
- Global
caudra.toml - Global
init.lua, only with Lua plugins turned on - Project
.caudra/caudra.toml - Project
.caudra/init.lua, only with Lua plugins turned on - 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.
Config files
Section titled “Config files”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.
| File | Scope | Holds | Kept separate because | Reference |
|---|---|---|---|---|
caudra.toml | global, project | settings, and in the global file the [experimental] switches | It is the main file, and only you write it | caudra config example caudra |
permissions.toml | global, project | permission rules for tools and MCP servers | It has its own error rule: a file that fails to load denies every tool call | caudra config example permissions |
mcp.toml | global, project | MCP servers | Caudra writes it when /mcp turns a server on or off, and it starts processes | caudra config example mcp |
providers.toml | global | model providers, their models, and their accounts | caudra auth login and caudra auth logout write it, and it can hold API keys | caudra config example providers |
workcell.toml | global | profiles for direct remote Workcell connections (needs experimental.remote_workcell) | It decides where credentials go, so it has to be a private file | caudra config example workcell |
sandboxes.toml | global | managed sandbox providers, networks, transfers, and profiles (needs experimental.sandboxes) | The /sandbox manager writes it, and it has to be a private file | caudra config example sandboxes |
init.lua | global, project | Lua code that sets up plugins (needs experimental.lua_plugins) | It is a program, not settings | - |
.env | global, project | environment variables, such as API keys, for any the environment does not set | It holds secrets | - |
commands/ | global, project | custom slash commands, one Markdown file each | Each 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.
Example
Section titled “Example”[ui]splash_animation = truemouse_scroll_lines = 5theme = "tokyonight"
[ui.tool_output_lines]bash = 8read = 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 = 4All 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.
Environment variables
Section titled “Environment variables”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, andworkcell.toml.sandboxes.tomlkeeps 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.envnever supplies a value. - An unset variable is an error that names the file, the line, and the variable. At startup, a bad
caudra.tomlstops startup and a badproviders.tomlexits. A badpermissions.tomlfails closed and denies every tool call. A badmcp.tomlloads none of its servers, and/mcpshows 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
/mcpturning a server off orcaudra auth loginadding a provider, the reference stays in the file rather than its value.
Values from files
Section titled “Values from files”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-tokenstarts at the root of the config file's drive, and UNC paths such as\\server\share\otel-tokenwork. - 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.
Hot reload
Section titled “Hot 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 changed | When 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.toml | Before the next tool call. |
mcp.toml | At 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.toml | The 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.json | At once. See Question overrides. |
| Skills | At once. |
| System prompt profiles | From the next turn. |
| Custom commands | At once. |
| Workflows and automations | Caudra reads them again each time it lists, launches, or arms one. |
workcell.toml and sandboxes.toml | After /reload. |
init.lua | After /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} reads | When the config file that names them reloads. Caudra does not watch them. |
Project .env | After a restart. |
A remote workspace session keeps the permissions and commands of its workspace. Its project files apply after /reload.
The prompt cache
Section titled “The prompt cache”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.
When Caudra rebuilds
Section titled “When Caudra rebuilds”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:
| Moment | Why then |
|---|---|
| Compaction | The conversation is new. |
| Switching model or provider | Each model keeps its own cache. |
| Switching the system prompt profile | The system prompt changes with it. |
| Changing the thinking level | Claude's cache of the conversation does not survive a change to the thinking settings. |
| Switching mode | The 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 expires | Claude 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.
What the model is told
Section titled “What the model is told”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
skilltool 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.
When a file breaks
Section titled “When a file breaks”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.
Project files that grant access
Section titled “Project files that grant access”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.
Examples
Section titled “Examples”Each one starts in the middle of a session, with the cache warm.
Add an MCP server
Section titled “Add an MCP server”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.
Turn off an MCP server
Section titled “Turn off an MCP server”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.
Switch to plan mode
Section titled “Switch to plan mode”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.
Disable a tool
Section titled “Disable a tool”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.
Edit a system prompt profile
Section titled “Edit a system prompt profile”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.
Add a skill
Section titled “Add a skill”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.
Edit an instruction file
Section titled “Edit an instruction file”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.
Break the permissions file
Section titled “Break the permissions file”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.
Put a file back
Section titled “Put a file back”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.
Experimental features
Section titled “Experimental features”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 = trueautomations = true| Key | Default | Turns on |
|---|---|---|
workflows | false | Workflows: the workflow tool, the workflow commands and inspector, and the caudra-workflow-dev skill. |
sandboxes | false | Managed 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_workcell | false | Direct remote Workcell connections: the --workcell-* flags and caudra auth workcell. |
lua_plugins | false | Every 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_messaging | false | Local 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. |
automations | false | Automations: 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.
Migrating from Lua settings
Section titled “Migrating from Lua settings”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.
Full Reference
Section titled “Full Reference”Top-level
Section titled “Top-level”| Field | Type | Default | Description |
|---|---|---|---|
always_yolo | bool | false | Start every session with YOLO mode (skip permission prompts, deny rules still apply); global config only |
always_auto | bool | false | Start 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_fast | bool | false | Start every session with fast mode, on the models that sell a fast tier (ignored otherwise) |
always_thinking | bool | string | unset | Start every session with extended thinking (true/"adaptive", "off", an effort level ("minimal" to "max"), or a token budget) |
| Field | Type | Default | Env | Min | Description |
|---|---|---|---|---|---|
splash_animation | bool | true | - | - | Show splash animation on startup |
scrollbar | bool | true | - | - | Show vertical scrollbar in scrollable areas |
touch | string | auto | - | - | 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 |
notifications | string | auto | - | - | 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 |
math | string | unicode | - | - | How LaTeX maths renders: unicode (approximate with Unicode) or raw (show the LaTeX source) |
mermaid | string | unicode | - | - | How mermaid flowcharts render: unicode (draw them with box-drawing characters) or off (leave the fence as code) |
inline_images | string | auto | - | - | How the transcript draws images that view_image reads, image_generate saves, and markdown names with : 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_ms | u64 | 10000 | - | - | Duration of ordinary status-bar messages (ms). Confirmation prompts use a fixed 3-second window |
which_key_delay_ms | u64 | 250 | - | - | How long Ctrl+X waits before listing the chords it can still reach (ms). 0 shows the list at once |
tooltips | bool | true | - | - | 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_char | u64 | 4 | - | - | Typewriter effect speed (ms/char) |
mouse_scroll_lines | u32 | 3 | - | 1 | Lines per mouse wheel scroll |
scroll_card_lines | u32 | 10 | - | - | 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_collapsed | string[] | ["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_lines | u32 | 20 | - | 1 | Maximum visible input lines |
show_thinking | bool | true | - | - | 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_lines | u32 | 10 | - | - | 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_reminders | bool | true | - | - | 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_decisions | bool | true | - | - | 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_format | String | system | - | - | Clock format for timestamps: "12h", "24h", or "system" (follow the OS preference, 24h when unknown) |
update_check | bool | true | CAUDRA_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_channel | string | auto | - | - | 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_update | bool | true | - | - | 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_mode | string | plan | - | - | 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 |
theme | string | unset | - | - | Name of the color theme to load at startup, overriding the theme you last picked with /theme. Unset keeps your last pick |
theme_light | string | unset | - | - | 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 |
ui.theme
Section titled “ui.theme”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:
printf '\033[?2031h'; mosh user@host; printf '\033[?2031l'ui.theme_light
Section titled “ui.theme_light”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.
ui.update_check
Section titled “ui.update_check”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.
ui.update_channel
Section titled “ui.update_channel”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.
ui.changelog_on_update
Section titled “ui.changelog_on_update”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.
ui.tool_output_lines
Section titled “ui.tool_output_lines”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.
| Field | Default | Tools |
|---|---|---|
bash | 5 | shell |
code | 5 | code |
task | 12 | task, task_control |
index | 3 | file_index, source_code_context, source_code_refs |
grep | 3 | file_grep, file_glob |
read | 3 | file_read |
write | 7 | file_write, file_edit, file_apply_patch, image_generate, memory, plan |
web | 3 | webfetch, websearch |
other | 3 | automation, batch, execution_environment, list_sessions, publish_message, question, read_topic, request_secret, send_message, skill, todo_write, tool_output, view_image, work_assignment, workflow |
| Field | Type | Default | Min | Description |
|---|---|---|---|---|
system_prompt_profile | String | builtin | - | Default user system prompt profile from the system-prompts config directory |
max_output_bytes | usize | 51200 | 1024 | Host-enforced default max tool-result size (bytes) |
max_output_lines | usize | 2000 | 10 | Host-enforced default max tool-result lines |
compaction_buffer | u32 | string | 20%, 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_instructions | String | unset | - | Extra instructions appended to the compaction summary prompt |
post_compaction_instructions | String | unset | - | Extra instructions the agent receives after any compaction (e.g. re-read plan.md) |
compaction_requirements | bool | true | - | 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_turns | u32 | 0 | - | Committed main-agent response groups between unchanged active background-work reminders; 0 disables periodic refresh only, not state-change or post-compaction reminders |
todo_reminder | bool | true | - | 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_compactions | u32 | 2 | - | 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_minutes | u32 | 30 | - | 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_choice | bool | true | - | 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_questions | bool | true | - | 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_secs | u64 | 600 | 1 | How 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_eta | bool | true | - | 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_titles | bool | true | - | Name a new session by summarizing its first prompt with the Title model |
summarize_memory | bool | true | - | 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_nudges | bool | true | - | 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_check | bool | true | - | 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_repair | bool | true | - | Repair malformed tool JSON syntax locally, with one bounded isolated model fallback; independent of eager dispatch |
eager_tool_dispatch | bool | true | - | Start tools and batch children as soon as their complete arguments arrive, instead of waiting for the whole message |
shell_output_filter | bool | true | - | Filter completed model-facing shell output with built-in rules |
shell_workdir_redirect | bool | true | - | 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_redirect | string | enforce | - | 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_model | string | sunburst | - | 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_warming | string | off | - | 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_interrupted | string | auto | - | 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_hours | u64 | 24 | 1 | Hours after which resume_interrupted = "auto" asks before resuming interrupted work instead of resuming it |
continual_learning | bool | true | - | 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_targets | string[] | ["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_tools | string[] | [] | - | 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 |
agent.messaging
Section titled “agent.messaging”| Field | Type | Default | Min | Description |
|---|---|---|---|---|
inbound | string | auto | - | 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_minute | usize | 64 | 1 | Most peer messages a session admits per minute from all senders together. Project settings may only lower it |
sender_per_minute | usize | 16 | 1 | Most peer messages a session admits per minute from one sending session. Project settings may only lower it |
publish_per_minute | usize | 16 | 1 | Most topic and broadcast publications a session sends per minute. Project settings may only lower it |
max_fanout | usize | 32 | 1 | Most live sessions one topic or broadcast publication reaches. Extra recipients are skipped and counted. Project settings may only lower it |
history_days | u64 | 30 | 1 | Days 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_messages | u64 | 50000 | 1 | Most messages the shared message history keeps; the oldest go first. Global config only |
agent.shell_env
Section titled “agent.shell_env”| Field | Type | Default | Description |
|---|---|---|---|
pass | string[] | [] | 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 |
set | table | {} | 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.
agent.steering
Section titled “agent.steering”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.
| Field | Type | Default | Min | Max | Description |
|---|---|---|---|---|---|
enabled | boolean | true | - | - | Master switch for automatic steering, including truncation recovery and repeat-policy blocking. |
max_recoveries | integer | 32 | 0 | 1024 | Corrective continuations per externally initiated invocation. Zero prevents optional recovery continuations. |
max_advisories | integer | 4 | 0 | 1024 | Advisory injections per invocation. Zero suppresses advisories. |
max_stalled_turns | integer | 5 | 0 | 1024 | Consecutive turns carrying neither a tool call nor visible text before the run ends, whichever rule intervened. Zero disables the backstop. |
rules | table | {} | - | - | Overrides by rule name, listed below. Omission uses built-in defaults. |
models | table | {} | - | - | Up to 256 exact provider/model-id keys, each with its own overrides. |
Rule in rules | Behavior |
|---|---|
truncation | Continue output cut off by the response token limit, up to 3 corrective requests per externally initiated invocation. |
empty_response | Continue after empty output, with separate per-episode limits after recent tools and while idle. |
repeated_tool_call | Refuse the third consecutive identical top-level tool name/input before execution. Native batch children do not acquire this hard blocker. |
protocol_mismatch | Correct an explicit provider tool-use indication with no actual tool calls, up to 2 continuations per episode. |
missing_task_report | Request a missing task summary or required structured report, up to 2 corrections. |
abandoned_turn | Continue 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. |
repetition | Advise on short exact tool cycles, including normalized native batch leaf calls, or repeated normalized assistant text. |
tool_planning | Advise 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_paths | Suggest 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.
Rule fields
Section titled “Rule fields”Each table at agent.steering.rules.<rule> accepts these common fields:
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Explicit false disables this rule. |
prompt | string | unset | Use 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 rules | Default | Range | Unit and meaning |
|---|---|---|---|
truncation.max_attempts | 3 | 1–1024 | Actual truncation-correction requests per externally initiated invocation, shared across truncation episodes. |
empty_response.max_after_tools | 3 | 1–1024 | Empty-output continuations per episode after recent tool results. |
empty_response.max_idle | 2 | 1–1024 | Empty-output continuations per episode without recent tool results. |
empty_response.max_barren | 1 | 1–1024 | Continuations 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_window | 5 | 1–4096 | Non-padding history messages inspected for recent tool results. |
repeated_tool_call.threshold | 3 | 2–1024 | Consecutive identical top-level calls. Refuse the call reaching this threshold. |
protocol_mismatch.max_attempts | 2 | 1–1024 | Protocol corrective continuations per episode. |
missing_task_report.max_attempts | 2 | 1–1024 | Additional report-correction prompts per task invocation. |
abandoned_turn.max_attempts | 2 | 1–1024 | Continuations per episode after a turn that announced work instead of doing it. |
repetition.window | 24 | 1–4096 | Recent normalized leaf tool calls retained for cycle detection. |
repetition.cycle_repeats | 3 | 2–1024 | Exact repetitions of a tool cycle needed for an advisory. |
repetition.max_cycle | 4 | 2–1024 | Maximum cycle length in leaf calls. Candidate cycle lengths start at 2. |
repetition.text_window | 8 | 1–4096 | Recent completed assistant responses retained for text repetition. |
repetition.text_repeats | 3 | 2–1024 | Matching nontrivial normalized assistant responses needed for an advisory. |
repetition.cooldown | 3 | 1–1024 | Completed model responses between this rule's advisories. |
tool_planning.after_calls | 6 | 1–1024 | Number of most recent leaf tool calls that must all have failed since the last response containing a successful result. |
tool_planning.after_responses | 3 | 1–1024 | Distinct completed model responses represented by those failed calls. |
tool_planning.cooldown | 3 | 1–1024 | Completed model responses between this rule's advisories. |
relative_paths.min_saved_chars | 12 | 1–1024 | Characters 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.
Global and exact-model overrides
Section titled “Global and exact-model overrides”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 = truetext_repeats = 4
[agent.steering.models."openai/gpt-5".rules.tool_planning]after_calls = 8prompt = "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:
- Start with built-in policy and rule defaults.
- Apply explicit global fields and rule fields.
- 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.
Budgets and safety boundaries
Section titled “Budgets and safety boundaries”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.
provider
Section titled “provider”| Field | Type | Default | Min | Description |
|---|---|---|---|---|
default_model | String | unset | - | Default model identifier (e.g. anthropic/claude-sonnet-4-6) |
allowed_models | string[] | [] | - | Glob patterns for permitted qualified model specs; empty permits all models |
excluded_models | string[] | [] | - | Glob patterns for excluded qualified model specs; exclusions take precedence |
connect_timeout_secs | u64 | 10 | 1 | HTTP connect timeout (seconds) |
stream_timeout_secs | u64 | 300 | 10 | Longest the server may send nothing before the request is abandoned (seconds) |
models
Section titled “models”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
refresh | bool | true | CAUDRA_MODELS_REFRESH | Check 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 |
url | String | unset | - | 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 |
storage
Section titled “storage”| Field | Type | Default | Env | Min | Description |
|---|---|---|---|---|---|
max_log_bytes_mb | u64 | 200 | - | 1 | Max total log size (MB) |
max_log_files | u32 | 10 | - | 1 | Max number of log files to keep |
max_eager_load_mb | u64 | 1024 | CAUDRA_MAX_EAGER_LOAD_MB | 64 | Largest 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_level | string | info | - | - | Minimum severity written to the log file: trace, debug, info, warn, or error. RUST_LOG overrides it |
input_history_size | usize | 100 | - | 10 | Number of input history entries to retain |
ephemeral | bool | false | - | - | Store session data in a temporary directory removed when Caudra exits |
[storage.retention]
Section titled “[storage.retention]”| Field | Type | Default | Description |
|---|---|---|---|
group_by | string | directory | Evaluate policies per working directory (directory) or across every session (none) |
sweep_interval_hours | u64 | 24 | Hours 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 |
trim | table | {} | Sessions outside this policy lose file revert, retained tool outputs, archives, and large rich outputs but stay resumable. Empty means never trim automatically |
forget | table | {} | 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.
[storage.snapshots]
Section titled “[storage.snapshots]”| Field | Type | Default | Min | Description |
|---|---|---|---|---|
enabled | bool | true | - | 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_mb | u64 | 512 | 1 | Most 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_files | u64 | 50000 | 1 | Most 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_mb | u64 | 100 | 1 | Largest 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.
[telemetry]
Section titled “[telemetry]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
enabled | bool | false | CAUDRA_ENABLE_TELEMETRY | Master switch |
metrics_exporter | string | none | OTEL_METRICS_EXPORTER | Where metrics go: otlp, console, none, or a comma-separated mix |
logs_exporter | string | none | OTEL_LOGS_EXPORTER | Where events go: otlp, console, none, or a comma-separated mix |
protocol | string | unset | OTEL_EXPORTER_OTLP_PROTOCOL | OTLP protocol: grpc, http/protobuf, or http/json. Required when an exporter is otlp |
endpoint | string | unset | OTEL_EXPORTER_OTLP_ENDPOINT | Collector endpoint. HTTP appends /v1/metrics and /v1/logs |
headers | table | {} | OTEL_EXPORTER_OTLP_HEADERS | Extra headers sent with every export |
timeout_ms | integer | 10000 | OTEL_EXPORTER_OTLP_TIMEOUT | Per-export request timeout (ms) |
compression | string | none | OTEL_EXPORTER_OTLP_COMPRESSION | Payload compression: gzip or none |
metrics_protocol | string | unset | OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Metrics-only protocol override |
metrics_endpoint | string | unset | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Metrics-only endpoint, used verbatim with no path appended |
metrics_headers | table | {} | OTEL_EXPORTER_OTLP_METRICS_HEADERS | Metrics-only headers, merged over headers |
metrics_timeout_ms | integer | unset | OTEL_EXPORTER_OTLP_METRICS_TIMEOUT | Metrics-only request timeout (ms) |
logs_protocol | string | unset | OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Logs-only protocol override |
logs_endpoint | string | unset | OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Logs-only endpoint, used verbatim with no path appended |
logs_headers | table | {} | OTEL_EXPORTER_OTLP_LOGS_HEADERS | Logs-only headers, merged over headers |
logs_timeout_ms | integer | unset | OTEL_EXPORTER_OTLP_LOGS_TIMEOUT | Logs-only request timeout (ms) |
metrics_interval_ms | integer | 60000 | OTEL_METRIC_EXPORT_INTERVAL | How often metrics are exported (ms) |
metrics_export_timeout_ms | integer | 30000 | OTEL_METRIC_EXPORT_TIMEOUT | Deadline for one metrics export, retries included (ms) |
logs_interval_ms | integer | 5000 | OTEL_LOGS_EXPORT_INTERVAL, OTEL_BLRP_SCHEDULE_DELAY | How often queued events are flushed (ms) |
logs_max_queue_size | integer | 2048 | OTEL_BLRP_MAX_QUEUE_SIZE | Event queue capacity. Events are dropped and counted when it is full |
logs_max_export_batch_size | integer | 512 | OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | Maximum events per export request |
logs_export_timeout_ms | integer | 30000 | OTEL_BLRP_EXPORT_TIMEOUT | Deadline for one events export, retries included (ms) |
metrics_temporality | string | delta | OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | Metric temporality: delta or cumulative |
service_name | string | caudra | OTEL_SERVICE_NAME | service.name on the exported resource |
resource_attributes | table | {} | OTEL_RESOURCE_ATTRIBUTES | Extra resource attributes, your place for team or environment labels |
metrics_include_session_id | bool | true | OTEL_METRICS_INCLUDE_SESSION_ID | Attach session.id to metrics. Turn off to keep metric cardinality low |
metrics_include_version | bool | false | OTEL_METRICS_INCLUDE_VERSION | Attach app.version to metrics |
log_user_prompts | bool | false | OTEL_LOG_USER_PROMPTS | Include prompt text in caudra.user_prompt events. Off by default |
log_tool_details | bool | false | OTEL_LOG_TOOL_DETAILS | Include tool input in caudra.tool_result events. Off by default |
content_max_length | integer | 10240 | CAUDRA_OTEL_CONTENT_MAX_LENGTH | Character 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.
[worktrees]
Section titled “[worktrees]”| Field | Type | Default | Description |
|---|---|---|---|
backend | string | auto | What 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 |
directory | string | <data dir>/worktrees | Where 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.
[websearch]
Section titled “[websearch]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
mode | string | fallback | WORKCELL_WEBSEARCH_MODE | How 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 |
backends | string[] | the comma-separated list in WORKCELL_WEBSEARCH_BACKEND, else ["exa-mcp"] | WORKCELL_WEBSEARCH_BACKEND | Backends 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.
[websearch.searxng]
Section titled “[websearch.searxng]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
url | string | unset | SEARXNG_URL | SearXNG base URL, HTTPS when a credential is set and never with credentials in it |
api_key | string | unset | SEARXNG_API_KEY | API key sent to SearXNG; set at most one of api_key, bearer_token, or user and password |
bearer_token | string | unset | SEARXNG_BEARER_TOKEN | Bearer token sent to SearXNG |
user | string | unset | SEARXNG_USER | Basic authentication user, set with password |
password | string | unset | SEARXNG_PASSWORD | Basic authentication password, set with user |
[websearch.exa]
Section titled “[websearch.exa]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
api_key | string | unset | EXA_API_KEY | Exa API key |
[websearch.brave]
Section titled “[websearch.brave]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
api_key | string | unset | BRAVE_API_KEY | Brave Search API key |
[websearch.kagi]
Section titled “[websearch.kagi]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
api_key | string | unset | KAGI_API_KEY | Kagi API key |
[websearch.serpapi]
Section titled “[websearch.serpapi]”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
api_key | string | unset | SERPAPI_API_KEY | SerpApi API key |
engine | string | unset | SERPAPI_ENGINE | SerpApi engine: google or bing |
decisions
Section titled “decisions”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.
| Field | Type | Default | Description |
|---|---|---|---|
timeout_ms | integer | 10000 | Positive 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_ms | integer | 3000 | Positive 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. |
log | boolean | false | Retain bounded decision records in the local caudra.db. |
log_retention_days | integer | 90 | Positive retention period for decision records. |
features | table | {} | Per-feature modes below. |
thresholds | table | {} | 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.
decisions.features
Section titled “decisions.features”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.
| Feature | Default | Supported modes | Behavior beyond shadow |
|---|---|---|---|
permission_advice | off | off, shadow, advise | Add warnings to an existing permission prompt without delaying the answer. |
auto_screening | off | off, shadow, enforce | Escalate 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_effect | off | off, shadow, advise | Warn about possible project writes during Plan review only when shell_writes is configured. Never establish read-only authority. |
content_screening | off | off, shadow, advise, enforce | Screen 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_suggestions | off | off, shadow, advise | Suggest a shortlisted skill. The agent still chooses whether to load it. |
goal_prescreen | off | off, shadow, enforce | Skip an unlikely-to-pass goal evaluation within the continuation budget and continue work. Only the normal evaluator can certify completion. |
subagent_routing | off | off, shadow, enforce | Choose 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_nudge | off | off, shadow, advise | At 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_search | off | off, shadow, enforce | Rerank 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_search | off | off, shadow, enforce | Rerank 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_recall | off | off, shadow, advise | Remind 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_duplicates | off | off, shadow, advise | When 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_nudge | off | off, shadow, advise | Judge 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_retention | off | off, shadow, enforce | During 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_pointers | off | off, shadow, advise | When 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_context | off | off, shadow, enforce | In 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. |
decisions.thresholds
Section titled “decisions.thresholds”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.
| Field | Type | Default | Description |
|---|---|---|---|
permission_flag | float | 0.85 | Probability for a permission warning. |
auto_flag | float | 0.85 | Probability for escalating an eligible Auto call. |
content_injection | float | 0.9 | Probability that sampled content attempts instruction injection. |
content_addressed_to_agent | float | 0.9 | Probability that sampled content addresses the agent. |
routing_confidence | float | 0.9 | Confidence 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_below | float | 0.05 | Skip an evaluator at or below this completion probability, within the continuation budget. |
shell_writes | float | unset | Optional project-write warning threshold. Omission leaves the warning disabled. No built-in enforcement threshold. |
question_tool_nudge | float | 0.85 | Minimum noul score for a question-tool reminder. Provisional, not a calibrated probability; advise only, and errors or uncertainty never reopen the turn. |
relevance_floor | float | 0.1 | Relevance 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_confidence | float | 0.75 | Relevance probability a note needs before memory recall names it in a reminder. |
Question-tool nudge
Section titled “Question-tool nudge”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.
Reranking
Section titled “Reranking”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.
Question overrides
Section titled “Question overrides”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.
[automations]
Section titled “[automations]”| Field | Type | Default | Min | Max | Description |
|---|---|---|---|---|---|
turns_per_hour | u32 | 20 | 1 | 600 | Most turns automations may start in one session per rolling hour, shared by all of its automations |
max_unattended_turns | u32 | unset | 1 | 10000 | Stop automation-started turns after this many since the last human input. Human input resets the count, and unset means no cap |
allow_private_network | bool | false | - | - | 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.
[autopilot]
Section titled “[autopilot]”| Field | Type | Default | Min | Max | Description |
|---|---|---|---|---|---|
max_continuations | u32 | 100 | 0 | 10000 | Most continuations autopilot may send per engagement before it ends. 0 removes the limit |
max_cost | f64 | unset | - | - | Most spending in USD per autopilot engagement, counting API-billed spend only. Must be positive, and unset means no cap |
max_minutes | u32 | unset | 1 | 525600 | Most wall-clock minutes per autopilot engagement while the session is open. Unset means no cap |
error_retries | u32 | 5 | 0 | 20 | Retries 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.
| Field | Type | Default | Description |
|---|---|---|---|
allow_private_hosts | string[] | [] | 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_networks | string[] | [] | 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:
| Name | Addresses |
|---|---|
loopback | 127.0.0.0/8 and ::1 |
private | 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and fc00::/7 |
cgnat | 100.64.0.0/10 |
tailscale | 100.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.
Plugins
Section titled “Plugins”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 = falseplugins.index
Section titled “plugins.index”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.
| Field | Type | Default | Min | Max | Description |
|---|---|---|---|---|---|
max_file_size_mb | integer | 2 | 1 | 16 | Refuse to index files larger than this many MiB. |
plugins.skill
Section titled “plugins.skill”skill executes as a native Caudra tool. This table keeps its existing configuration key.
| Field | Type | Default | Description |
|---|---|---|---|
plugin_dev | boolean | false | Offer the builtin caudra-plugin-dev skill for writing caudra plugins. Needs experimental.lua_plugins. |
workflow_dev | boolean | true | Offer the builtin caudra-workflow-dev skill for writing and running workflows. Needs experimental.workflows. |
automation_dev | boolean | true | Offer the builtin caudra-automation-dev skill for writing automations. Needs experimental.automations. |
docs | boolean | true | Offer the builtin caudra-docs skill: this build's user documentation, loaded one page or section at a time. |
pstack | boolean | false | Offer 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. |
mattpocock | boolean | false | Offer Matt Pocock's bundled skills (grilling, TDD, diagnosing bugs, code review, specs, tickets): the mattpocock skill and the /mattpocock: commands. |
emil | boolean | false | Offer Emil Kowalski's bundled design-engineering skills (animation, motion review, UI stress tests, prototypes, mobile polish, Swift): the emil skill and the /emil: commands. |
plugins.task
Section titled “plugins.task”task executes as a native Caudra tool. This table keeps its existing configuration key.
| Field | Type | Default | Min | Description |
|---|---|---|---|---|
max_concurrent | integer | 8 | 1 | Max concurrently running subagents. |
Validation
Section titled “Validation”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.
Directory layout
Section titled “Directory layout”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).
| Purpose | Linux / macOS | Windows |
|---|---|---|
| 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.
Config file versions
Section titled “Config file versions”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.
| File | Version | Without version | Newer than this build reads |
|---|---|---|---|
caudra.toml | 5 | Read as version 1 | Caudra stops with an error |
permissions.toml | 2 | Read as version 1 | Fails closed. Tool calls are denied until the file is fixed |
mcp.toml | 2 | Read as version 1 | Servers from that file do not start, and Caudra shows the error |
providers.toml | 1 | Read as version 1 | Caudra stops with an error |
plugin.toml | 1 | Read as version 1 | Every permission of that plugin is denied |
workcell.toml | 1 | Rejected | Rejected with an error |
sandboxes.toml | 1 | Rejected | Rejected 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().
Global and project files
Section titled “Global and project files”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.
Upgrade notes
Section titled “Upgrade notes”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 shortpython_execution = 40
[agent]defer_builtin_tools = truereads 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 shortcode = 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 = trueBackups
Section titled “Backups”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.
| Backup | Path under backups/ |
|---|---|
| A global config file | config/global/<file>.v<from>.<YYYYMMDDTHHMMSSZ>.bak |
| A project config file | config/projects/<project-id>/<file>.v<from>.<YYYYMMDDTHHMMSSZ>.bak |
caudra.db before a schema upgrade | caudra.db.v<from>.bak |
caudra.db before caudra permissions repair-review --apply | caudra.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.
Rolling back
Section titled “Rolling back”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:
cp ~/.local/state/caudra/backups/config/global/caudra.toml.v1.20261020T101500Z.bak ~/.config/caudra/caudra.tomlcaudra 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.
Personal Instructions
Section titled “Personal Instructions”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.mdin any of those project directories for per-directory preferences (gitignored)~/.config/caudra/AGENTS.mdfor preferences that apply to all projects
All of these are added to the system prompt at the start of every session.
Memory
Section titled “Memory”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.