This page is a typed, structured listing of every key in the caliban settings file. For a narrative explanation of how scopes interact, how to locate each file, and how to edit settings interactively, see Settings Reference and Settings Layering .
Settings files are TOML by primary convention (settings.toml / settings.local.toml); JSON is accepted on import only. Unknown top-level keys are tolerated for forward-compat.
Key Type Default Description
agentstring— Agent profile name (sub-agent dispatch hint). modelstring | { provider, name }— Primary model. Bare string (e.g. "claude-sonnet-4-6") or qualified object { provider = "anthropic", name = "..." }. fallback_modelstring | { provider, name }— Fallback model when the primary errors. Same shapes as model. model_overrides{ string → string }{}Per-route model overrides. Keys are router route names (e.g. "fast-classifier"); values are model ids. effort"low" | "medium" | "high" | "max" | "auto"— Default reasoning effort level.
Nested under the [permissions] table.
Key Type Default Description
permissions.allowstring[][]Patterns that auto-allow (legacy bucket form). permissions.askstring[][]Patterns that prompt the user (legacy bucket form). permissions.denystring[][]Patterns that hard-deny (legacy bucket form). permissions.rulesRuleSpec[][]Ordered v2 rule array. When non-empty, takes precedence over the three buckets above. Source order is preserved (first match wins). permissions.enforceboolean— When true, refuse --no-permissions / bypass mode at startup. permissions.default_modestring— Initial permission mode at session start. Values: default, acceptEdits, plan, auto, dontAsk, bypassPermissions. permissions.audit_logbooleantrueAppend-only permission-decision log toggle.
RuleSpec fieldspermissions.rules entries):
Field Type Description
patternstringGlob matching Tool or Tool:first-arg-glob (e.g. "Bash:git *"). action"allow" | "ask" | "deny"Decision for matching calls. commentstring (optional)Human-readable comment shown in /permissions. reasonstring (optional)Deny reason shown to the operator and logged. expires_atISO 8601 timestamp (optional) Rule is skipped after this time.
[permissions]
# v2 ordered rules (preferred)
[[permissions.rules]]
pattern = "Bash:git *"
action = "allow"
comment = "git commands OK"
[[permissions.rules]]
pattern = "Bash:rm *"
action = "deny"
reason = "use git revert"
[[permissions.rules]]
pattern = "*"
action = "ask"
Key Type Default Description
hooks{ string → … }{}Raw hook event → handler list map (passed to caliban_agent_core::HooksConfig). disable_all_hooksbooleanfalseKill-switch: disable every external hook handler. allow_managed_hooks_onlybooleanfalseWhen true, only managed-scope hooks fire. allowed_http_hook_urlsstring[][]HTTP-hook URL allowlist (glob patterns). http_hook_allowed_env_varsstring[][]Environment variable names that HTTP hooks are permitted to read.
Under [mcp_servers.<name>]. Each entry configures one MCP server.
Key Type Default Description
type"stdio" | "http" | "sse""stdio"Transport selector. Also accepted as transport (TOML alias). commandstring""Executable command (stdio only). argsstring[][]Argv after the command (stdio only). env{ string → string }{}Environment variables injected for the server process (stdio only). cwdstring— Working directory override (stdio only). urlstring— Absolute http:// or https:// URL (http/sse transports). headers{ string → string }{}Static request headers (http/sse only). oauth"off" | "auto" | "manual""off"OAuth mode (http/sse only). disabledbooleanfalseMark this server disabled without removing the entry. permissionsobject — Per-server permission scoping (composes with global rules).
[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
Key Type Default Description
routerobject — Router config (opaque; schema owned by caliban-model-router). Use caliban.toml [router] for the primary router config.
Nested under [memory].
Key Type Default Description
memory.auto_memory_enabledboolean— Enable / disable auto-memory topic files. memory.auto_memory_directorystringPlatform default Directory for auto-memory topic files. memory.cap_tokens_autointeger— Token budget cap for the auto-memory tier. memory.cap_tokens_claude_mdinteger— Token budget cap for the CLAUDE.md tier. memory.cap_tokens_combinedinteger— Combined token budget cap across all tiers.
Key Type Default Description
pluginsobject — Plugin manager knobs (schema owned by caliban-plugins).
Key Type Default Description
output_stylestring— Active output-style name (see Output Styles ). editor_modestring— Input editing mode: "vim" or "emacs". view_modestring— TUI layout mode: "compact" or "expanded". statusLine.commandstring— Required when statusLine is set. Shell command whose stdout prefixes the status bar.statusLine.timeout_msinteger (50–5000)— Maximum ms to wait for the status-line script. statusLine.paddinginteger (0–8)— Spaces of padding around the custom segment. tuiobject — TUI knobs. Known sub-key: showCostInStatusline (boolean).
statusLine uses camelCase on disk for Claude Code compatibility. The TOML alias status_line is also accepted.
Key Type Default Description
api_key_helperstring | object | object[]— Provider API-key supplier(s). Bare string = command path; object = { command, provider?, refreshIntervalMs?, slowHelperWarningMs? }; array = per-provider list.
Key Type Default Description
enable_telemetryboolean— OTel / cost emitter toggle.
Key Type Default Description
auto_compact_thresholdnumber (0–1) or null0.75Pre-turn autocompaction threshold (context utilization fraction). null disables autocompact. micro_compact_enabledbooleantrueEnable the per-turn microcompact (LLM-free supersession) pass. tool_result_cap_charsinteger (≥ 0)50000Global per-tool-result cap in characters. 0 disables. min_cache_block_tokensinteger (≥ 0)1024Minimum estimated tokens on the last user message to merit the conversation-level cache marker.
Key Type Default Description
parent_settings_behavior"block" | "augment""augment"When "block" in the managed scope, the managed layer flips to the top of the merge chain (enterprise lockdown).
Key Type Default Description
additional_directoriesstring[][]Extra workspace roots to consult for CLAUDE.md and skills. claude_md_excludesstring[][]Glob patterns to exclude from CLAUDE.md discovery (claudeMdExcludes). env{ string → string }{}Environment-variable overrides applied to child processes spawned by caliban.