Every key recognized by settings.toml (and its JSON equivalent) is listed below, grouped by topic. For merge semantics see Settings Layering ; for file paths see File Locations .
All fields are optional. Unknown top-level keys are tolerated for forward-compatibility (they are collected and ignored rather than causing a parse error).
Key Type Default Description
agentstring— Agent profile name used as a sub-agent dispatch hint modelstring or { provider, name }provider default Primary model. Bare string (e.g. "claude-sonnet-4-7") or qualified object (e.g. { provider = "anthropic", name = "claude-sonnet-4-7" }). CLI --model / --provider override this fallback_modelstring or { provider, name }— Model used when the primary returns an error. Wired through caliban-model-router. CLI --fallback-model overrides this model_overrides{ route → model }{}Per-named-route model overrides passed to the router (e.g. { "fast-classifier" = "claude-haiku-4-7" })
For provider and model selection details see Model Selection and The Model Router .
Key Type Default Description
permissions.allowstring[][]Patterns that auto-allow without prompting. Concatenated across scopes permissions.askstring[][]Patterns that prompt the user. Concatenated across scopes permissions.denystring[][]Patterns that hard-deny. Concatenated across scopes permissions.rulesRuleSpec[][]v2 ordered rule array. When non-empty, takes precedence over the three-bucket form above. Source order is preserved; first match wins permissions.enforceboolfalseWhen true, refuse --no-permissions / bypass mode at startup permissions.default_modestring"default"Initial permission mode at session start. Valid values: default, acceptEdits, plan, auto, dontAsk, bypassPermissions permissions.audit_logbooltrueEnable the append-only decision log
Each entry in permissions.rules supports:
Field Type Required Description
patternstringyes Glob pattern matching Tool or Tool:first-arg-glob action"allow" | "ask" | "deny"yes Decision when this rule matches commentstringno Human-readable note shown in /permissions reasonstringno Deny reason surfaced to the operator and logged expires_atISO-8601 datetime no Rule is skipped after this timestamp
See Permissions Concepts and Pattern Grammar for full detail.
Key Type Default Description
hooks{ event → handler[] }{}Hook event map. Keys are event names (e.g. "PreToolUse", "SessionEnd"); values are handler lists disable_all_hooksboolfalseKill-switch that disables every external hook handler. In-process hooks (permissions, audit) still run allow_managed_hooks_onlyboolfalseWhen true, only hooks defined in the managed scope fire allowed_http_hook_urlsstring[][]Glob allowlist for HTTP hook endpoint URLs http_hook_allowed_env_varsstring[][]Env-var names that HTTP hook handlers are allowed to read
See Hooks for the full event list and handler shapes.
mcp_servers is a map of server name to server configuration. Each entry deep-merges across scopes so a project scope can add environment variables to a user-scope server without redefining the whole entry.
[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
[mcp_servers.silverbullet]
type = "http"
url = "https://mcp.example.com/mcp"
headers = { Authorization = "Bearer ${SB_TOKEN}" }
Field Type Default Description
type"stdio" | "http" | "sse""stdio"Transport. Also accepted as transport (legacy alias) commandstring""Executable (stdio only) argsstring[][]Argv after command (stdio only) env{ key → value }{}Environment variables (stdio only) cwdstring— Working directory override (stdio only) urlstring— Absolute HTTP/HTTPS URL (http/sse only) headers{ key → value }{}Static request headers (http/sse only) oauth"off" | "auto" | "manual""off"OAuth mode (http/sse only) permissions.allowstring[][]Per-server allow list (composed with global rules) permissions.denystring[][]Per-server deny list disabledboolfalseSkip this server on startup
See MCP Servers for configuration examples and the OAuth flow.
Key Type Default Description
routerobject — Opaque config blob passed to caliban-model-router. The router crate owns the schema; see The Model Router
Key Type Default Description
memoryobject — Memory tier knobs passed to caliban_memory::MemoryConfig. Sub-keys include auto_memory_enabled (bool), auto_memory_directory (string), cap_tokens_auto, cap_tokens_claude_md, cap_tokens_combined (integers)
See Memory Tiers and CLAUDE.md & Imports .
Key Type Default Description
pluginsobject — Plugin manager knobs. Schema is owned by the plugin subsystem; see Plugins
Key Type Default Description
output_stylestring"default"Active output-style name. See Output Styles . Restart-required editor_mode"vim" | "emacs"— Input-line editing mode view_modestring— Compact vs. expanded TUI layout statusLineobject — Custom statusline command. Also accepted as status_line (TOML-friendly alias) tuiobject — TUI theme and layout knobs (e.g. showCostInStatusline)
statusLine sub-keys:
Field Type Default Description
commandstring— Shell command whose stdout is used as the statusline text. Required timeout_msinteger— Per-invocation timeout in ms (50–5000) paddinginteger— Horizontal padding cells (0–8)
Key Type Default Description
api_key_helperstring, object, or object[]— Provider API-key supplier. Three shapes: bare command string; single { command, provider, refreshIntervalMs, slowHelperWarningMs } object; or array of provider-keyed objects. Executed without a shell; cached for refreshIntervalMs (default 5 min) or until a 401 is received
Auth precedence per provider: per-provider helper → wildcard helper → environment variable → keyring → anonymous.
See Configuring Providers & API Keys .
Key Type Default Description
enable_telemetryboolfalseEnable OpenTelemetry / cost emitter
See Telemetry & Cost .
Key Type Default Description
auto_compact_thresholdfloat or null0.75Pre-turn auto-compaction threshold as a utilization fraction in [0, 1]. null disables auto-compact micro_compact_enabledbooltrueEnable per-turn microcompact (LLM-free supersession pass) tool_result_cap_charsinteger50000Global per-tool-result character cap. 0 disables min_cache_block_tokensinteger1024Minimum estimated tokens on the last user message to place a conversation-level prompt-cache marker
See Context & Compaction .
Key Type Default Description
parent_settings_behavior"block" | "augment""augment"When "block" is set in the managed scope , the managed scope moves to the top of the merge chain, overriding all user, project, local, and CLI settings. Has no effect when set in other scopes
Key Type Default Description
additional_directoriesstring[][]Extra workspace roots for file and shell tools to consider claude_md_excludesstring[][]Glob patterns for CLAUDE.md paths to skip during discovery env{ key → value }{}Environment-variable overrides applied to every child process launched by caliban (tools, hooks, MCP servers). Deep-merged across scopes; highest-priority scope wins per key