Caliban User Guide

Caliban is a Rust-native, provider-agnostic AI agent harness that puts you in control of model routing, memory, permissions, and prompt context. This guide is for users who run caliban day-to-day and operators who deploy and configure it for a team or homelab; it describes behavior and workflows, not Rust internals.

How this guide is organized

What Is Caliban?

Caliban is an AI agent harness: a CLI that drives one or more language models through a structured loop of prompts, tool calls, and responses while managing sessions, permissions, memory, and extensibility around that loop. It is provider-agnostic — the same harness works with Anthropic Claude (direct, Bedrock, Vertex), OpenAI (direct, Azure), Google Gemini (AI Studio, Vertex), and local Ollama, all through a common internal representation.

Capabilities at a glance

The agent loop

At its core, Caliban runs a streaming agent loop:

flowchart LR
    U[User prompt] --> A[Agent loop]
    A --> M[Model — streams response]
    M -->|tool_use blocks| T[Tool dispatch]
    T -->|tool results| M
    M -->|stop| O[Response shown to user]

Each turn streams from the model as it arrives; tool calls are dispatched as they appear and their results fed back until the model produces a final text response. The loop runs identically in TUI, headless, and library contexts.

Philosophy

Caliban exists because the dominant AI agent CLIs are tightly coupled to a single provider and leave operators with little control over what the model sees, what it can do, or where state is stored. The design is a direct response to those constraints.

Operator control

You decide what model handles each task, what context goes into the prompt, and which tools the model is allowed to call. Routing is declarative (caliban.toml); settings layer at four scopes (managed, user, project, local) with deep-merge semantics; permissions are first-class and auditable. Nothing is hardwired to a service the operator does not control.

Provider-agnostic

No SDK lock-in. Anthropic Claude, OpenAI, Google Gemini, and local Ollama all speak the same internal representation inside Caliban. Cloud transports (AWS Bedrock, Google Vertex, Azure OpenAI) are cargo-feature-gated and additive — the core binary has no mandatory cloud dependency. Switching providers is a flag, not a rewrite.

Local-first and data sovereignty

Sessions, checkpoints, auto-memory, and tool-result overflows live on your disk by default. Caliban is designed to run in a self-hosted homelab: no required cloud account, no telemetry unless you opt in (CALIBAN_ENABLE_TELEMETRY=1), no state sent anywhere you do not control.

AGPL-3.0 transparency

Caliban is licensed under AGPL-3.0-only. If you modify Caliban and run it as a network service or distribute the binary, you must release your changes under the same license. This closes the "SaaS loophole" that GPL-3.0 leaves open, aligning with projects like Mastodon and Nextcloud that use AGPL to keep improvements in the commons. Personal use is unaffected. The full rationale is in ADR 0003.

Rust performance

Harness overhead should be negligible compared to model latency. The time-to-result you experience is dominated by the model, not the runtime. This is not a feature worth advertising loudly — it is a baseline expectation for a tool that runs constantly in the background.

Project Status

Caliban v0.7.0 is a pre-1.0 release. The binary (caliban) is daily-usable from main; the core agent loop, TUI, headless mode, sessions, permissions, tools, MCP, sub-agents, memory, sandbox, and telemetry are all shipped. A number of parity gaps with Claude Code remain.

What is shipped

The table below summarizes the major shipped areas. All items marked ✅ are available on main today.

What is partial or backlog

Some rows in the parity matrix are 🟡 (partial / experimental):

For the full up-to-date breakdown, see Parity vs Claude Code. If you hit something unexpected, see Troubleshooting.

License

Caliban is licensed under AGPL-3.0-only. See Philosophy for the rationale.

Installation & Building

Caliban is published to crates.io, so the quickest way to get the binary is cargo install caliban. Building from a git checkout stays fully supported and is the path to use when you want to hack on caliban itself, or need a build with non-default feature flags.

There are no pre-built binary downloads yet — the GitHub releases carry no attached artifacts, so every install compiles from source, whether Cargo fetches that source from crates.io or you clone it yourself. A published container image (ghcr.io/caliban-ai/caliban) is the third option if you would rather not build at all.

Requirements

For a git checkout, the exact channel is pinned in rust-toolchain.toml (currently 1.95.0) and rustup downloads it automatically on first cargo invocation — no manual rustup install step required. Installing from crates.io does not pick up that pin (the published crate does not ship rust-toolchain.toml), so your default toolchain must already be 1.95 or newer.

Install from crates.io

cargo install caliban --locked

Cargo builds the binary and drops it in ~/.cargo/bin/caliban, which rustup already puts on your PATH. The build takes a few minutes on a cold cache.

--locked is recommended: the published crate ships its Cargo.lock, so this builds against exactly the dependency versions the release was tested with. Drop it if you deliberately want newer semver-compatible dependencies.

To upgrade later, re-run the same command — caliban has no built-in self-update command.

```admonish note title="Installing caliband too" cargo install caliban installs only the caliban binary. Background-fleet features additionally need the caliband daemon, which ships in a sibling crate:

cargo install caliban-supervisor --bin caliband --locked

See The Background Fleet for what it does.

## Build from source

Use this path for development, for building a specific commit, or for enabling
the optional cloud transports below.

### Clone

```bash
git clone https://github.com/caliban-ai/caliban.git
cd caliban

Release binary

cargo build --release --bin caliban

The binary lands at target/release/caliban. Build time on a modern machine is a few minutes on a cold cache.

Development build

cargo build --workspace      # all crates, debug symbols
cargo test  --workspace      # full test suite

Put the binary on your PATH

A source build does not install anything — unlike cargo install, you place the binary yourself:

# Option A — copy to a directory already on your PATH
cp target/release/caliban ~/.local/bin/caliban

# Option B — add target/release to PATH (in your shell profile)
export PATH="$PWD/target/release:$PATH"

# Option C — let cargo install it from the checkout
cargo install --path caliban --locked

Smoke test

caliban --version

You should see a version string. If you get a "command not found" error, confirm the install directory (~/.cargo/bin for cargo install, or target/release/ for a source build) is on your PATH.

For a build made from a git checkout, the version also carries the commit it was built from, so you can pin exactly which point in history a binary corresponds to:

caliban 0.7.0 (a1b2c3d, 2026-07-15)

The parentheses hold the short commit SHA and that commit's date; a build with uncommitted changes appends -dirty (e.g. a1b2c3d-dirty). Builds made without git metadata (release tarballs, cargo install from crates.io) report just the bare semver — caliban 0.7.0.

Optional: cloud transport feature flags

By default, caliban connects to providers over their public HTTPS APIs. Cloud-managed transports (AWS Bedrock, Google Vertex AI, Azure OpenAI) require optional Cargo feature flags. The exact flag names per crate are:

To build a binary with multiple cloud transports enabled at once:

cargo build --release --bin caliban \
  --features caliban-provider-anthropic/bedrock,caliban-provider-anthropic/vertex,\
caliban-provider-openai/azure,caliban-provider-google/vertex

The same --features list works with cargo install caliban, so you do not need a checkout just to enable a cloud transport.

Cloud transport features are not built in default CI runs. They are exercised by a weekly cron job and by manual dispatch of the ci-cloud workflow.

Helper scripts

The scripts/ directory contains these helpers:

Run scripts/check.sh --help or scripts/coverage.sh --help for the full usage summary.

Your First Session

Get caliban answering questions in under five minutes.

Set an API key

Caliban needs credentials for at least one provider before it can call a model. The quickest path is an environment variable. For Anthropic (the default provider):

export ANTHROPIC_API_KEY=sk-ant-...

For other providers, see Configuring Providers & API Keys.

Run a one-shot prompt

The -p / --print flag runs caliban non-interactively: it sends your prompt, streams the response to stdout, then exits.

caliban -p "What is the capital of France?"

That's it. The assistant's reply prints to stdout.

caliban --provider openai --model gpt-5.5 -p "Hello"

Work in a directory

Caliban uses the current working directory as the workspace root for file and shell tools. Just run it from your project:

cd ~/dev/my-project
caliban -p "Summarise README.md"

Enter interactive mode

Drop the -p flag (and any prompt) to enter the interactive TUI instead:

caliban

Caliban detects that stdin is a TTY and launches the ratatui interface. Type your message and press Enter. To quit, press Ctrl-C or Ctrl-D at an empty prompt.

For a tour of the TUI, see The Interactive TUI.

Named sessions

Every conversation can be saved to a named session and resumed later:

# First run — creates a session called "research"
caliban --session research "Read README.md and summarise it"

# Later — resume the same conversation
caliban --resume research

Sessions are stored on disk under the platform's data directory (for example ~/.local/share/caliban/sessions/ on Linux). See Sessions & Persistence for details.

The Interactive TUI

Invoking caliban with no prompt on a TTY launches the ratatui-based terminal interface. This is the primary mode for open-ended, conversational work.

Launching

caliban

Caliban detects that stdin is a TTY and enters the TUI. If you prefer to start from a specific session, pass --resume <name> or --continue (resumes the most recently updated session).

Basic flow

The screen is divided into three areas:

┌──────────────────────────────────────────────┐
│ assistant: Ready. What would you like to do? │
│                                              │
│ 🔧 Read({"path":"src/main.rs"})              │
│    → Read src/main.rs, lines 1-42 of 42      │
│                                              │
│ assistant: The entry point is…               │
├──────────────────────────────────────────────┤
│ > █                                          │
├──────────────────────────────────────────────┤
│ ~/dev/my-project · anthropic claude-sonnet-4-6 · session: work │
└──────────────────────────────────────────────┘

Type your message and press Enter to send. For multi-line composition, use Shift+Enter on terminals that support the kitty keyboard protocol (kitty, iTerm2, Ghostty, WezTerm, foot) or Alt+Enter as a portable fallback.

Press Ctrl-C during a turn to cancel it. Press Ctrl-C or Ctrl-D at an empty prompt to exit.

Tool calls and the permission modal

When the model wants to invoke a tool (read a file, run a shell command, etc.) caliban checks its permission rules before executing. Depending on the matching rule, the call is:

• allowed automatically — executes silently; a status line appears in the transcript.
• denied automatically — the model is told the call was refused.
• asked — a modal dialog appears:

  ┌─ Permission required ────────────────────────────────┐
  │  Bash: git commit -am "fix typo"                     │
  │                                                      │
  │  [y] Allow once   [Y] Always allow                   │
  │  [n] Deny once    [N] Always deny                    │
  └──────────────────────────────────────────────────────┘

Pressing y or n handles the call once. Pressing Y or N opens a sub-prompt that lets you write a permanent allow or deny rule to a config scope, so you are not asked again for the same pattern.

Cycling permission modes

Shift+Tab cycles the session-wide permission mode through the available values. The current mode is shown as a chip in the status line (the default mode hides the chip). Modes in order:

bypassPermissions (rules ignored entirely) is only reachable when the session was started with --allow-dangerously-skip-permissions.

For a full explanation of each mode, see Permission Modes.

The slash menu

Typing / at the input bar opens a fuzzy-search menu of slash commands:

> /
  /clear      Clear the transcript
  /compact    Summarise and compress context
  /model      Switch the active model
  /rewind     Restore a checkpoint
  …

Continue typing to filter the list; press Enter to run the selected command. See Slash Commands for the full index.

For a deeper look at transcript navigation, keyboard shortcuts, and the @-attachment picker, see The TUI in Depth.

Headless Basics

Headless mode runs caliban non-interactively: prompt in, output to stdout, exit. It is the right entry point for scripts, CI pipelines, and any context where there is no TTY.

The -p / --print flag

Pass -p (or the long form --print) with your prompt to run headlessly:

caliban -p "List the files in this directory"

Without -p, caliban checks whether stdin is a TTY. If stdin is not a TTY (i.e. you are in a pipe) or stdout is piped, caliban enters headless mode automatically. Pass --no-auto-print to suppress the automatic fallback if you need to control this explicitly.

Output formats

The --output-format flag selects what caliban writes to stdout:

# Plain text
caliban -p "Explain tokio" --output-format text

# Single JSON result
caliban -p "Explain tokio" --output-format json | jq '.result'

# NDJSON stream (tool calls, partial messages, final result)
caliban -p "Explain tokio" --output-format stream-json

The stream-json format is the richest: it includes a system/init frame first (active model, tools, MCP servers, settings sources), per-call tool_use and tool_result frames during the run, and a final type: result frame with token counts and cost. For full details see The stream-json Protocol.

Reading the prompt from stdin

Pass - as the prompt to read from stdin instead of the command line:

echo "What does this error mean?" | caliban -p -
cat error.log | caliban -p -

This is useful when the prompt is too long for a shell argument or is generated by another command.

Exit codes

Caliban follows sysexits.h conventions plus two additional signals:

CI scripts can distinguish budget exhaustion (137) from a real failure (1/2) without parsing stdout.

When to use headless

Permissions in headless mode

There is no modal in headless mode. Any rule that would normally show the Ask dialog instead becomes a hard deny. Read-only tools (Read, Glob, Grep) are allowed by default, but write and shell tools are not. To grant write access, pick one:

# Auto-allow file edits
caliban -p "Fix the typo in README.md" --permission-mode acceptEdits

# Narrow allow rule (repeatable)
caliban -p "Run tests" --allow 'Bash:cargo test*'

# Allow everything that would normally Ask (use sparingly)
caliban -p "..." --auto-allow

For depth on permission modes and rule syntax, see Print Mode.

Sessions & Persistence

Every conversation caliban has with a model is a session: a named, timestamped record of messages, token usage, and active todos. Sessions persist automatically so you can stop at any point and pick up exactly where you left off.

Starting a named session

caliban --session my-project

If my-project already exists on disk, caliban resumes it. If not, a new empty session is created. Session names must match [a-zA-Z0-9_-]+ and be between 1 and 64 characters.

Resuming a previous session

Three flags handle resume:

-c is the fastest way back into your last conversation:

caliban -c

-r accepts the same name grammar as --session:

caliban -r my-project

Resume semantics

When caliban opens an existing session it restores the full message history and accumulated token usage. The model and provider recorded in the session file are used unless overridden by --model or --provider on the command line. Plan-mode state and the todo list are also restored.

Suppressing persistence

To run a session entirely in memory without writing to disk, pass --no-save:

caliban --no-save

The session still functions normally for the duration of the run; nothing is written when it ends.

Overriding the sessions directory

By default, sessions are stored under your platform's data directory (see Files & Directories for the per-OS table). You can point caliban at a different directory for the duration of a run:

caliban --sessions-dir /path/to/sessions --session my-project

CALIBAN_SESSIONS_DIR is not a recognized env var for this flag — use --sessions-dir directly.

Session file format

Each session is a pretty-printed JSON file at <sessions-dir>/<NAME>.json. Fields include name, provider, model, messages, total_usage, created_at, updated_at, todos, and plan_mode. Files are written atomically (via a debounced background writer with a 250 ms window) to prevent corruption from crashes mid-save.

You can inspect, diff, or even git-track session files directly — the format is intentionally human-readable.

Listing sessions from the TUI

Inside the TUI, /resume lists all known sessions sorted by last-modified date. An optional substring filter narrows the list:

/resume                  # show all sessions
/resume my-proj          # show sessions whose name contains "my-proj"

Each row shows the session name, turn count, total token usage, and last-modified time. To open a listed session, exit and re-launch with caliban --session <NAME>.

The TUI in Depth

Caliban's interactive mode is a full-screen terminal UI built on ratatui + crossterm. This chapter covers everything that goes beyond the basics introduced in The Interactive TUI.

Layout

The screen is divided into three regions from top to bottom:

┌─────────────────────────────────────────────────────┐
│                                                     │
│   Transcript / output region  (flex-grow)           │
│                                                     │
├─────────────────────────────────────────────────────┤
│   Input area (2 rows)                               │
├─────────────────────────────────────────────────────┤
│   Status bar (1 row)                                │
└─────────────────────────────────────────────────────┘

The input area sits between the transcript and the status bar, placing the prompt visually close to the context information below it.

Status line

The status bar shows cwd · provider model · session (turns) · running… during a live turn. When caliban is idle the spinner disappears and the elapsed-turn time is shown instead.

A custom prefix segment can be prepended by configuring a shell script in settings (see Settings Reference for the statusLine key). The script runs off-thread after each turn completes; its output is cached so it never blocks rendering. Use /statusline to inspect the active configuration.

Keybindings

Overlays

Overlays are modal popups rendered centered (approximately 80% × 80%) over the main view. Press Esc or q to close any overlay. The active input bar is suppressed while an overlay is open.

Available overlays and how to reach them:

Editor modes

Caliban's input bar uses emacs-style key bindings by default (Ctrl+A / Ctrl+E for line start/end, Ctrl+K to kill to end-of-line, etc.).

External editor handoff

Ctrl+G writes your current input buffer to a temp file, suspends the TUI (leaving the alternate screen), execs $VISUAL / $EDITOR / vi with the file as the argument, then reads the result back and re-enters the TUI. Multi-word editor values like EDITOR='code --wait' work because the value is split on whitespace without shell parsing.

Transcript viewer

Ctrl+O opens the transcript viewer overlay. It renders every ContentBlock in the conversation history — text, tool calls, tool results, thinking blocks, and images — as the model sees them.

Following background bash (Ctrl+B)

Background bash lets caliban run a shell command in the background while you continue interacting with the agent. Press Ctrl+B inside the TUI to open or follow the background bash output panel. The agent can launch background bash tasks via Bash{background:true}; the TUI surfaces their output through the same panel.

Reverse history search

Ctrl+R opens inline reverse search over the current session's prompt history, showing matches as you type. Ctrl+S cycles the scope outward:

Ctrl+R  →  session scope
Ctrl+S  →  project scope  →  all-projects scope

Wider scopes are loaded lazily in a background task (budget: 2 s). History is persisted per project.

Prompts, Attachments & Images

This chapter covers how to compose prompts, reference files, and send images to the model — whether you are working interactively in the TUI or driving caliban from the command line.

Writing prompts

In the TUI, type your prompt in the input area and press Enter to submit. For a multi-line prompt, press \ followed by Enter to insert a newline, then Enter alone on a blank line to submit.

For longer drafts, press Ctrl+G to open the current input buffer in $VISUAL / $EDITOR / vi. Caliban reads the saved file back when the editor exits.

In headless mode, pass the prompt via a positional argument, --prompt TEXT, or pipe from stdin using -:

caliban "Explain the diff"
caliban --prompt "Explain the diff"
git diff | caliban -p -

@path file references

Type @ in the TUI input bar to open the file suggestion menu (gitignore-aware). Continue typing to narrow by path. The selected file is read and attached to your prompt as a text block at submit time.

You can also type @path/to/file directly without the menu. Any @-reference that resolves to an image-like extension (.png, .jpg, .jpeg, .gif, .webp) is handled by the image pipeline rather than as text — see Images below.

Attachment size limits

Two flags control how large @-attachments can be:

If a single file exceeds --max-attach-bytes or the total across all files exceeds --attach-budget-bytes, caliban rejects the attachment with a clear error before sending anything to the model.

# Raise limits for a large codebase session
caliban \
  --max-attach-bytes 524288 \
  --attach-budget-bytes 4194304 \
  --session big-project

Images

Caliban supports image input via three entry points:

1. @path — reference an image file by path in the TUI or via --prompt "@screenshot.png explain this" in headless mode.
2. Clipboard paste — paste an image from the clipboard directly into the TUI input bar (platform clipboard integration required; built with the clipboard feature).
3. Drag-and-drop — drag an image file into a supporting terminal emulator; caliban parses the DnD escape sequence and ingests the file.

Supported MIME types: image/png, image/jpeg, image/gif, image/webp.

Ingest pipeline

Before sending an image to a model, caliban runs it through an ingest pipeline:

1. MIME sniff — infers type from magic bytes; rejects anything outside the allowlist.
2. Decode + dimension check — decodes the image to verify it is not corrupt.
3. Downscale — if the file exceeds 5 MiB (pre-base64) or the longest edge exceeds 1568 px, caliban downscales using Lanczos3 resampling. A [downscaled] badge appears in the TUI. The 1568 px target matches Anthropic's recommended longest edge for cost-efficient vision inputs.
4. SHA-256 fingerprint — deduplicated images are not re-sent within a session.

The pipeline is configurable via [images] in caliban.toml:

[images]
max_bytes = 5242880          # 5 MiB pre-base64 cap
downscale_target = 1568      # longest-edge px target

Capability routing

By default, caliban will refuse to send an image to a model that does not have vision capability, surfacing a clear RouterError::NoCandidate rather than silently dropping the image. Set CALIBAN_STRICT_ROUTING=false to opt into degraded behavior where image content is replaced with a text placeholder and the request proceeds.

Session storage

Images are stored as blobs under <sessions-dir>/<session>/blobs/<sha256>.bin. Session JSON files carry only a BlobRef (the SHA-256), keeping transcripts small and git-diffable.

Graphics protocol detection

When the TUI renders an image inline, it detects the terminal's graphics protocol once at session start using the following cascade:

1. CALIBAN_GRAPHICS env var — values: kitty, iterm, sixel, none.
2. $TERM_PROGRAM — iTerm.app and WezTerm → iTerm2 protocol.
3. $TERM — contains kitty → Kitty protocol; contains sixel → DEC sixel.
4. Fallback — text placeholder [image: WxH MIME filename].

Override detection explicitly when caliban picks the wrong protocol:

CALIBAN_GRAPHICS=kitty caliban --session vision-work

Slash Commands

Slash commands are operator-level shortcuts you type directly in the TUI input bar. They are not model-tool calls and are not gated by the permission rule grammar — they run as your direct action.

How the slash system works

Type / in the input bar to open the suggestion menu. A fuzzy typeahead list appears showing all registered commands grouped by category.

Continue typing to narrow the list, then press Enter (or Tab) to select a command. Some commands run immediately (immediate: true) and return to the input bar; others open an overlay or emit output to the transcript.

Hooks fire on every slash submission: UserPromptSubmit carries is_slash: true, command, and args, so hooks can audit or veto any slash command.

Plugin-supplied commands

Plugins can register additional slash commands through the same SlashCommandRegistry. Built-in commands take priority; a plugin command with a conflicting name is dropped with a warning at registration time. See Plugins for details.

Common commands

The table below lists the most frequently used built-in commands. The full list — including commands added by plugins — is enumerated at runtime by /help inside the TUI.

Adding your own slash commands

Custom slash commands are defined as skills or plugins. See Custom Slash Commands for the authoring guide.

Supported Providers

Caliban is provider-agnostic: you choose which AI provider and model to use at runtime, and the same agent loop, tool engine, and permission system work regardless of which backend answers the requests.

Provider table

Bedrock, Vertex, and Azure transports are enabled by Cargo feature flags at build time. Binary distributions built by the project team include all features; self-compiled builds must enable the relevant feature (e.g. --features bedrock). These transports can only be selected through the model router — they are not available via the --provider CLI flag.

Capability matrix

Configuring Providers & API Keys

Caliban needs to know which provider to use and how to authenticate with it. Provider selection happens on the command line; authentication is supplied via environment variables or a dynamic key helper.

Selecting a provider

Pass --provider to select the backend for a session:

caliban --provider anthropic   # default
caliban --provider openai
caliban --provider google
caliban --provider ollama      # no API key needed

When --provider is omitted, caliban resolves the provider from settings.model (see Model Selection), falling back to anthropic.

API key environment variables

Each provider reads its key from a well-known environment variable:

Set the variable in your shell profile or pass it inline:

export ANTHROPIC_API_KEY="sk-ant-..."
caliban "summarize this file"

Dynamic key helper (api_key_helper)

For secrets stored in a keychain, vault, or SSO-backed credential store, set api_key_helper in your settings file instead of exposing keys in the environment. The helper is a process caliban spawns to retrieve the current key on demand.

Forms

Bare string — a single executable path or command string, used for all providers:

api_key_helper = "/usr/local/bin/get-caliban-key"

Object — one helper with explicit options:

[api_key_helper]
command = "/usr/local/bin/get-caliban-key"
provider = "anthropic"        # omit for wildcard ("*")
refreshIntervalMs = 300000    # 5 minutes (default)
slowHelperWarningMs = 10000   # warn if script takes > 10 s (default)

Array — different helpers per provider, with a wildcard fallback:

[[api_key_helper]]
provider = "anthropic"
command = "/usr/local/bin/anthropic-key"

[[api_key_helper]]
provider = "*"
command = "/usr/local/bin/generic-key"

The helper receives two environment variables:

• CALIBAN_PROVIDER — the provider id (e.g. anthropic)
• CALIBAN_API_KEY_HELPER_TTL_MS — the configured refresh interval in milliseconds

It must print the API key to stdout (trailing newline is stripped) and exit 0. Any non-zero exit is treated as an error.

Caching and refresh

Caliban caches the returned key in memory for refreshIntervalMs (default 5 minutes). On a 401 or 403 from the provider, the cache entry is invalidated and the helper is re-invoked immediately for a fresh key. Override the TTL globally with CALIBAN_API_KEY_HELPER_TTL_MS.

Bedrock and Vertex configuration

AWS Bedrock and Google Vertex are configured through the model router using [provider.bedrock] and [provider.vertex] blocks in caliban.toml. Authentication follows each platform's standard credential chain:

• Bedrock — AWS credential chain (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, instance profiles, ~/.aws/credentials). A background task refreshes credentials on a configurable interval (default 5 minutes).
• Vertex (Anthropic) — Google Application Default Credentials (GOOGLE_APPLICATION_CREDENTIALS, gcloud auth application-default login).
• Vertex (Google) — same GCP ADC path as the Anthropic Vertex transport.

See The Model Router for the full caliban.toml syntax, including [provider.X] blocks that let you override the env var name or base URL per provider.

For a full listing of every setting key, see Settings Reference.

Model Selection

Caliban lets you choose the exact model at the command line, in settings, or via the model router. When multiple sources specify a model, a clear precedence chain resolves the winner.

Selecting a model at the command line

Use --model to name the model you want:

caliban --model claude-opus-4-7 "write a haiku"
caliban --provider openai --model gpt-5.5 "explain monads"
caliban --provider google --model gemini-2.0-flash "summarize this"
caliban --provider ollama --model qwen3.5:9b "local inference"

Per-provider defaults

When --model is omitted and no model is set in settings, caliban uses a built-in default for the chosen provider:

Ollama: dynamic model discovery

Unlike the hosted providers (Anthropic, OpenAI, Google), Ollama's available models are inherently dynamic — you pull, remove, and load them on the server at will. Caliban therefore treats the Ollama server as the source of truth and has no static model table for it: the model list and each model's capabilities (context window, vision, tools, reasoning) are discovered at runtime from the server's own API:

• GET /api/tags — the models you have pulled.
• POST /api/show — per-model capabilities and maximum context_length.
• GET /api/ps — the live context window of a currently-loaded model (honors a server-side num_ctx).

This means the context window shown in the status bar reflects what the server actually reports — e.g. a 256K-context model shows 256K, not a hardcoded guess.

When discovery happens:

• At startup — a background refresh updates capabilities shortly after launch.
• On /model — opening the model list re-queries the server, so a model pulled or loaded after startup appears immediately.
• Warm start — the last successful discovery is cached to $XDG_CACHE_HOME/caliban/discovery/ollama-<host>.json (per server) and loaded at startup, so correct values are available instantly and offline.

If the server is unreachable and no cache exists yet, caliban shows a conservative default and marks capabilities as not-yet-known rather than asserting a wrong value. Point caliban at a specific server with OLLAMA_BASE_URL (each server caches independently).

The same pattern will extend to other locally-served, OpenAI-compatible back ends (vLLM, LM Studio) — see the provider roadmap.

Setting a model in settings

Set model in your project or user settings file to avoid repeating --model on every invocation. Two forms are accepted:

Bare string — the provider is inferred from the model name resolution or --provider:

model = "claude-sonnet-4-6"

Qualified object — explicitly names both the provider and the model:

[model]
provider = "anthropic"
name = "claude-sonnet-4-6"

The qualified form is the safest option in shared project configs because it makes the intended provider unambiguous.

You can also set a fallback_model that caliban uses when the primary model errors:

[model]
provider = "anthropic"
name = "claude-opus-4-7"

[fallback_model]
provider = "anthropic"
name = "claude-sonnet-4-6"

Fallback model (--fallback-model)

Pass --fallback-model on the command line to override the settings fallback for a single run:

caliban --model claude-opus-4-7 --fallback-model claude-sonnet-4-6 "long task"

The fallback is wired through caliban-model-router (ADR 0038) and is also surfaced in the headless system/init frame.

Per-turn limits

Control token usage and sampling with these flags:

caliban --max-tokens 8192 --temperature 0.2 "write a long essay"

Per-purpose model overrides (model_overrides)

For finer-grained control without a full router config, set model_overrides in settings to pin specific request purposes to a particular model string:

[model_overrides]
fast-classifier = "claude-haiku-4-5"
summarization = "claude-haiku-4-5"

The keys must match the purpose slugs understood by the router (main_loop, summarization, fast_classifier, sub_agent, embedding). This setting does not support cross-provider routing; use the model router for that.

Precedence

When multiple sources specify a model, this chain resolves the winner (highest priority first):

flowchart LR
    A["CLI<br/>--model / --provider"] --> B["settings.model<br/>(project > user > managed)"]
    B --> C["Provider default<br/>(built-in table)"]

1. CLI flags (--model, --provider) — always win.
2. settings.model — merged across the settings scope chain (project > user > managed).
3. Provider built-in default — the per-provider fallback in the table above.

For the most flexible per-purpose routing, see The Model Router.

The Model Router

The model router is a purpose-keyed dispatcher that sits between the agent loop and your provider adapters. It lets you assign different models — from the same or different providers — to different kinds of requests, and adds resilience features (fallback, hedging, circuit breakers) on top.

Why a router?

The agent makes provider calls for several distinct purposes: the main conversational loop, summarization for compaction, fast classification for permission decisions, sub-agent loops, and more. The router lets you express policies like:

• Use Claude Opus for main-loop turns, Claude Haiku for summarization.
• Route fast classification to a local Ollama model (zero API cost, low latency).
• Fall back from Anthropic to OpenAI if Anthropic returns a rate-limit error.

Request purposes

Each internal request carries a purpose that the router uses for dispatch:

Enabling the router

Drop a caliban.toml file in your project root. Caliban discovers it by walking up from the current directory to the nearest git root or $HOME, then falls back to ~/.config/caliban/caliban.toml. You can also point directly to a file:

caliban --config /path/to/caliban.toml "my prompt"
# or via env var:
CALIBAN_ROUTER_CONFIG=/path/to/caliban.toml caliban "my prompt"

Discovery order (highest priority first): --config flag → CALIBAN_ROUTER_CONFIG → walk-up from current directory → ~/.config/caliban/caliban.toml.

Basic configuration

A minimal caliban.toml with two purpose-keyed routes:

[router]
default_purpose = "main_loop"

[[router.route]]
purpose = "main_loop"
provider = "anthropic"
model = "claude-opus-4-7"

[[router.route]]
purpose = "fast_classifier"
provider = "ollama"
model = "llama3.2:3b"

Valid provider values: anthropic, openai, google, ollama.

Provider blocks

Override the API key env var or base URL for a provider in caliban.toml:

[provider.openai]
api_key_env = "OPENAI_API_KEY_STAGING"
base_url = "https://oai-staging.example.com/v1"

[provider.ollama]
base_url = "http://gpu-server.local:11434"

Fallback chains

When a route fails with a retriable error (rate-limit, model unavailable, network timeout, server error), the router tries the next route for the same purpose. Define an explicit ordered fallback list, or let declaration order in the file serve as the implicit chain:

[[router.route]]
id = "main-primary"
purpose = "main_loop"
provider = "anthropic"
model = "claude-opus-4-7"
fallback = ["main-fallback"]    # explicit: only try this specific route next

[[router.route]]
id = "main-fallback"
purpose = "main_loop"
provider = "openai"
model = "gpt-5.5"

Set fallback = [] to disable fallback entirely for a route.

Errors that are not retriable (auth failure, content policy, invalid request, cancellation) propagate immediately without trying another route.

Hedging

Hedging races a second route against the primary after a configurable delay. The first to respond wins; the other is cancelled. This is a spend-for-latency trade-off and must be opted in explicitly:

[[router.route]]
purpose = "main_loop"
provider = "anthropic"
model = "claude-sonnet-4-6"
hedge = { hedge_after_ms = 1000, max = 1 }

A global default applies to all routes in the file:

[router.hedge]
hedge_after_ms = 1500
max_hedges = 1

Set hedge = false on a route to disable the global default for that route.

Circuit breakers

A circuit breaker tracks failures per route and temporarily stops routing to a route that is consistently failing. Once the cool-off window passes, the breaker enters a half-open state and probes the route before fully reopening.

[router.breaker]           # global defaults
failure_threshold = 5      # trip after 5 failures within the window
window_secs = 60
cooldown_secs = 30
half_open_probes = 1

[[router.route]]
purpose = "main_loop"
provider = "anthropic"
model = "claude-sonnet-4-6"
breaker = false            # disable the global breaker for this route

Per-route breaker overrides can supply any subset of the fields; the rest inherit the global defaults. Cancellation outcomes do not count as failures.

Capability filters

Routes can declare capability requirements. The router only sends a request to a route if the request's needs satisfy the route's declared capabilities:

[[router.route]]
purpose = "main_loop"
provider = "anthropic"
model = "claude-sonnet-4-6"
requires = { vision = true, tool_use = true }

The router also derives needs automatically from the request content (image blocks → vision need, tool declarations → tool-use need, thinking budget → thinking need), so you do not need to annotate every route manually.

Effort levels

Set a default effort level on a route and optionally map each level to a provider-specific knob string:

[[router.route]]
purpose = "main_loop"
provider = "anthropic"
model = "claude-sonnet-4-6"
effort = "medium"

[router.route.effort_map]
low    = "budget=1024"
medium = "budget=8192"
high   = "budget=32768"

Valid effort levels: low, medium (default), high. Callers that don't specify an effort level inherit the route's default; the route default falls back to medium.

Diagnosing the router

Use caliban router debug to print the candidate list the router would resolve for a synthetic request, including breaker state and effort knobs:

# Default: main_loop purpose, no special needs
caliban router debug

# Simulate a vision + tool request
caliban router debug --purpose main_loop --has-vision --has-tools

# Show the effort table for a high-effort request
caliban router debug --effort high

# Point at a specific config file
caliban --config ./caliban.toml router debug --purpose summarization

The output shows each route with a + (kept) or - (dropped) marker, the reason it was kept or dropped, and the current circuit-breaker state.

flowchart LR
    R["Request\n(purpose + needs)"] --> Res["Resolve candidates\n(purpose filter →\ncapability filter →\nbreaker filter)"]
    Res --> D{"Dispatch"}
    D -- "success" --> Resp["Response"]
    D -- "retriable error" --> F["Next candidate\n(fallback chain)"]
    F --> D
    D -- "hedge delay" --> H["Hedge race\n(first wins)"]
    H --> Resp

Settings Layering

Caliban merges configuration from up to five sources before starting. Knowing the merge order lets you predict which value wins when the same key appears in multiple places.

The five scopes

Higher priority always wins for scalar values. The CLI scope is a virtual overlay — it has no on-disk file.

flowchart LR
    M["Managed\n(lowest)"] --> U["User"]
    U --> P["Project"]
    P --> L["Local"]
    L --> C["CLI --settings\n(highest)"]
    C --> EFF["Effective\nSettings"]

Deep-merge semantics

Scalars use highest-wins: the value from the highest-priority scope that defines the key is used; lower scopes are ignored for that key.

Arrays and maps have richer rules:

The --settings CLI overlay

--settings injects a virtual scope that sits above Local but below any active managed-block. It accepts either an inline JSON object or a path to a .json or .toml file:

# inline JSON
caliban --settings '{"model": "claude-opus-4-7"}'

# file path
caliban --settings /tmp/ci-overrides.toml

This is the recommended way to supply CI-specific settings without touching scope files.

parent_settings_behavior — managed lockdown

When an operator sets parent_settings_behavior = "block" in the managed scope, the merge order flips: the managed scope moves to the top of the chain and overrides every other scope, including the CLI overlay.

# /etc/caliban/managed-settings.toml
parent_settings_behavior = "block"
model = "claude-haiku-4-7"

With "block" active, users cannot override model from their own settings or from --settings. The value "augment" is the default behaviour (managed sits at the bottom).

--setting-sources — scope filtering

--setting-sources restricts which on-disk scopes are loaded. It accepts a comma-separated list of scope names: managed, user, project, local. The CLI overlay is always applied regardless of this flag.

# Load only user + project scopes (skip local overrides)
caliban --setting-sources user,project

# Pin to project scope only — useful for reproducible CI runs
caliban --setting-sources project

An unknown scope name is a fatal error (exit 78) rather than a silent no-op.

Live reload

A file watcher monitors each scope's path with a 250 ms debounce. When a file changes, caliban re-loads and re-merges all scopes atomically and fires a ConfigChange hook event. Most keys take effect immediately:

• Live-reloadable: permissions.*, hooks.*, api_key_helper.*, output_style, editor_mode, view_mode, statusLine, env, memory, additional_directories, claude_md_excludes
• Restart-required: model, fallback_model, mcp_servers.*, auto_compact_threshold, micro_compact_enabled, compact_strategy

Restart-required keys log a WARN on change and take effect on the next caliban invocation. The /config TUI overlay shows a "restart required" badge next to changed restart-required keys.

File Locations

Caliban resolves settings files from four on-disk scopes. Paths are XDG-first on every platform (ADR 0050) — the same layout on Linux, macOS, and Windows.

Scope paths

Managed scope

Set by a system administrator. Caliban reads but never writes this directory.

The JSON equivalent (managed-settings.json) is accepted on read as a legacy path but triggers a WARN on startup.

User scope

Per-user settings that apply across all projects. Caliban resolves the user-configuration directory XDG-first: $XDG_CONFIG_HOME/caliban/, defaulting to ~/.config/caliban/ on every platform.

Project scope

Committed alongside your code. This file should be checked into version control and shared with your team.

Local scope

Machine-local overrides that should not be committed. Add .caliban/settings.local.toml to your .gitignore.

Per-feature files (legacy)

Caliban still loads standalone per-feature TOML files during the current compatibility window. They are consulted only when the corresponding key is absent from the unified settings file in the same scope directory.

TOML vs JSON

TOML is the canonical write format. JSON is accepted on read as a legacy/import path:

• When both settings.toml and settings.json exist in the same scope directory, .toml wins and caliban logs a WARN about the ignored .json file.
• When only settings.json exists, caliban loads it with a WARN recommending migration.
• Caliban's own write paths (modal, caliban perms add, /permissions editor) always emit TOML.

Atomic writes

All caliban-owned writes use an atomic flock + temp-file rename pattern:

1. A sibling .settings.toml.lock file is exclusively flocked.
2. Content is written to a uniquely-named .toml.tmp.<pid>.<tid> file.
3. The temp file is synced and renamed onto the target.
4. The lock is released.

This ensures concurrent writers (e.g. two terminal sessions) never produce a corrupted file.

Settings Reference

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).

Model / Agent

For provider and model selection details see Model Selection and The Model Router.

Permissions

Each entry in permissions.rules supports:

See Permissions Concepts and Pattern Grammar for full detail.

Hooks

See Hooks for the full event list and handler shapes.

MCP Servers

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}" }

See MCP Servers for configuration examples and the OAuth flow.

Router

Memory

See Memory Tiers and CLAUDE.md & Imports.

Plugins

UI / Output

statusLine sub-keys:

Authentication

Auth precedence per provider: per-provider helper → wildcard helper → environment variable → keyring → anonymous.

See Configuring Providers & API Keys.

Observability

See Telemetry & Cost.

Sandbox

OS-sandbox posture for Bash commands run under --workspace / --restrict-paths (ADR 0054). The whole [sandbox] table is optional; an unset block leaves the workspace fence at its defaults.

sandbox.network is the only key currently read from layered settings. Secret scrubbing is a built-in behavior, not a setting: under the workspace fence, secret-named env vars (*KEY*, *SECRET*, *TOKEN*, *PASSWORD*, *CREDENTIAL*, OTEL_EXPORTER_OTLP_HEADERS) are always dropped from a sandboxed command's environment (#405). It is on by default and not configurable via settings.json/settings.toml today.

# .caliban/settings.toml
[sandbox]
network = "deny"

See The OS Sandbox.

Context-Window Management

See Context & Compaction.

Managed Scope Control

Miscellaneous

Config Commands

Caliban ships two subcommand families for inspecting and managing settings: caliban config for the unified settings layer, and caliban settings for import/export of individual scope files. Both work without a running session.

caliban config print

Prints the fully-merged effective settings as JSON, annotated with the scope each value came from. Honors --settings and --setting-sources so you can preview what a CI run or a different scope combination would see.

caliban config print

# Show only project + user scopes (skip local)
caliban --setting-sources user,project config print

# Preview with a CLI overlay applied
caliban --settings '{"model": "claude-opus-4-7"}' config print

The output shows the merged Settings object. Each top-level key lists the scope that contributed the winning value. This is the headless equivalent of the read-only Effective tab in the /config TUI overlay.

caliban config migrate

Consolidates legacy per-feature TOML files (permissions.toml, mcp.toml, hooks.toml) in the current workspace into a single .caliban/settings.toml. Existing keys in the target file are preserved; the migrated keys are merged on top.

# Preview what would be written (nothing is changed)
caliban config migrate --dry-run

# Run the migration
caliban config migrate

After migration the per-feature files are no longer read (caliban checks for the unified key first). You can safely delete them, or leave them in place — caliban will ignore them once the corresponding key exists in settings.toml.

caliban settings import

Imports a settings file from a foreign format (Claude Code JSON, Codex JSON, or legacy caliban JSON) into canonical caliban TOML at the target scope.

# Import ~/.claude.json into the user scope (dry-run first)
caliban settings import --from ~/.claude.json --scope user --dry-run
caliban settings import --from ~/.claude.json --scope user

# Import a project settings file into the project scope
caliban settings import --from /path/to/settings.json

Options:

caliban settings import is the recommended migration path when you have an existing Claude Code settings.json you want to adopt. The source file is read-only; only the target scope's TOML is written.

caliban settings print

Prints the raw settings for a single scope (before merging), or the merged effective settings when no scope is specified.

# Print the project-scope settings
caliban settings print

# Print the user-scope settings
caliban settings print --scope user

Options:

This differs from caliban config print in that it shows the unmerged raw contents of one scope rather than the merged result across all scopes.

TOML-primary write / JSON import-only

Caliban always writes TOML. JSON files at any scope path are accepted on read as a legacy or import path, but caliban logs a WARN and recommends running caliban settings import to migrate.

When both settings.toml and settings.json exist in the same scope directory, TOML wins and the JSON file is ignored (with a WARN).

Live reload and restart-required keys

Most settings changes take effect immediately via the file watcher (250 ms debounce). A subset of keys require a full restart:

• Restart-required: model, fallback_model, mcp_servers.*, output_style, auto_compact_threshold, micro_compact_enabled, compact_strategy

When a restart-required key changes on disk while caliban is running, caliban logs a WARN and shows a "restart required" badge in the /config TUI overlay. The new value will be used the next time you launch caliban.

All other settings — permissions, hooks, api_key_helper, UI keys, env, memory knobs — are live-reloadable and take effect within one debounce cycle without restarting.

Concepts

Every tool call the model makes — Bash, Write, Edit, a fetched URL, an MCP action — passes through the permission system before it executes. The system is a flat list of rules evaluated from top to bottom; the first rule that matches determines the outcome.

Actions

Each rule maps a pattern to one of three actions:

Rule structure

A rule is a TOML table with a pattern and an action, plus optional metadata:

[[permissions.rules]]
pattern  = "Bash:git *"       # required — see Pattern Grammar
action   = "allow"            # required — allow | deny | ask
comment  = "git ops are fine" # optional — shown in the Ask modal, not to the model
reason   = "…"                # optional, deny-only — returned to the model
expires_at = "2027-01-01T00:00:00Z"  # reserved, parsed but not yet enforced

Evaluation order

Rules are evaluated top-to-bottom; first match wins.

Sources are merged in priority order before evaluation, so high-priority sources simply appear earlier in the flat list:

1. CLI flags (--allow, --deny, --ask) — highest priority; prepended at startup.
2. Project file — <workspace>/.caliban/permissions.toml.
3. User file — $XDG_CONFIG_HOME/caliban/permissions.toml (default: ~/.config/caliban/permissions.toml).
4. Built-in defaults — lowest priority; appended automatically.

Within a single file, rules are ordered exactly as written. The [[permissions.rules]] array preserves authoring order, so narrow rules belong above broader ones.

Built-in defaults

When no rule matches a tool call before the end of the list, the built-in defaults serve as a safety net:

Unknown tools (MCP tools, future built-ins) fall through to the * catch-all and are ask by default.

Decision flow

flowchart TD
    A([Tool call arrives]) --> B{Runtime rules\nany match?}
    B -- yes --> Z
    B -- no --> C{CLI rules\n--allow/--deny/--ask}
    C -- match --> Z
    C -- no match --> D{Project rules\npermissions.toml}
    D -- match --> Z
    D -- no match --> E{User rules\n~/.config/caliban/}
    E -- match --> Z
    E -- no match --> F{Built-in defaults}
    F -- match --> Z
    Z[Matched rule action] --> G{Action?}
    G -- allow --> H([Execute tool])
    G -- deny --> I([Reject — return reason to model])
    G -- ask --> J{Interactive session?}
    J -- yes --> K([Show Ask modal])
    J -- no --> L{--auto-allow?}
    L -- yes --> H
    L -- no --> I

The Permission Mode wraps this pipeline and can override the ask verdict (but never a static allow or deny). See Permission Modes for details.

Pattern Grammar

A pattern is the pattern field in a [[permissions.rules]] entry (or the argument to --allow/--deny/--ask on the CLI). It encodes the tool name and an optional argument specifier.

The specifier can be written two ways — Tool:<glob> or Tool(<glob>). They are interchangeable; pick whichever reads better. This page uses the colon form throughout, and every form below has an equivalent paren spelling.

Forms at a glance

In the paren form the glob is everything between the first ( and the trailing ), so a (, ), or : inside the glob is taken literally — Bash(scp host:/tmp/*) and Bash(echo (hi)) both work. A : appearing before the first ( selects the colon form, leaving the parens as literal glob text.

Glob characters

The argument-side glob uses globset semantics:

Non-path patterns (Bash command strings, URLs, MCP string fields) use literal_separator = false, so * matches slashes too.

Tool:<glob> — first-argument matching

The "first arg" is a per-tool field extracted from the JSON input:

If the tool has no known accessor, only the bare Tool form can match; Tool:<glob> never fires for that tool.

Bash:~<glob> — anywhere-in-command match

Prefix the argument glob with ~ to perform a sliding-window search over the full command string rather than matching from the start. This catches commands invoked via wrappers or subshells:

# Deny any use of rm, even via sudo or bash -c "rm …"
[[permissions.rules]]
pattern = "Bash:~rm *"
action  = "deny"
reason  = "no rm — use git revert or Write"

The ~ prefix is only meaningful for Bash. On other tools it does not match.

Tool:key=<glob> — structured (dotted-key) matching

For MCP tools or built-ins whose input has named fields, use key=glob to match a specific field. Dots traverse nested objects:

# Allow creating GitHub issues only in the anthropic org
[[permissions.rules]]
pattern = "mcp__github__create_issue:repo=anthropic/*"
action  = "allow"

# AND-combined: repo must match AND title must start with "feat"
[[permissions.rules]]
pattern = "mcp__github__create_issue:repo=anthropic/*,title=feat*"
action  = "allow"

File-edit path normalization

For Read, Write, Edit, MultiEdit, and NotebookEdit, the file path in the tool call is workspace-normalized before pattern matching:

• Absolute paths are used as-is.
• Relative paths are resolved against the workspace root (the git rev-parse --show-toplevel result, or the current working directory when outside a repo).
• A relative pattern like src/**/*.rs is automatically anchored with **/ so it matches at any depth under the repo.

# Allow editing any Markdown file anywhere in the repo
[[permissions.rules]]
pattern = "Edit:**/*.md"
action  = "allow"

# Allow editing files only in a specific directory (absolute path)
[[permissions.rules]]
pattern = "Write:/tmp/*"
action  = "allow"

Examples table

Permission Modes

Permission modes control what happens when the rule evaluator produces an ask verdict. They do not override a static allow or deny — those always win. A mode is just a post-pass filter on top of the rule pipeline.

The six modes

The status bar shows a chip when the active mode is not default:

Cycling modes with Shift+Tab

In the interactive TUI, press Shift+Tab to cycle forward through the modes:

default → acceptEdits → plan → auto → dontAsk → bypassPermissions → default

Cycling into bypassPermissions without the confirmation flag (see below) fires a warning toast and snaps back to default.

Setting the mode at startup

Use --permission-mode on the command line:

caliban --permission-mode acceptEdits "add docstrings to all public functions"

Valid values are the camelCase mode names: default, acceptEdits, plan, auto, dontAsk, bypassPermissions.

The mode is also resolved from the environment variable CALIBAN_DEFAULT_PERMISSION_MODE and the permissions.default_mode setting (see below), with this precedence:

1. --permission-mode CLI flag
2. CALIBAN_DEFAULT_PERMISSION_MODE env var
3. permissions.default_mode in settings
4. Built-in default (default)

The default_mode setting

Set a persistent default mode in your project or user settings file:

[permissions]
default_mode = "acceptEdits"

This is overridden by the CLI flag and env var as shown above.

Auto-mode and --disable-auto-mode

When the mode is auto, the classifier is consulted for each tool call whose rule verdict is ask. The classifier dispatches via the router's FastClassifier purpose — configure it to use a small, fast model (e.g., Haiku, GPT-4o-mini, a local Ollama model). Results are cached for the session by (tool_name, sha256(input)).

To disable the classifier (all ask verdicts stay as-is, routing to the modal), pass:

caliban --disable-auto-mode

or set CALIBAN_DISABLE_AUTO_MODE=1. When disabled, auto mode behaves identically to default.

Bypass permissions latch

bypassPermissions overrides all rules, including static deny. Because this is a footgun, caliban refuses to enter the mode without an explicit confirmation flag:

caliban --allow-dangerously-skip-permissions --permission-mode bypassPermissions

Without --allow-dangerously-skip-permissions:

• Starting with --permission-mode bypassPermissions aborts at startup with an error.
• Configuring permissions.default_mode = "bypassPermissions" also aborts at startup.
• Cycling to bypassPermissions via Shift+Tab fires a warning toast and reverts to default.

--no-permissions

--no-permissions disables the permission system entirely — no rules are evaluated and every tool call is allowed. It conflicts with --allow, --deny, --ask, and --auto-allow. The resolved mode surfaces as "disabled" in the system/init stream-json frame.

Managing Rules

Rules can be created and edited through three surfaces: the interactive Ask modal that appears when a tool call reaches an ask verdict, the /permissions overlay inside the TUI, and the caliban perms CLI for scripted or headless management.

The Ask modal

When a tool call hits an ask verdict during an interactive session, the TUI pauses and presents a modal with four choices (navigate with arrow keys, confirm with Enter):

Press Esc to dismiss the modal and deny the current call without writing any rule.

When you choose "Always allow" or "Always reject", caliban opens a sub-prompt with a suggested narrow pattern (e.g., Bash:git push rather than Bash), a scope picker (project / user), and an optional comment field. The rule is atomically appended to the appropriate TOML file and takes effect immediately for the rest of the session.

The /permissions overlay

Type /permissions in the TUI input bar to open the interactive permissions overlay. It shows:

• The full effective rule list (runtime rules, then config rules by scope, then built-in defaults), each tagged with its origin.
• Runtime-only rules added by "Always allow/reject" during this session.
• Keybind d deletes the selected rule: a session rule is dropped from the live store immediately; a file-scoped rule is removed from its TOML file; built-in defaults are read-only.

Use the overlay to inspect the live rule list and verify which rule would match a given tool call before running it.

caliban perms CLI

The caliban perms subcommand provides a complete headless management surface. All verbs accept an optional --scope flag (managed | user | project | local | cli; defaults vary by verb).

list — show rules

# Show the effective merged rule list across all scopes
caliban perms list --effective

# Show only project-scope rules in JSON
caliban perms list --scope project --json

Output (human-readable): 1 allow Bash:git *

test — check a tool call

Returns exit code 0 (allow), 1 (deny), or 2 (ask) so it's scriptable.

# Would `git push` be allowed?
caliban perms test Bash '{"command":"git push"}'
# MATCH: pattern=Bash:git * action=allow

# Would rm be allowed?
caliban perms test Bash '{"command":"rm -rf /tmp"}'
# MATCH: pattern=Bash:rm * action=deny

explain — show the full match walk

Prints every rule in evaluation order with a MATCH marker next to the first rule that fires. Useful for diagnosing unexpected allow/deny outcomes.

caliban perms explain Bash '{"command":"sudo rm -rf /"}'
# Rule list (source order; first match wins):
#     1       allow   Bash:git *
#     2 MATCH deny    Bash:~rm *
#     3       ask     Bash
#     ...

add — append a rule

Appends a rule to the target scope file (default: project).

# Allow all cargo commands at project scope
caliban perms add "Bash:cargo *" allow --comment "cargo is safe"

# Deny curl at user scope with a reason for the model
caliban perms add "Bash:curl *" deny --scope user --reason "use WebFetch instead"

remove — delete a rule

Remove by exact pattern match. Index-based removal is reserved for a future release.

caliban perms remove --pattern "Bash:cargo *" --scope project

import — import rules from another config

Import rules from a Claude Code settings.json, a legacy caliban JSON file, or a foreign TOML. Defaults to user scope.

# Dry-run first
caliban perms import --from ~/.claude/settings.json --dry-run

# Actually import into user scope
caliban perms import --from ~/.claude/settings.json --scope user

Patterns are copied through verbatim. Claude Code writes the parenthesised form (Bash(git *), Edit(src/**)), which caliban's matcher accepts as-is — an imported rule set is live immediately, with no rewriting step. See Pattern Grammar.

export — export rules to stdout

Outputs the current scope's rules in TOML (default) or JSON format, suitable for redirecting into a new file or piping to another tool.

# Export project rules as TOML
caliban perms export --scope project

# Export as JSON (three-bucket format for interop)
caliban perms export --scope project --format json

audit — inspect the decision log

Reads the JSONL audit log and prints matching entries. See Headless & Audit for log location and rotation details.

# Show all deny decisions in the last hour
caliban perms audit --action deny --since 2026-06-01T00:00:00Z

# Show the 20 most recent decisions for the Write tool
caliban perms audit --tool Write --head 20

lint — check for duplicate or dead rules

Scans a scope's rule list for duplicate (pattern, action) pairs, and for patterns that can never match any tool call (an unclosed Bash(git *, an empty Bash(), a malformed glob). Exits 0 if clean, 1 if anything is found.

caliban perms lint --scope project
# OK (no duplicate or never-matching patterns)

caliban perms lint --scope user
# duplicate: pattern="Bash:git *" action=allow
# never matches: `Bash(git *` has an unclosed `(` — write `Tool(<glob>)` or `Tool:<glob>`

Never-matching rules are worth linting for because they fail closed and silently — the runtime treats an uncompilable glob as "no match", so the operator only sees an unexplained denial.

Headless & Audit

Headless mode and the ask verdict

When caliban runs without a TTY — in CI, in a script, or via caliban -p — there is no interactive modal to present. Any tool call that reaches an ask verdict is handled by NonInteractiveAskHandler:

• Default behavior (no flags): ask becomes a hard deny. The tool call fails with a permission error message that names a concrete remediation.
• With --auto-allow: every ask verdict becomes allow. This is equivalent to dontAsk mode for the duration of the run.

The deny message is tailored to the tool class:

The rule the message prints works when pasted verbatim: Tool(<glob>) and Tool:<glob> are interchangeable spellings (see Pattern Grammar).

Opt-in strategies

Choose the least-permissive option that satisfies the task:

# Allow only file edits (most common CI use case)
caliban -p "update version in Cargo.toml" --permission-mode acceptEdits

# Allow specific git commands
caliban -p "commit and push" --allow "Bash:git *"

# Allow all ask-rule tools (use with care)
caliban -p "run the full refactor" --auto-allow

You can also set rules in the project's permissions.toml so they apply without CLI flags:

[[permissions.rules]]
pattern = "Bash:git *"
action  = "allow"
comment = "safe for CI"

The JSONL audit log

Every tool-call decision (allow, deny, or ask) is appended to an append-only JSONL file.

Log location

The audit_log setting controls whether logging is active:

[permissions]
audit_log = true   # default; set false to disable

Log format

Each line is a JSON object:

{
  "ts": "2026-06-01T14:23:01.123456Z",
  "session_id": "s_abc123",
  "turn_index": 4,
  "tool_use_id": "tu_xyz",
  "tool_name": "Bash",
  "input_excerpt": "{\"command\":\"git push origin main\"}",
  "action": "allow",
  "matched_rule": {
    "pattern": "Bash:git *",
    "action": "allow"
  }
}

input_excerpt is truncated to 256 characters and newlines are replaced with spaces.

Log rotation

When the log file exceeds 100 MiB, caliban automatically:

1. Renames the current file to permission-decisions-YYYY-MM-DD.jsonl.
2. Gzip-compresses the renamed file to permission-decisions-YYYY-MM-DD.jsonl.gz.
3. Removes the uncompressed renamed file.
4. Opens a fresh permission-decisions.jsonl for subsequent writes.

Rotated archives accumulate in the same directory. Remove old .gz files manually when disk space is a concern.

Querying the log

Use caliban perms audit to filter and display log entries:

# All decisions since midnight UTC
caliban perms audit --since 2026-06-01T00:00:00Z

# Only denials for the Write tool
caliban perms audit --tool Write --action deny

# Most recent 50 entries
caliban perms audit --head 50

# Combine filters
caliban perms audit --tool Bash --action allow --since 2026-06-01T00:00:00Z --head 100

Exit code is always 0; an empty result prints (empty).

Hardening with permissions.enforce

The permissions.enforce flag prevents the bypass latch from being used, even when --allow-dangerously-skip-permissions is passed:

[permissions]
enforce = true

With enforce = true, caliban refuses to start if --allow-dangerously-skip-permissions is on the command line or if permissions.default_mode is set to bypassPermissions. This is useful for team or managed deployments where operators want to guarantee that static deny rules can never be overridden.

Built-in Tools

Caliban ships a fixed set of built-in tools that cover the most common agentic tasks: reading and writing files, executing shell commands, searching code, fetching web content, and coordinating work. Every tool is permission-gated (see Permissions) and subject to the execution policies described in Tool Execution.

Pass --no-tools to disable all tools and run caliban in chat-only mode.

Tool reference

WebSearch backends

WebSearch delegates to one of three search APIs, selected by the CALIBAN_WEBSEARCH_PROVIDER environment variable:

If the selected provider's API key is missing, the tool returns a structured error naming the missing variable so the agent can try a different approach rather than failing silently.

Filesystem tool conflict resolution

Edit, Write, MultiEdit, NotebookEdit, and WriteMemoryTopic all declare a conflict key based on their target path (or memory slug). When the model emits two write operations targeting the same file in a single turn, caliban serializes those calls in submission order rather than letting them interleave. Calls targeting different files still execute in parallel. See Tool Execution for details.

Tool Execution

This page covers how caliban resolves file paths for tools, dispatches multiple tools concurrently within a turn, caps oversized tool output, and controls verbosity.

Path resolution and workspace

Every filesystem and shell tool resolves paths relative to the workspace root — the directory caliban was started in, unless overridden.

--workspace <DIR> — Set the workspace root explicitly. Relative tool paths are joined against this directory. If not supplied, caliban uses the current working directory. Setting --workspace confines the file and shell tools to that directory by default (path restriction is implied); pass --no-restrict-paths to opt out. See ADR 0048.

--restrict-paths — Reject any tool call whose path resolves outside the workspace root. Absolute paths that escape the workspace return an error rather than silently accessing arbitrary filesystem locations. This is implied when --workspace is set; the explicit flag is still useful to fence to the current working directory when no --workspace is given.

--no-restrict-paths — Opt out of the implied restriction so the tools may read and write outside the workspace root. Conflicts with --restrict-paths. When combined with --no-permissions (auto-approve), caliban emits a startup warning that the run is unfenced.

additional_directories — A list of extra root paths declared in settings.toml. Tools may read and write these paths even when --restrict-paths is active, as long as the path falls under one of the declared roots.

# .caliban/settings.toml
additional_directories = [
  "/data/shared",
  "/home/user/docs",
]

Parallel tool dispatch

When the model emits multiple tool_use blocks in a single assistant turn, caliban runs them concurrently by default (ADR 0016).

flowchart LR
    A[Model turn\nmulti-tool call] --> B[Permission gate\nserial]
    B -->|Denied| C[Deny result\nto model]
    B -->|Allowed| D[FuturesUnordered\nbounded by semaphore]
    D --> E[Results in\ncompletion order]
    E --> F[Re-ordered to\nsubmission order\nin history]

Permission hooks run serially first. Each before_tool hook fires in submission order, producing an Allowed or Denied decision before any concurrent execution begins. Denied results are returned to the model immediately.

Allowed calls fan out into a FuturesUnordered pool bounded by a semaphore.

Default concurrency limit — available_parallelism() − 1 (minimum 1). This leaves one CPU core for the agent loop, streaming, and the TUI render thread. Most tools are I/O-bound, so the limit is a soft ceiling against runaway fan-out rather than a strict CPU cap.

Override flags:

Write conflict serialization. Tools that write to the same target (Edit, Write, MultiEdit, NotebookEdit, WriteMemoryTopic) declare a conflict key. Two calls with the same key are serialized in submission order even when the concurrency limit would permit them to run together. Calls with different keys (or no key) still parallelize freely.

Tool-result capping

Large tool results — for example, reading a multi-thousand-line file — can fill the context window quickly. Caliban caps each tool result before it is appended to the conversation.

tool_result_cap_chars (settings key, default 50000) — Maximum character count for a single tool result delivered inline to the model. Set to 0 to disable capping.

When a result exceeds the cap, the overflow text is written to a spill file under the caliban cache directory (~/.cache/caliban/tool-overflows/ on Linux, ~/Library/Caches/caliban/tool-overflows/ on macOS) and the model receives a truncated result with a note pointing at the spill path. The model can then decide whether to read the spill file directly.

# .caliban/settings.toml — raise the cap for large codebases
tool_result_cap_chars = 100_000

Suppressing tool announcements

By default, caliban prints a line to the terminal each time it invokes a tool, showing the tool name and its primary argument. Pass --quiet to suppress these announcements. Error output from tools is never suppressed.

# Silent execution — no "Running Bash: cargo test" lines
caliban --quiet -p "run the test suite and summarise failures"

The OS Sandbox

Caliban can wrap every subprocess spawned by the Bash tool in an OS-level sandbox that restricts what the child process may do — independent of permission rules. Where permission rules decide whether a command runs, the sandbox controls what it can access once it does.

The sandbox is implemented by the caliban-sandbox crate (ADR 0032). It is disabled by default and must be explicitly enabled in settings.

The --workspace fence (what you actually get)

The one sandbox policy caliban ships and applies for you is the workspace fence. It turns on whenever you pass --workspace <path> or --restrict-paths, and it wraps Bash commands. A plain interactive caliban run has no sandbox at all.

What the fence guarantees (ADR 0054):

Letting a sandboxed run reach the network

git fetch, cargo against crates.io, npm install, gh, and curl all need egress, so they fail inside the fence by default. A command that fails while egress is blocked will tell you so. To opt out:

caliban --workspace ./repo --sandbox-network=allow

or, persistently, in settings.json:

{ "sandbox": { "network": "allow" } }

The CLI flag wins over settings; settings win over the default (deny).

Per-hostname allowlists (e.g. "allow github.com only, so the agent can open a PR") are not yet supported — neither sandbox backend can filter egress by hostname, so it requires a proxy. Tracked in #477. Until then the opt-out is all-or-nothing.

```admonish note title="The [sandbox] TOML table below is not wired" The policy reference that follows describes the caliban-sandbox crate's full Policy surface. Only sandbox.network in settings.json is currently read by caliban; the other knobs are reachable from the library but not from a config file. Treat the rest of this page as a description of the sandbox engine, not of settings you can set today.

## Platform support

| Platform | Backend | Status |
|----------|---------|--------|
| macOS | Apple Seatbelt (`sandbox-exec`) | Supported |
| Linux / WSL | bubblewrap (`bwrap >= 0.5`) | Supported |
| Windows native | — | Not supported in v1; use WSL for the bubblewrap backend |

```admonish warning title="Seatbelt deprecation"
Apple has deprecated the `sandbox-exec` / Seatbelt API. It still ships in all
current macOS releases, but caliban's macOS backend will need to move to the
Endpoint Security Framework if Apple removes `sandbox-exec` in a future OS
version. There is no announced removal date.

Enabling the sandbox

Add a [sandbox] block to your project or user settings.toml:

[sandbox]
enabled = true
fail_if_unavailable = true   # refuse to start if bwrap/sandbox-exec is missing

With fail_if_unavailable = false (the default), caliban falls back to running unsandboxed if the backend binary is absent or too old, and logs a warning.

What the sandbox restricts

The sandbox limits three classes of access for spawned subprocesses:

Filesystem

On Linux, denied paths are masked with --tmpfs (an empty in-memory directory shadows the real one). On macOS, Seatbelt uses (deny file-write* (subpath …)) rules. Glob patterns are not supported in filesystem ACLs — add explicit path roots.

The environment variables ${WORKSPACE}, ${HOME}, and the XDG vars are expanded when the sandbox is initialized.

Network

Per-hostname egress is not reliably enforceable by either backend alone. The supported patterns are:

• Block all egress — leave network.allowed_domains empty. Uses --unshare-net on Linux and omits all network-outbound allow rules on macOS.
• Proxy-filtered egress — set network.http_proxy_port to route subprocess HTTP through an operator-run proxy at 127.0.0.1:<port>. The proxy enforces domain rules; the sandbox only allows the loopback port.

Other network settings

[sandbox.network]
allow_unix_sockets = false     # Docker daemon socket, etc.
allow_local_binding = false    # bind() on local ports
allow_mach_lookup = []         # macOS-only: Mach service names

Full configuration example

[sandbox]
enabled = true
fail_if_unavailable = true
auto_allow_bash_if_sandboxed = true
allow_unsandboxed_commands = ["git", "gh"]
enable_weaker_nested_sandbox = false

[sandbox.filesystem]
allow_read  = ["${WORKSPACE}", "/etc", "/usr"]
deny_read   = ["${HOME}/.ssh"]
allow_write = ["${WORKSPACE}"]
deny_write  = ["${WORKSPACE}/.git/hooks"]

[sandbox.network]
http_proxy_port = 8888
allow_unix_sockets = false
allow_local_binding = false

Key settings

auto_allow_bash_if_sandboxed — When both enabled and this flag are true, the permission classifier auto-allows all Bash(*) calls without showing a prompt. The sandbox is the protection; the Ask modal becomes redundant. Defaults to false. Note: commands listed in allow_unsandboxed_commands are not auto-allowed — they run outside the sandbox and still go through normal permission rules.

allow_unsandboxed_commands — A glob list matched against the first token of each command (or the full command string when the pattern contains a space). Matching commands bypass the sandbox entirely. Use this for tools that genuinely need unrestricted access — for example, git or gh.

enable_weaker_nested_sandbox — For dev containers or VMs that are already inside a user namespace: drops the --unshare-user flag on Linux (which would otherwise fail). This is a no-op on macOS.

bwrap_path / sandbox_exec_path — Override the path to the sandbox binary if it is not at the default location ($PATH for bwrap; /usr/bin/sandbox-exec for macOS).

How it works

SandboxedShim::wrap_command intercepts the tokio::process::Command built by BashTool before it is spawned. If the sandbox is active and the command is not on the bypass list, it rewrites the command so that:

• On macOS: sandbox-exec -f <profile.sb> <original command>
• On Linux: bwrap [bind/ro-bind/tmpfs flags] <original command>

The rest of the Bash tool — stdout/stderr capture, PID-group cleanup, timeouts, cancellation — is unchanged. The sandbox is a shim layer, not a fork.

Detection runs at startup. bwrap version >= 0.5 is required on Linux (the --die-with-parent flag arrived in 0.5).

Skills

Skills are reusable instruction packages that the model loads on demand. Each skill is a markdown file with YAML frontmatter — the same format as the Anthropic "superpowers" plugin ecosystem, so existing skills port without changes.

Skills are not executed; they inject text into the model's context. A skill can describe a workflow, a style guide, a debugging procedure, or any other multi-step process. Only the description line is always visible to the model; the full body is fetched lazily when the model calls the Skill tool.

How the Skill tool works

Caliban registers a single built-in tool named Skill. Its description lists every loaded skill by name and one-line description. When the model wants to follow a skill's instructions, it calls Skill with the skill's exact name; the harness returns the body as text and the model proceeds accordingly.

This design keeps the token cost bounded: descriptions are always present, bodies are pay-per-use.

Discovery roots

Caliban scans three roots in priority order. The first match for a given name wins; later roots are shadowed.

A project-level skill with the same name as a user-level skill silently replaces it. Malformed SKILL.md files are logged at warn and skipped — loading is best-effort.

Skill file format

Each skill lives in its own subdirectory. The directory name must match the name: frontmatter field exactly.

.caliban/skills/
  my-workflow/
    SKILL.md

SKILL.md structure:

---
name: my-workflow
description: "One-line summary shown to the model in the Skill tool description."
metadata:
  trigger: pre-implementation   # free-form; passed through unchanged
---

# My Workflow

Full markdown instruction set. Only loaded when the model calls Skill({"name": "my-workflow"}).

Required frontmatter fields: name and description. The metadata map is optional.

Built-in skills

Caliban ships one built-in skill compiled into the binary:

Built-ins register before the directory scan, so a user or project skill with the same name will shadow them.

Disabling skills

Related pages

• Plugins — bundle skills alongside hooks, MCP servers, and output styles
• Slash Command Index — /skills overlay shows loaded skills

Custom Slash Commands

Caliban's slash commands are managed through a central SlashCommandRegistry. Every command — whether built-in or plugin-supplied — registers in the same registry, which drives typeahead completion, the /help listing, and dispatch.

The built-in registry (ADR 0040)

At startup, caliban registers approximately 30 built-in slash commands covering session management, context control, configuration, and diagnostics. The registry is the canonical source of truth for what commands exist; /help enumerates the live set.

flowchart LR
    Input["/ input"] --> Typeahead["Typeahead suggester"]
    Input --> Dispatch["Registry dispatch"]
    Dispatch --> Command["SlashCommand impl"]
    Command --> SlashCtx["SlashCtx (session + registries)"]

Each command receives a SlashCtx containing the running session, provider, MCP manager, skills registry, hooks, and settings — everything it might need without requiring each command to thread individual dependencies through its call signature.

Full built-in command list

See the Slash Command Index for the authoritative list with descriptions and arguments.

Key commands relevant to the extending cluster:

Plugin-supplied commands

Plugins (ADR 0030) may register additional slash commands by placing command markdown files in their commands/ subdirectory. The plugin system feeds these into the registry at startup using the same SlashCommand trait. Plugin-supplied commands are namespaced <plugin>:<command> so they cannot shadow built-ins by accident.

Hook on slash submission

UserPromptSubmit fires before the slash parser runs. The hook payload includes is_slash: true, command, and args. A hook can reject or rewrite a slash command — useful for audit logging or per-operator policy enforcement.

Related pages

• Slash Command Index
• Skills
• Plugins
• Hooks

Hooks

Hooks let you attach external logic to caliban's event stream — shell scripts, HTTP callbacks, or MCP tools — without modifying the agent or recompiling. Hooks run in-process (for the built-in PermissionsHook and audit hooks) or via an external HookRouter (for operator-configured handlers).

Event taxonomy

Caliban fires events at the following lifecycle points (ADR 0024):

Additional events (Setup, UserPromptExpansion, PostToolBatch, InstructionsLoaded, WorktreeCreate, WorktreeRemove, Elicitation, ElicitationResult, TeammateIdle) are reserved but not yet fired.

Handler types

Each hook entry declares one or more handlers. Two handler types are fully wired; three are stubs (see below).

Decision protocol

For PreToolUse and UserPromptSubmit, command and http handlers report their decision as:

Stdout JSON (preferred):

{
  "hookSpecificOutput": {
    "permissionDecision": "allow",
    "permissionDecisionReason": "matched allowlist",
    "updatedInput": {}
  }
}

permissionDecision values: allow, deny, ask. updatedInput lets the hook rewrite the tool input before dispatch (the rewritten input is validated against the tool's schema; validation failure is a hard deny).

Exit codes (shell-script shorthand):

• 0 — Allow
• 2 — Deny (stderr becomes the reason)
• anything else — Allow with a logged warning

PostToolUse and observer-only hooks ignore the decision even when a handler provides one. Handlers marked async = true are fire-and-forget; their decisions are always ignored.

SessionStart context injection

A SessionStart command or http handler may return an additionalContext string — either flat ({"additionalContext": "…"}) or nested under hookSpecificOutput. Caliban splices each returned block into the system prompt inside a <session-context> element, so a hook can inject dynamic per-session context (current branch, ticket ID, deploy status) without editing CLAUDE.md.

Config: settings hooks table (preferred)

Hooks live in the unified settings file under the hooks key. The table maps event names to arrays of handler groups. See Settings Layering for how scopes merge — hook arrays concatenate across scopes (project entries append to user entries).

# .caliban/settings.toml  — project scope

disable_all_hooks = false
allow_managed_hooks_only = false

allowed_http_hook_urls = [
  "https://hooks.example.com/*",
]
http_hook_allowed_env_vars = ["AUDIT_TOKEN"]

[[hooks.SessionStart]]
matcher = "*"
[[hooks.SessionStart.handlers]]
type    = "command"
command = "/usr/local/bin/caliban-audit"
args    = ["session-start"]
timeout = "5s"

[[hooks.PreToolUse]]
matcher = "Bash"
if      = "Bash:rm *"
[[hooks.PreToolUse.handlers]]
type    = "command"
command = "${CALIBAN_PROJECT_DIR}/.caliban/hooks/guard-rm.sh"
async   = false

[[hooks.PreToolUse]]
matcher = "WebFetch"
[[hooks.PreToolUse.handlers]]
type    = "http"
url     = "https://hooks.example.com/preflight"
headers = { Authorization = "Bearer ${AUDIT_TOKEN}" }
timeout = "3s"

[[hooks.PostToolUse]]
matcher = "*"
[[hooks.PostToolUse.handlers]]
type  = "mcp"
mcp   = "audit-server"
tool  = "log_tool_call"
async = true

Config: legacy hooks.toml (compat)

If no hooks key appears in any settings file, caliban falls back to loading:

• <workspace>/.caliban/hooks.toml (project scope)
• ~/.config/caliban/hooks.toml (user scope)

The legacy file uses the same TOML shape shown above (top-level keys plus [[hooks.<Event>]] arrays). The two scopes merge with project entries taking priority. This path is deprecated — prefer the unified settings file for new configurations.

Safety controls

Related pages

• Permissions concepts
• Plugins — plugins can bundle hook configurations
• Slash Command Index — /hooks shows the active handler set

MCP Servers

Caliban implements the Model Context Protocol client side, letting you connect any MCP-compatible server as a source of additional tools. Connected servers' tools appear in the same ToolRegistry as built-ins, with the naming convention mcp__<server>__<tool>.

Configuring servers

Servers are declared in the mcp_servers table of your unified settings file, or in the legacy mcp.toml when no unified settings are present.

Minimal stdio server

# .caliban/settings.toml

[mcp_servers.linear]
command = "npx"
args    = ["-y", "@linear/mcp-server"]
env     = { LINEAR_API_KEY = "${LINEAR_API_KEY}" }

HTTP server

[mcp_servers.notion]
type    = "http"
url     = "https://mcp.notion.com/v1"
headers = { Authorization = "Bearer ${NOTION_TOKEN}" }

SSE server

[mcp_servers.legacy-api]
type = "sse"
url  = "https://api.example.com/mcp/sse"

Server configuration reference

${CLAUDE_PROJECT_DIR} expands to the current workspace root in all string fields, so plugin-bundled servers can reference binaries relative to the workspace without hardcoding paths.

OAuth (oauth = "auto" and "manual")

For HTTP/SSE servers behind OAuth, caliban performs the authorization-code flow with PKCE and a loopback callback server.

Auto discovery (oauth = "auto"): caliban discovers the authorization endpoints from the server's /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server documents. Most hosted MCP servers (Sentry, Linear, Notion, …) also advertise a registration_endpoint, so caliban dynamically registers a client (RFC 7591) on the first run — no app registration, no client_id, nothing to configure but the URL:

[mcp_servers.sentry]
type  = "http"
url   = "https://mcp.sentry.dev/mcp"
oauth = "auto"

The first interactive run opens a browser, you authorize, and the token is cached. caliban registers a public PKCE client for its loopback callback; a fixed callback port (below) keeps that registration stable across runs.

GitHub is the exception — its authorization server does not offer dynamic registration (registration_endpoint: null), so auto needs a manually-registered OAuth App's client_id (+ client_secret) in an oauth_config block:

[mcp_servers.github]
type  = "http"
url   = "https://api.githubcopilot.com/mcp/"
oauth = "auto"

[mcp_servers.github.oauth_config]
client_id     = "${GITHUB_OAUTH_CLIENT_ID}"
client_secret = "${GITHUB_OAUTH_CLIENT_SECRET}"

GitHub matches the OAuth App's Authorization callback URL exactly, so pin the loopback port: register the callback as http://127.0.0.1:41870/callback and run with CALIBAN_MCP_OAUTH_PORT=41870. A configured client_id always takes precedence over dynamic registration.

Manual configuration (oauth = "manual"): supply the endpoints yourself in a [mcp_servers.<name>.oauth_config] block:

[mcp_servers.my-server]
type  = "http"
url   = "https://api.example.com/mcp"
oauth = "manual"

[mcp_servers.my-server.oauth_config]
client_id  = "${MY_CLIENT_ID}"
auth_url   = "https://auth.example.com/authorize"
token_url  = "https://auth.example.com/token"
scopes     = ["read", "write"]

The first interactive run opens your browser to authorize; the token is cached and reused (and silently refreshed near expiry) on later runs, so no browser is needed again until it fully expires. In headless/--print/non-TTY runs a server with no cached token fails fast with an actionable error rather than hanging on a callback — authorize it interactively once first. Tokens are stored in the OS keyring; caliban falls back to $XDG_DATA_HOME/caliban/mcp-tokens.json (mode 0600) on systems without keychain support.

Easiest path for GitHub — reuse the GitHub CLI's token. If you're logged in with gh, its token already authenticates the GitHub MCP server, so you can skip OAuth entirely with a static bearer header and no app registration:

[mcp_servers.github]
type    = "http"
url     = "https://api.githubcopilot.com/mcp/"
oauth   = "off"
headers = { Authorization = "Bearer ${GITHUB_MCP_TOKEN}" }

then launch with GITHUB_MCP_TOKEN=$(gh auth token) caliban …. Nothing secret is stored on disk and the token is always current. (Any GitHub PAT with the needed scopes works the same way.)

Environment-variable expansion

Every string value in an [mcp_servers.<name>] block — url, headers.*, command, args, env.*, and the oauth_config.* fields — supports ${VAR}, ${VAR:-default}, and ${CLAUDE_PROJECT_DIR} expansion, so credentials can live in the environment instead of in settings.toml. A ${VAR} with no value (and no default) is left as-is and the server is reported as failed rather than silently mis-configured.

Fixed callback port

Use --mcp-oauth-port <PORT> (or CALIBAN_MCP_OAUTH_PORT) to pin the loopback callback port instead of an ephemeral one. This is required for authorization servers that match the redirect_uri exactly (GitHub OAuth Apps) and useful on firewalled machines.

Per-server permissions

Each server can declare scoped permission rules that compose with the global rule grammar. Patterns match the unprefixed tool name; caliban expands them to mcp__<server>__<tool> when evaluating against the global engine.

[mcp_servers.linear.permissions]
allow = ["read_*", "list_*"]
deny  = ["delete_*"]
ask   = ["create_*", "update_*"]

Merge order when multiple rules match a call: global deny → server deny → server ask → server allow → global ask → global allow → default (Ask)

Discovery and the /mcp overlay

At startup, caliban connects to every non-disabled server, sends initialize, and registers one McpTool per advertised tool. Failures (spawn error, handshake timeout) are logged at warn and skipped — they do not abort startup.

The /mcp slash command shows per-server status:

@server:resource references

Type @<server>: in the input bar to trigger resource autocomplete for that server. Caliban calls resources/list lazily on first use and caches the result; resources/list_changed notifications invalidate the cache.

Elicitation

When an MCP server needs additional input from the user (for example, before a destructive operation), it sends an elicitation request. In interactive mode, caliban shows a TUI modal. In --print / CI mode, elicitation requests are automatically declined.

Controls

Related pages

• Plugins — plugins can bundle MCP server configs
• Permissions concepts
• Slash Command Index — /mcp overlay

Plugins

A plugin bundles related customizations — skills, hooks, sub-agent definitions, MCP server configs, and output styles — into a single installable directory. The plugin system (ADR 0030) is a thin orchestrator: it parses a plugin.json manifest, namespaces items, expands ${CALIBAN_PLUGIN_ROOT}, and feeds everything into the same per-surface loaders that project and user files use.

What a plugin contains

my-plugin/
  plugin.json             # required manifest
  skills/
    my-workflow/
      SKILL.md
  hooks/
    hooks.json
  agents/
    reviewer.md
  output-styles/
    concise.md
  mcp/
    .mcp.json
  commands/
    recap.md

All subdirectories are optional. When a components entry is omitted from the manifest, the loader scans the conventional subdirectory automatically.

The manifest (plugin.json)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Short description shown in /plugins and trust prompts",
  "author": "Alice <alice@example.com>",
  "license": "MIT",
  "homepage": "https://example.com/my-plugin",
  "components": {
    "skills": ["skills/my-workflow"],
    "hooks": "hooks/hooks.json",
    "agents": ["agents/reviewer.md"],
    "output_styles": "output-styles/concise.md",
    "mcp_servers": "mcp/.mcp.json",
    "commands": ["commands/recap.md"]
  },
  "caliban": {
    "min_version": "0.5.0",
    "platforms": ["macos", "linux"]
  }
}

For MCP servers bundled as inline config (matching Claude Code's .mcp.json shape), use the top-level mcpServers key instead of components.mcp_servers.

Discovery roots

Caliban scans three roots at startup. A plugin with the same name in an earlier root replaces later ones — no manifest merging.

Managed plugins ignore the plugins.enabled list — they run regardless of per-user configuration.

Namespacing

Items loaded from a plugin carry a <plugin>:<item> prefix:

• Skills: my-plugin:my-workflow
• Output styles: my-plugin:concise
• MCP servers: my-plugin:my-server

This prevents collisions with bare-named items at the project or user level. Hooks merge additively across plugins.

The caliban plugin command

# List all installed plugins and their status
caliban plugin list

# Show the manifest of an installed plugin as JSON
caliban plugin info <name>

# Install a plugin from a marketplace
caliban plugin install <name>@<marketplace-url>

# Install a plugin from a local directory
caliban plugin install --dir /path/to/my-plugin

# Update a plugin to the latest marketplace version
caliban plugin update <name>

# Remove a plugin
caliban plugin remove <name>

# Enable / disable a plugin (affects whether it loads at startup)
caliban plugin enable <name>
caliban plugin disable <name>

caliban plugin help prints the full reference.

Marketplace trust

First-time marketplace installs display the manifest, its sha256 hash, and the install URL and prompt for acknowledgement. Acknowledged installs are recorded in $XDG_DATA_HOME/caliban/trust/plugins.json. Re-installs of the same manifest hash skip the prompt; version bumps re-prompt. Sideloads (local --dir installs) skip trust gating because the operator already has filesystem access.

${CALIBAN_PLUGIN_ROOT} expansion

Inside plugin-bundled hook commands and MCP server configs, ${CALIBAN_PLUGIN_ROOT} expands to the plugin's absolute root directory. ${CLAUDE_PLUGIN_ROOT} is a supported alias so existing Claude Code plugins port verbatim.

Related pages

• Skills
• Hooks
• MCP Servers
• Output Styles
• Slash Command Index — /plugins overlay

Output Styles

Output styles nudge the model toward a particular response shape — more explanatory prose, learning-paced prompts with TODO(human) markers, or a proactive fill-in approach — by splicing a block into the system prompt. They are orthogonal to tools, hooks, and permissions: switching styles changes only the system prompt.

Built-in styles

Caliban ships four built-in styles compiled into the binary:

The default style emits no block at all, so switching to it produces the exact same system prompt as having no style — prompt-cache hits are preserved.

Selecting the active style

Via settings (preferred): set output_style in your settings file.

# ~/.config/caliban/settings.toml
output_style = "explanatory"

Via environment variable (until the settings hierarchy is fully wired):

CALIBAN_OUTPUT_STYLE=learning caliban

Via the TUI: use /output-style to open the picker. The new selection is remembered for the session but takes effect only after /clear or a restart, because providers cache the system prompt and a mid-session change would silently invalidate that cache.

How styles splice into the system prompt

OutputStylePrefix::splice_into wraps the active style's body in an <output-style> XML element and prepends it to the base system prompt. Memory tier content goes first, then the style block, then the base body:

[memory tiers]

<output-style name="explanatory">
... style body ...
</output-style>

[base system prompt]

If the active style has an empty body (the default style), splice_into returns the base prompt unchanged — no extra tokens, no cache miss.

The frontmatter field keep_coding_instructions: false (default true) lets a style suppress the default coding-assistant guidance block. Use this for documentation-only or writing-only modes where coding instructions are irrelevant.

Custom styles

Drop a .md file with YAML frontmatter into the appropriate directory. The file stem must match the name: field.

.caliban/output-styles/
  brief.md

Example brief.md:

---
name: brief
description: "Terse responses — one sentence per point, no preamble."
keep_coding_instructions: true
---

Keep all responses as brief as possible. One sentence per point.
No greetings, no summaries, no padding. Respond with the minimum necessary.

Required fields: name and description. Both snake_case (keep_coding_instructions) and kebab-case (keep-coding-instructions) are accepted.

Discovery roots

A project style with the same name shadows user, plugin, and built-in styles.

Plugin-supplied styles and force_for_plugin

A plugin-supplied style with force_for_plugin: true in its frontmatter overrides the operator's output_style setting while the plugin is enabled. The /config picker shows a "locked by plugin: X" badge. Disabling the plugin releases the lock.

force_for_plugin: true is silently ignored on non-plugin styles (project, user, built-in).

Related pages

• Plugins
• Settings Reference — output_style key
• Slash Command Index — /output-style picker

Sub-agents

Caliban can spawn a nested agent — a sub-agent — to handle a focused subtask without polluting the parent's transcript. The parent's turn loop pauses while the sub-agent runs, then resumes with the sub-agent's condensed result as a single tool-result block.

The AgentTool

Sub-agents are exposed to the model as a built-in tool named AgentTool. When the model invokes it, caliban spins up a fresh Agent instance in the same process and drives it to completion.

Key properties of an AgentTool invocation:

Tool allowlist

The tool_allowlist input controls which tools the sub-agent may call:

• Omitted or null — inherits every tool the parent has, except AgentTool itself.
• Explicit list — sub-agent gets exactly those tools. Unknown names are silently dropped.

Isolation mode

Each AgentTool invocation carries an isolation field (none or worktree):

• none (default) — sub-agent shares the parent's working directory. Suitable for read-only work (investigation, summarization).
• worktree — sub-agent runs in a dedicated git worktree materialized at .caliban/worktrees/<name>. Suitable for tasks that write files. See Worktree Isolation for details.

Background mode

Setting background: true in the AgentTool input detaches the sub-agent from the parent and hands it off to the caliband supervisor daemon. The parent's call returns immediately with the new agent's id. See The Background Fleet.

The --no-sub-agent flag

Pass --no-sub-agent (or set CALIBAN_NO_SUB_AGENT=1) to remove AgentTool from the tool registry entirely. The model will never see the tool and cannot spawn sub-agents.

caliban --no-sub-agent "review this codebase"

This is useful when you want a strict single-agent session, or when operating in an environment where spawning child work is undesirable (CI cost budgets, audit requirements).

When to use sub-agents

For the full set of built-in tools the sub-agent can draw on, see Built-in Tools.

The Background Fleet

Caliban can run sub-agents in the background — detached from your current session — and let you monitor, attach to, or stop them at will. A per-workspace supervisor daemon (caliband) owns the fleet and keeps agents alive even after the parent caliban process exits.

Spawning a background agent

From the command line

The quickest way to fire off a background task is the --bg flag:

caliban --bg "refactor the auth module to use the new token type"

This is shorthand for caliban agents spawn --prompt <task>. Caliban auto-starts caliband if it is not already running, then returns immediately with the new agent's id.

From inside a session

The model can request a background sub-agent by setting background: true in an AgentTool call. The parent session receives the id and a note to check back via caliban attach <id>.

The caliband daemon

caliband is a separate binary shipped alongside caliban. It runs as a per-workspace daemon: each workspace root gets its own daemon instance. A workspace is usually a single git repository, but since v0.5.0 the supervisor can manage a workspace spanning multiple sources (repos), each with its own worktree isolation.

Socket path (resolution order):

1. $CALIBAN_DAEMON_RUNTIME_DIR/<hash>.sock if CALIBAN_DAEMON_RUNTIME_DIR is set.
2. $XDG_RUNTIME_DIR/caliban/<hash>.sock if $XDG_RUNTIME_DIR is set.
3. $TMPDIR/caliban-daemon/<hash>.sock (fallback; typical on macOS).

The <hash> is a 16-hex-char SHA-256 prefix of the absolute workspace root path, so each workspace gets a stable, unique socket without naming collisions. (For a single-repo workspace the workspace root is the repo root, so the socket is unchanged from earlier releases.)

caliband auto-starts when any caliban agents command or --bg flag needs it. You should rarely need to launch it directly.

cargo install caliban-supervisor --bin caliband

Networked control plane (beta)

By default caliband serves its control plane over the local Unix domain socket described above. Since v0.5.0 it can instead serve that same line-delimited (NDJSON) protocol over TCP, so a remote client (for example prospero) can drive the fleet across the network rather than only from the same host. Enable it by passing --listen <host:port> (or setting CALIBAN_DAEMON_LISTEN) when the daemon starts:

caliband --workspace-root /path/to/workspace \
  --listen 0.0.0.0:7070 \
  --tls-cert cert.pem --tls-key key.pem \
  --token "$CALIBAN_DAEMON_TOKEN"

Agent lifecycle states

caliban agents subcommands

caliban agents list

Print all registered agents and their status.

caliban agents list

caliban agents spawn

Spawn a new background agent with an explicit prompt.

caliban agents spawn --prompt "audit all SQL queries for injection risks"
caliban agents spawn --prompt "write tests for crates/caliban-tools-builtin" --label my-test-agent

Options:

caliban agents attach <id>

Stream a running agent's transcript live. Press Ctrl+D to detach without stopping the agent.

caliban agents attach a3f8b2c1

caliban agents logs <id>

Print the agent's session log (session.json).

caliban agents logs a3f8b2c1

caliban agents kill <id>

Terminate an agent (SIGTERM, escalating to SIGKILL after a grace period).

caliban agents kill a3f8b2c1

caliban agents respawn <id>

Kill the agent and restart it with the same original spawn spec (same prompt, model, isolation settings).

caliban agents respawn a3f8b2c1

Note that respawn assigns a new id; the old id is removed from the registry.

caliban agents rm <id>

Remove an agent from the registry. The agent must be stopped first, unless --force is passed.

caliban agents rm a3f8b2c1
caliban agents rm a3f8b2c1 --force   # remove even if still running

Top-level shorthands

Four common operations have top-level sugar to save typing:

caliban daemon subcommands

caliban daemon status

Print daemon health, PID, uptime, agent count, and the socket path.

caliban daemon status

caliban daemon stop

Ask the daemon to shut down gracefully after finishing in-flight requests. Running agents are not automatically killed; stop them first if you want a clean shutdown.

caliban daemon stop

Session storage

Each background agent's transcript is stored as a regular caliban session file at <base>/agents/<id>/session.json. This means all session tooling (compaction, replay, audit) works on background agents out of the box. Attaching to an agent is conceptually the same as resuming its session over the agent's per-agent socket.

Diagram: agent lifecycle

flowchart LR
    A([caliban --bg task]) -->|spawn request| D[caliband daemon]
    D -->|registers| R[(Registry)]
    D -->|starts| W[Agent worker]
    W -->|streams turns| S[(session.json)]
    W -->|per-agent socket| T([caliban attach id])
    W -->|done/failed| R
    T2([caliban agents kill id]) -->|kill request| D
    D -->|SIGTERM→SIGKILL| W

For how background agents use git worktree isolation, see Worktree Isolation.

Worktree Isolation

When a sub-agent writes files, those writes land in the parent's working tree by default. That is fine for read-only investigation, but it mixes the sub-agent's diff into yours and gives you no clean way to discard it. Worktree isolation solves this: caliban materializes a dedicated git worktree for the sub-agent so its file operations are completely separate from the parent's tree.

How it works

When isolation: worktree is requested, caliban uses the caliban-worktrees crate to:

1. Create a new git branch named caliban/<name> off the chosen base ref.
2. Materialize a worktree at .caliban/worktrees/<name>/ in the repo root.
3. Optionally apply sparse-checkout patterns to limit which paths are checked out.
4. Optionally symlink heavy directories (e.g. target/, node_modules/) from the parent repo into the worktree so they are shared rather than duplicated.
5. Run the sub-agent with its working directory set to the worktree root.

The sub-agent's git history (commits, diffs) lives on the caliban/<name> branch. You can inspect, cherry-pick, or discard it with standard git commands after the run.

Base ref options

The worktree.base_ref field controls what the new branch is rooted on:

Sparse checkout

Set worktree.sparse_paths to a list of path patterns to limit which files are materialized in the worktree. Patterns follow git's sparse-checkout cone format. An empty list (the default) checks out all files.

{
  "prompt": "refactor crates/caliban-tools-builtin",
  "isolation": "worktree",
  "worktree": {
    "base_ref": "head",
    "sparse_paths": ["crates/caliban-tools-builtin/", "Cargo.toml"]
  }
}

Symlinked directories

Large directories that should be shared — not copied — go in worktree.symlink_directories. Each path is relative to the parent repo root. The directory must exist in the parent at creation time.

{
  "prompt": "run the test suite and summarize failures",
  "isolation": "worktree",
  "worktree": {
    "symlink_directories": ["target", "node_modules"]
  }
}

Cleanup behavior

Set CALIBAN_KEEP_WORKTREES=1 to disable automatic removal for debugging. The worktree (and its caliban/<name> branch) will then persist until you remove it manually with git worktree remove and git branch -d.

Operator notes

• Disk usage. Each worktree is a full checkout of the matched paths. Use sparse_paths and symlink_directories to keep sizes manageable. The default head base ref shares git objects with the parent repo, so only working-tree files consume extra disk.
• One worktree per sub-agent. Two concurrent sub-agents with the same name will conflict. Background fleet agents receive auto-generated names based on their id, so fleet-level collisions are not a concern. For foreground parallel agents (a future feature), use distinct names.
• Branch visibility. git branch --list 'caliban/*' shows all active sub-agent branches. You can merge, rebase, or delete them like any other branch.

For how worktree isolation relates to background agents and the caliband daemon, see The Background Fleet.

Memory Tiers

Caliban carries three on-disk memory tiers that are spliced into every system prompt before the session starts. All three are plain Markdown files you can read and edit with any text editor. A fourth tier — MCP-mediated long-form memory — is planned for a future release.

flowchart LR
    G["Global CLAUDE.md\n~/.config/caliban/CLAUDE.md"]
    P["Project tier\n<workspace>/CLAUDE.md\n(+ ancestor walk + @-imports + rules)"]
    A["Auto-memory index\n~/.local/share/caliban/projects/<slug>/memory/MEMORY.md"]
    SP["System prompt"]
    G --> SP
    P --> SP
    A --> SP

The splice order is always global → project → auto-memory, each tier wrapped in an XML-tagged block so the model can distinguish them:

<global-claude-md path="…/CLAUDE.md">
…
</global-claude-md>

<project-claude-md path="…/CLAUDE.md">
…
</project-claude-md>

<auto-memory-index path="…/MEMORY.md">
…
</auto-memory-index>

<default system prompt…>

Missing tiers are silently omitted — no empty tag block is emitted.

Tier 1 — Global

Path: ~/.config/caliban/CLAUDE.md (XDG $XDG_CONFIG_HOME honored)

Owned by the operator. Caliban never writes here. Use it for cross-project preferences: tool choices, tone, coding style, personas. Read once at startup; missing file is fine.

Tier 2 — Project

Path: <workspace_root>/CLAUDE.md — plus the ancestor walk described in CLAUDE.md & Imports.

Owned by the project / repository — commit it like any other file. Contains repo-specific conventions, build commands, and taboos. Caliban never writes here.

Tier 3 — Auto-memory

Directory: ~/.local/share/caliban/projects/<sanitized-cwd>/memory/ (XDG $XDG_DATA_HOME honored; override with CALIBAN_AUTO_MEMORY_DIRECTORY or CALIBAN_MEMORY_DIR).

Owned by the agent. The agent uses ReadMemoryTopic and WriteMemoryTopic — two built-in tools — to maintain a per-project knowledge base across sessions. See Auto-Memory for the full format and write protocol.

Only MEMORY.md (the index, capped at 200 lines / 25 KB) is loaded eagerly each session. Topic files are read on demand.

Token budget

The combined memory prefix defaults to 32 000 tokens (estimated as bytes / 4, provider-agnostic). If the combined size exceeds the cap, the auto-memory tier is truncated first (a [truncated: N bytes] notice is appended to its block), then the project tier, then the global tier.

Per-tier caps can be set in the [memory] block of settings.toml:

[memory]
cap_tokens_auto      = 8000   # cap the auto tier independently
cap_tokens_claude_md = 16000  # cap the combined CLAUDE.md tier
cap_tokens_combined  = 28000  # override the combined ceiling

The same values can be set via environment variables: CALIBAN_MEMORY_BUDGET_TOKENS, CALIBAN_MEMORY_CAP_TOKENS_AUTO, and CALIBAN_MEMORY_CAP_TOKENS_CLAUDE_MD.

When the sum of both per-tier caps would exceed the combined ceiling, each is scaled down proportionally so the sum fits.

The Memory tool and /memory

The built-in Memory tool is the agent-facing interface for reading and writing the auto-memory tier. See Built-in Tools for the full tool reference.

The /memory slash command shows the active tiers, their paths, and their estimated token counts:

/memory
  global   ~/.config/caliban/CLAUDE.md (412 tokens)
  project  /Users/me/dev/myproject/CLAUDE.md (880 tokens)
  auto     ~/.local/share/caliban/projects/…/memory/MEMORY.md (256 tokens)
    walk     /Users/me/dev/myproject/CLAUDE.md (880 tokens)

CLAUDE.md & Imports

The project memory tier is richer than a single file. At session start, caliban walks up the directory tree from the current working directory, concatenating every CLAUDE.md, AGENTS.md, and .caliban.md it finds, then resolves any @-imports inside them and activates path-scoped rules from .caliban/rules/.

Ancestor walk

Starting at cwd, caliban walks toward the filesystem root. The walk stops at the first git root it finds, or the filesystem root, whichever comes first (WalkStop::Both, the default).

Within each directory, files are loaded in most-specific → most-general order: .caliban.md → CLAUDE.md → AGENTS.md. All three are concatenated; they don't override each other.

The resulting files are spliced in broad → narrow order (root-first) so that narrower, more-specific instructions appear later and take precedence in the model's reading.

@-imports

Any of the discovered files may contain @-import directives on their own line:

@./shared/conventions.md
@~/notes/api-style.md
@/abs/path/to/team-guide.md

Import resolution is:

• Depth-bounded to 5 levels of recursion.
• Cycle-detected by canonical path — circular imports are ignored.
• Local paths only. HTTP/HTTPS URLs (@https://…) are rejected outright to keep the prompt-assembly path auditable.
• External imports (paths outside the workspace root and outside ~/.config/caliban/) require one-time approval. The approval decision is persisted to ~/.local/state/caliban/imports-allowlist.json. In non-interactive mode (--print, --bare, CI), external imports are denied unless CALIBAN_APPROVE_IMPORTS=1 is set.

Imported content is inlined at the import site with an <!-- imported from … --> marker so the model can trace provenance.

Nested on-demand

When the model reads or edits a file in a subdirectory that has its own CLAUDE.md, that file is appended to the system prompt for the rest of the session. This happens once per (path, session) pair — caliban does not reload on file changes or unload when the model leaves the subtree.

The system prompt grows monotonically during a session. This is intentional: operators reason about it as "everything the model has been told", not as a sliding window.

Path-scoped rules

Files under .caliban/rules/<topic>.md are loaded with optional paths: glob frontmatter:

---
paths:
  - "src/**/*.ts"
  - "tests/**/*.ts"
---

Always use `strict` TypeScript. Prefer `unknown` over `any`.

Rules without a paths: frontmatter are always-active and loaded at startup. Rules with paths: frontmatter are activated lazily on the first file touch matching any pattern in the set. Once activated, a rule stays in the prompt for the rest of the session.

claude_md_excludes for monorepos

Large monorepos often have directories whose CLAUDE.md should not be spliced into every session. Add gitignore-style patterns to settings.toml to skip them during the ancestor walk:

claude_md_excludes = [
  "node_modules/**",
  "vendor/**",
  "third_party/**/CLAUDE.md",
]

Patterns are evaluated relative to the workspace root (the cwd at startup), not the absolute filesystem path. Last-match wins for a given path; ! negation is supported.

The same patterns can be supplied at runtime via the colon- or newline-separated CALIBAN_CLAUDE_MD_EXCLUDES environment variable.

Additional directories

--additional-directories (or additional_directories in settings.toml) extends the set of paths the file tools can access. These directories do not contribute CLAUDE.md content by default. Set CALIBAN_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to opt in — each added path then performs its own ancestor walk, concatenated after the cwd walk in declaration order.

Auto-Memory

Auto-memory is the agent-writable third tier of caliban's memory model. At the start of each session, caliban splices a per-project index file (MEMORY.md) into the system prompt. During the session, the agent uses two built-in tools — ReadMemoryTopic and WriteMemoryTopic — to read and write Markdown topic files that persist knowledge across sessions.

Directory layout

~/.local/share/caliban/projects/<sanitized-cwd>/memory/
  MEMORY.md              ← index, spliced into every session (≤ 200 lines / 25 KB)
  build-commands.md      ← topic file
  api-conventions.md     ← topic file
  deploy-checklist.md    ← topic file
  …

The <sanitized-cwd> slug is derived from the canonical workspace path (e.g. /Users/jf/dev/caliban → Users-jf-dev-caliban). Override the directory with CALIBAN_AUTO_MEMORY_DIRECTORY or CALIBAN_MEMORY_DIR.

The index file (MEMORY.md)

MEMORY.md is the only file loaded eagerly each session. It must stay under 200 lines / 25 KB so it fits comfortably inside the splice budget. Caliban bootstraps an empty MEMORY.md with a conventions block the first time the memory directory is accessed.

A typical index looks like:

# Memory index

- [build-commands](build-commands.md) — project: `cargo build --release`; binary lands in `target/release/`
- [api-conventions](api-conventions.md) — feedback: prefer the built-in HTTP helper over shelling out to curl
- [deploy-checklist](deploy-checklist.md) — project: run migrations before flipping the feature flag

HTML comments (<!-- … -->) in MEMORY.md are stripped from the spliced prompt but kept on disk. The auto-injected conventions block is wrapped in HTML comments for this reason — it stays on disk for authoring guidance but does not consume token budget.

Topic file format

Each topic file is a Markdown file with YAML frontmatter:

---
name: sprint-mode
description: "user prefers consolidated design proposals + spec + plan + implementation in one pass"
metadata:
  node_type: memory
  type: feedback
---

User prefers a single-pass workflow: design proposal, spec, plan, and
implementation delivered together without a human review checkpoint in
between.

Slug rules: non-empty, no path separators, no .., no leading ..

Memory types

The agent classifies each topic at write time. There is no automated classifier — the model is best positioned to judge what to save.

Built-in tools

Both tools are sandboxed to the memory directory — path traversal attempts are rejected at the tool level.

WriteMemoryTopic performs an atomic write:

1. Write topic body + frontmatter to <slug>.md.tmp.
2. Rename to <slug>.md (atomic on the same filesystem).
3. Rewrite MEMORY.md with an updated index line for the slug (same tmp-then-rename approach).

A crash between steps 2 and 3 leaves an orphan topic file. Run /memory rebuild-index to repair it.

Managing memory

There is no automatic pruning. Memories persist until manually removed.

Cross-references between topics

Topic bodies may contain [[slug]] cross-references, for example [[parity-gap-matrix]]. These are informational breadcrumbs — caliban does not auto-follow them. The agent can follow a reference by calling ReadMemoryTopic with the referenced slug.

Disable for CI

Set CALIBAN_DISABLE_AUTO_MEMORY=1 to drop the auto-memory tier from the splice and suppress the auto-memory skill. This guarantees identical system prompts regardless of on-disk memory state. --bare sets the same flag automatically.

Checkpoints & Rewind

Caliban takes a per-prompt snapshot of every file that a file-writing tool touched during that prompt's turns. If you don't like the result, /rewind lets you pick any prior prompt and restore the files, the conversation, or both — without losing the history of what happened in between.

What gets snapshotted

The checkpoint recorder fires on Write, Edit, MultiEdit, and NotebookEdit. Before any of these tools mutates a file for the first time within a prompt, caliban reads the pre-image and stores it content-addressed under the per-prompt blob directory.

Plan-mode prompts (which reject mutating tools) emit an empty manifest so they are still selectable as conversation-rewind targets.

Disk layout

~/.local/share/caliban/projects/<cwd-hash>/checkpoints/<session>/
  prompt-001/
    manifest.json
    blobs/<sha256>.bin
  prompt-002/
    manifest.json
    blobs/<sha256>.bin
  …

<cwd-hash> is the first 16 hex characters of sha256(canonical_cwd). Override the root with CALIBAN_CHECKPOINT_ROOT. Disable recording entirely with CALIBAN_CHECKPOINT_DISABLED=1.

Each manifest.json records:

For each entry, exists_pre: false means the file was created by the prompt (restore will delete it). Blobs are content-addressed — the same pre-image across two prompts is stored once.

Triggering /rewind

Open the rewind overlay from the TUI in two ways:

• Type /rewind at the prompt.
• Press Esc Esc (two Esc presses within 400 ms) when the input buffer is empty.

The overlay lists prompts newest-first. Navigate with arrow keys, confirm with Enter.

Restore options

"Truncate conversation" removes all messages after the selected prompt's last assistant message, so the conversation ends at that point in time.

Storage limits and pruning

CALIBAN_CHECKPOINT_MAX_BYTES caps total blob storage per project (default 5 GiB). When the cap is exceeded, oldest prompt blobs are dropped first; the manifest is kept as a cleared marker so the prompt remains selectable for conversation rewind (but file restore is no longer possible).

A checkpoint directory is removed only when cleanupPeriodDays (default 30) has elapsed since its last update and the corresponding session is being pruned by the session store. Checkpoints are never orphaned while a session is still resumable.

Context & Compaction

Every provider has a finite context window. Caliban tracks utilization in real time and provides several tools — automatic and manual — to keep long sessions healthy without losing important history.

Context tracking

Caliban maintains a ContextWindow counter that accumulates token usage from every provider response. This is independent of the telemetry subsystem: the /context command and the TUI status-bar percentage work for all users regardless of whether CALIBAN_ENABLE_TELEMETRY is set.

/context
  input tokens used : 62 430 / 200 000  (31%)
  output tokens used: 4 812
  ⚠ approaching limit (warn threshold: 80%)

/context shows a per-message-kind breakdown and warns when utilization reaches 80%. See Telemetry & Cost for OTLP export of context metrics.

Auto-compaction

When the context-window utilization reaches auto_compact_threshold, caliban automatically runs the configured compactor before the next turn. The default threshold is 0.75 (75% utilization).

Configure in settings.toml:

auto_compact_threshold = 0.75   # 0.0–1.0; unset or null disables autocompact

Set auto_compact_threshold to null (or omit it) to disable autocompact entirely and rely on manual /compact invocations.

Compaction strategy

Both autocompact and manual /compact run the compactor selected by compact_strategy:

compact_strategy = "summarize"   # "summarize" (default) | "drop-oldest" | "noop"

summarize and drop-oldest keep leading system messages and the most recent turns verbatim, and only act once utilization is high enough that there is older history to shed. Unknown values fall back to summarize.

Micro-compaction

Micro-compaction is an LLM-free per-turn pass that supersedes stale ToolResult blocks in the conversation history without making any API calls.

The logic is per-tool:

When a newer result for the same key exists, the older result block is replaced with a [superseded: <tool>(<key>)] placeholder, keeping message structure intact but recovering tokens.

Enable or disable in settings.toml:

micro_compact_enabled = true    # default: true

Manual /compact

/compact triggers an immediate compaction of the current conversation through the configured Compactor (the same path used by autocompact). A compact.event log entry is emitted and a compact.event metric is recorded if telemetry is enabled.

/compact

No flags. The strategy is determined by compact_strategy (see Compaction strategy above) — see Hooks for the PreCompact / PostCompact hook events that fire around each compaction.

/clear

/clear resets the conversation to an empty state and zeroes the ContextWindow counter. The session file is updated. Use it to start a fresh sub-task without opening a new session.

/clear

PreCompact and PostCompact hooks

Caliban fires PreCompact before compaction begins and PostCompact after it completes. These hook events are available to external scripts and MCP handlers.

# In settings.toml [hooks]
[hooks]
PreCompact  = [{ type = "command", command = "echo compacting…" }]
PostCompact = [{ type = "command", command = "notify-send 'compact done'" }]

See Hooks for the full hook configuration reference.

Prompt caching

Caliban uses Anthropic-style prompt caching by default to reduce cost on repeated turns. A cache marker is placed on the last user message when its estimated token count meets the minimum threshold.

Configure min_cache_block_tokens in settings.toml:

min_cache_block_tokens = 1024   # omit to use the upstream default

Tool result size cap

Caliban can cap the character length of individual tool results before they are appended to the conversation. This prevents a single large Read or Bash output from consuming a disproportionate share of the context window.

tool_result_cap_chars = 65536   # 0 disables the cap (default)

Summary of relevant settings

Print Mode

Print mode is caliban's non-interactive entry point. Instead of launching the TUI, it drives the agent to completion and writes results to stdout — making caliban scriptable from a shell, a CI job, or any program that can invoke a subprocess.

Activating print mode

Auto-headless fires when a prompt is given and stdout is piped or stdin is not a TTY. Pass --no-auto-print to suppress this inference and keep the TUI even in piped contexts.

Choosing an output format

--output-format text|json|stream-json

Supplying input

By default caliban reads the prompt from the positional argument or --prompt. To pipe multi-line input, pass - as the prompt value and write to stdin:

git diff HEAD | caliban -p - "review these changes"

For multi-turn scripted sessions use --input-format stream-json to send NDJSON user frames on stdin instead. When this flag is active, a non-- inline prompt is rejected at startup (exit 64) to prevent accidentally bypassing the frame parser. See The stream-json Protocol for details.

Budget guard

--max-budget-usd <USD>

Caps the cumulative spend for a run. Cost is tracked against the vendored rate card in caliban-telemetry. When the budget is exceeded after a turn completes, caliban emits a result frame with subtype: "budget_exceeded" and exits 137. Unknown (provider, model) pairs contribute $0.00 and emit a single warning — the run is not blocked.

Deterministic runs with --bare

caliban --bare -p "count lines of code"

--bare skips hooks, skills, plugins, MCP server discovery, auto-memory, and CLAUDE.md walk-up. The agent runs with only its built-in tools and the flags you supply. Use it when you need a fully reproducible run that ignores user and project settings.

Exit codes

CI scripts can distinguish budget exhaustion from genuine failures without parsing stdout: $? carries the signal.

Session persistence

Print-mode runs honour --session <NAME>, --continue (-c), and --resume the same way as interactive sessions. Pass --no-save to skip writing the session back to disk after the run.

Related pages

• The stream-json Protocol — detailed frame reference
• Structured Output — --json-schema for schema-conformant replies
• CI Patterns — complete recipes for GitHub Actions and other pipelines

The stream-json Protocol

--output-format stream-json is caliban's full automation contract. It emits newline-delimited JSON (NDJSON) to stdout, one frame per line, in a well-defined order. Downstream programs parse the stream with any JSON library and route on the type (and subtype) fields.

The protocol mirrors Claude Code's stream-json shape closely enough that most existing consumers work with minimal changes, while remaining provider-agnostic — token field names and cost breakdowns differ by provider and are not byte-identical to Claude Code.

Output frame types

system/init — first frame of every run

Emitted before any agent activity begins.

{
  "type": "system",
  "subtype": "init",
  "session_id": "a3f7c2d1-...",
  "model": "anthropic/claude-sonnet-4-6",
  "tools": ["Bash", "Edit", "Glob", "Grep", "Read", "Write"],
  "plugins": [],
  "settingSources": ["managed", "user", "project"],
  "mcp_servers": [],
  "bare_mode": false,
  "cwd": "/home/ci/repo",
  "permission_mode": "acceptEdits"
}

settingSources uses camelCase for Claude Code parity. permission_mode values are default, acceptEdits, plan, auto, dontAsk, bypassPermissions, or "disabled" (when --no-permissions is in effect).

system/api_retry

Emitted when the provider triggers a retry (rate-limit, overload, transient network error).

{
  "type": "system",
  "subtype": "api_retry",
  "attempt": 2,
  "max_retries": 5,
  "retry_delay_ms": 1500,
  "error_status": 529,
  "error_category": "overloaded"
}

error_category values: overloaded, rate_limit, timeout, network, server_error, other.

user — echo of the user prompt

Only emitted when --replay-user-messages is set.

{
  "type": "user",
  "content": [{"type": "text", "text": "fix the failing tests"}]
}

text — incremental assistant text delta

Only emitted when --include-partial-messages is set.

{"type": "text", "delta": "Here is the fix: "}

thinking — incremental reasoning delta

Emitted under --include-partial-messages when the model streams reasoning content (extended thinking models).

{"type": "thinking", "delta": "Let me check the test output…"}

tool_use and tool_result — progress frames

Each tool invocation produces a tool_use frame (emitted once the model finishes streaming the tool's input JSON) immediately followed by a tool_result frame (emitted once the tool completes).

{"type": "tool_use", "id": "toolu_01ABC", "name": "Bash", "input": {"command": "cargo test"}}
{"type": "tool_result", "tool_use_id": "toolu_01ABC", "is_error": false, "content": [{"type": "text", "text": "test result: ok. 42 passed"}]}

When --include-tool-dispatch-events is set, each tool_result frame also carries a t_ms field — the wall-clock milliseconds caliban spent dispatching that tool call — so consumers can correlate per-tool latency (#28). The field is omitted entirely when the flag is off.

message — full assistant message (authoritative)

Emitted at the end of each turn when --include-partial-messages is not set. When --include-partial-messages is set, text deltas stream via text frames instead and no message frame is emitted.

{
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "All tests pass now."},
    {"type": "tool_use", "id": "toolu_01ABC", "name": "Bash", "input": {"command": "cargo test"}}
  ]
}

hook_event

Only emitted when --include-hook-events is set.

{
  "type": "hook_event",
  "hookEventName": "PreToolUse",
  "hookSpecificOutput": {"matcher": "Bash", "decision": "allow"}
}

hookEventName and hookSpecificOutput are camelCase (ADR 0024 parity).

warning

Non-fatal informational frames that do not terminate the run. Currently emitted for model substitution detected at the provider level.

{
  "type": "warning",
  "subtype": "model_mismatch",
  "message": "model mismatch: requested \"llama3.1\" but provider responded with \"llama3.2\"",
  "details": {"requested": "llama3.1", "actual": "llama3.2"}
}

result — always the last frame

{
  "type": "result",
  "subtype": "success",
  "result": "All 42 tests pass.",
  "session_id": "a3f7c2d1-...",
  "total_cost_usd": 0.0034,
  "turns": 3,
  "total_input_tokens": 8210,
  "total_output_tokens": 621
}

subtype values:

For non-success subtypes, result is absent. Read last_assistant_text for the most recent assistant reply and tool_calls_seen to distinguish an actively-looping agent (many tool calls, no clean finish) from one that stalled silently.

Stream-json input (--input-format stream-json)

Pass --input-format stream-json to make caliban read NDJSON user frames from stdin instead of a single prompt. This lets you drive multi-turn conversations from any language without a pseudo-TTY.

{"type": "user", "content": "fix the lint warnings"}
{"type": "user", "content": [{"type": "text", "text": "now run the tests"}]}

content can be a plain string or an array of {"type":"text","text":"…"} blocks. Unknown fields on user frames, unknown type values, and malformed JSON are hard parse errors — the run aborts with exit 64 and a result frame with subtype: "error". This is intentional: silent parsing of an unknown field would let a wrong envelope shape run the agent with a blank prompt.

A control/interrupt frame is accepted on stdin but the interrupt is not yet honored; caliban emits a stderr warning and continues.

When --input-format stream-json is active, an inline prompt is incompatible and is rejected at startup. Pass - (or omit the prompt entirely) to read from stdin.

Example NDJSON exchange

printf '{"type":"user","content":"how many Rust source files are here?"}\n' \
  | caliban --output-format stream-json \
            --input-format stream-json \
            --replay-user-messages \
            --bare

{"type":"system","subtype":"init","session_id":"b1c2...","model":"anthropic/claude-sonnet-4-6","tools":["Bash","Glob","Grep","Read"],"plugins":[],"settingSources":[],"mcp_servers":[],"bare_mode":true,"cwd":"/repo","permission_mode":"default"}
{"type":"user","content":[{"type":"text","text":"how many Rust source files are here?"}]}
{"type":"tool_use","id":"toolu_01","name":"Bash","input":{"command":"find . -name '*.rs' | wc -l"}}
{"type":"tool_result","tool_use_id":"toolu_01","is_error":false,"content":[{"type":"text","text":"142"}]}
{"type":"message","role":"assistant","content":[{"type":"text","text":"There are 142 Rust source files."},{"type":"tool_use","id":"toolu_01","name":"Bash","input":{"command":"find . -name '*.rs' | wc -l"}}]}
{"type":"result","subtype":"success","result":"There are 142 Rust source files.","session_id":"b1c2...","total_cost_usd":0.0012,"turns":1,"total_input_tokens":3100,"total_output_tokens":48}

Optional frame flags

Related pages

• Print Mode — activating headless mode and output formats
• CI Patterns — parsing stream-json in scripts and Actions

Structured Output

--json-schema tells caliban to force the assistant's final reply into a JSON shape that matches a given schema. This is useful when a downstream script needs a machine-readable payload rather than freeform prose — a CI gate that needs a structured pass/fail verdict, a code-generation pipeline that expects a specific object shape, or any tool that would otherwise parse the reply with fragile string matching.

Supplying a schema

--json-schema <FILE_OR_JSON>

The argument is either:

• A path to a .json file: --json-schema ./schema.json
• Inline JSON (detected when the value starts with { or [): --json-schema '{"type":"object","required":["ok","message"]}'

What caliban does

1. Runs the agent loop normally.
2. After the final assistant turn, scans the reply for a balanced {...} JSON object. If the whole reply is valid JSON it is used as-is; otherwise the first balanced {...} block is extracted.
3. Validates the extracted object against the schema (required fields present, top-level and per-property types match).
4. On success: the validated object appears in the structured_output field of the result frame, and the process exits 0.
5. On failure: the result frame has subtype: "error" and the validation message appears in error. The process exits 2.

Worked example

Suppose you want caliban to report whether a repository's tests pass, in a structured format.

schema.json

{
  "type": "object",
  "required": ["passed", "summary"],
  "properties": {
    "passed": {"type": "boolean"},
    "summary": {"type": "string"},
    "failure_count": {"type": "integer"}
  }
}

Invocation

caliban \
  --output-format json \
  --json-schema ./schema.json \
  --bare \
  -p "Run the test suite and tell me whether it passed. Reply only with JSON."

Successful result frame (stdout)

{
  "type": "result",
  "subtype": "success",
  "result": "{\"passed\": true, \"summary\": \"42 tests passed, 0 failed\", \"failure_count\": 0}",
  "session_id": "...",
  "total_cost_usd": 0.0021,
  "turns": 2,
  "total_input_tokens": 5400,
  "total_output_tokens": 310,
  "structured_output": {
    "passed": true,
    "summary": "42 tests passed, 0 failed",
    "failure_count": 0
  }
}

Read structured_output in your script:

result=$(caliban --output-format json --json-schema schema.json --bare \
           -p "Run tests and reply with JSON.")
passed=$(echo "$result" | jq '.structured_output.passed')
if [ "$passed" != "true" ]; then
  echo "Tests failed"
  exit 1
fi

Failed validation (exit 2)

{
  "type": "result",
  "subtype": "error",
  "error": "missing required field `passed`",
  "session_id": "...",
  "total_cost_usd": 0.0018,
  "turns": 1,
  "total_input_tokens": 4800,
  "total_output_tokens": 95,
  "last_assistant_text": "All tests passed."
}

Tips

• Instruct the model to reply only with JSON in your prompt. Models that wrap their answer in prose (e.g. "Here is the result: {...}") are handled — caliban scans for the first balanced {...} — but pure JSON replies validate more reliably.
• Combine with --bare to skip skills and hooks that might inject extra text into the reply.
• In stream-json mode, the structured_output field appears in the final result frame the same as in json mode.

Related pages

• Print Mode — output formats and exit codes
• CI Patterns — complete pipeline recipes using structured output

CI Patterns

This page puts the headless flags together into complete, copyable recipes for GitHub Actions and other CI environments. Before reading further, familiarise yourself with Print Mode, The stream-json Protocol, and Headless & Audit.

Key flags for CI

Exit codes are the primary success signal. See Print Mode — Exit codes for the full table. $? == 0 means success; $? == 137 means the budget cap fired.

Recipe 1 — Simple text answer in GitHub Actions

Suitable for jobs that just need a freeform answer and check the exit code.

# .github/workflows/caliban-check.yml
name: caliban check

on: [push]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run caliban review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          caliban \
            --bare \
            --max-budget-usd 0.50 \
            --permission-mode acceptEdits \
            --no-save \
            -p "Review the diff for obvious bugs and print a one-sentence verdict."

The job fails if caliban exits non-zero (runtime error, budget exceeded, etc.).

Recipe 2 — Structured output with jq parsing

Use --output-format json and --json-schema when you need machine-readable output — for example, a gate that checks whether a review verdict is "pass" or "fail".

#!/usr/bin/env bash
# ci/review-gate.sh
set -euo pipefail

RESULT=$(caliban \
  --output-format json \
  --json-schema '{"type":"object","required":["verdict","reason"]}' \
  --bare \
  --max-budget-usd 1.00 \
  --permission-mode acceptEdits \
  --allow "Bash:git diff*" \
  --allow "Read" \
  --no-save \
  -p "Review the staged changes. Reply ONLY with JSON: {\"verdict\": \"pass\"|\"fail\", \"reason\": \"<one sentence>\"}")

echo "Raw result: $RESULT"
VERDICT=$(echo "$RESULT" | jq -r '.structured_output.verdict')

if [ "$VERDICT" = "pass" ]; then
  echo "Review passed: $(echo "$RESULT" | jq -r '.structured_output.reason')"
  exit 0
else
  echo "Review failed: $(echo "$RESULT" | jq -r '.structured_output.reason')"
  exit 1
fi

Recipe 3 — Multi-turn stream-json pipeline

For jobs that drive several agent turns or need to observe tool calls in real time, parse the NDJSON stream line by line.

#!/usr/bin/env bash
# ci/stream-pipeline.sh
set -euo pipefail

TASKS=$(cat <<'EOF'
{"type":"user","content":"Run the test suite and report any failures."}
{"type":"user","content":"If any tests failed, suggest a fix."}
EOF
)

LAST_RESULT=""
TOOL_CALLS=0

while IFS= read -r line; do
  [ -z "$line" ] && continue
  TYPE=$(echo "$line" | jq -r '.type')
  case "$TYPE" in
    system)
      SUBTYPE=$(echo "$line" | jq -r '.subtype')
      if [ "$SUBTYPE" = "init" ]; then
        echo "[init] model=$(echo "$line" | jq -r '.model')"
      fi
      ;;
    tool_use)
      TOOL_CALLS=$((TOOL_CALLS + 1))
      echo "[tool] $(echo "$line" | jq -r '.name')"
      ;;
    result)
      LAST_RESULT="$line"
      SUBTYPE=$(echo "$line" | jq -r '.subtype')
      COST=$(echo "$line" | jq -r '.total_cost_usd')
      echo "[result] subtype=$SUBTYPE cost=\$$COST tool_calls=$TOOL_CALLS"
      ;;
  esac
done < <(echo "$TASKS" | caliban \
    --output-format stream-json \
    --input-format stream-json \
    --bare \
    --max-budget-usd 2.00 \
    --permission-mode acceptEdits \
    --allow "Bash:cargo test*" \
    --no-save)

# Final check
EXIT_CODE=$?
SUBTYPE=$(echo "$LAST_RESULT" | jq -r '.subtype')
if [ "$EXIT_CODE" -ne 0 ] || [ "$SUBTYPE" != "success" ]; then
  echo "Run did not succeed (exit=$EXIT_CODE subtype=$SUBTYPE)"
  exit 1
fi

Permissions in headless mode

By default, caliban inherits all user and project permission rules in headless mode, just as in interactive sessions. For CI you typically want tighter control:

• --permission-mode acceptEdits — auto-allows file edits; still asks (or denies) for shell commands not covered by a rule.
• --allow "Bash:git *" — add a top-priority Allow rule for specific shell patterns.
• --deny "Bash:rm -rf*" — add a top-priority Deny rule.
• --bare — skip all settings-derived rules (only built-in defaults apply).

For a full discussion of permission modes and how they interact with headless runs, see Headless & Audit.

Parsing exit codes in shell

caliban --bare --max-budget-usd 0.20 -p "summarize the diff" || {
  CODE=$?
  case $CODE in
    75)  echo "Max turns exceeded";;
    137) echo "Budget cap hit";;
    124) echo "Cancelled";;
    *)   echo "Error: exit $CODE";;
  esac
  exit $CODE
}

Related pages

• Print Mode
• The stream-json Protocol
• Structured Output
• Headless & Audit

Driving Caliban

Print mode (Print Mode) runs caliban to completion and hands you the result. The driveable server surfaces go further: they expose a running agent that an external program steers — start a run, watch its events stream by, feed it follow-up input, and answer the permission prompts it raises — with no TUI in the loop.

There are three surfaces, each targeting a different kind of consumer, all built as thin protocol adapters over one shared drive core (see ADR 0055):

They are not substitutes — pick the one that matches how your consumer wants to talk to caliban.

The shared contract

Every surface exposes the same four operations over the drive core. The wire format differs; the semantics do not.

Lifecycle status

A run moves through these states (caliban_drive::DriveStatus):

starting → running → (awaiting_input ⇄ running)* → done | failed

A non-interactive run never enters awaiting_input — it goes running → done. failed carries an error string. On the MCP and HTTP surfaces status is a JSON object tagged by state (e.g. { "state": "awaiting_input" }); on ACP the turn boundary is conveyed as the stopReason of a session/prompt call.

The event envelope

The poll-based surfaces (MCP, HTTP) wrap each TurnEvent in a versioned envelope so the event schema can evolve without breaking clients:

{ "v": 1, "event": { "type": "AssistantTextDelta", "text": "Hello", ... } }

ACP instead translates each TurnEvent into a native session/update notification (agent_message_chunk, tool_call, …).

Auth model

One policy, applied uniformly by every surface (CALIBAN_DRIVE_TOKEN, building on the caliband bearer scheme):

• Loopback is open. A connection from the local host is trusted — loopback / the local filesystem is the boundary. caliban mcp serve and caliban acp serve run over stdio, which is loopback-inherent, so they always admit the peer.
• Remote requires a bearer token. A non-loopback peer must present Authorization: Bearer <token> matching the CALIBAN_DRIVE_TOKEN set out of band (env / secret), compared in constant time.
• Fail closed. Binding a surface to a non-loopback address with no token configured is refused — caliban never serves unauthenticated on the network.

Transport encryption (TLS) for remote binds is the deployment's concern and is out of scope for the gate.

Permissions

A driven run still enforces Permissions v2. When a tool call matches an Ask rule and there is no TUI to prompt, the request is surfaced back over the surface's own channel and its decision routed into the run — the run never bypasses the permission model or fails open:

• MCP — the prompt appears in the caliban_poll response's permission_request; answer it with caliban_permit.
• ACP — the agent sends a session/request_permission request; the client replies with the selected option.
• HTTP — the prompt appears in the GET …/events response's permission_request; answer it with POST …/permit.

If no client answers within the timeout (10 minutes), the request is denied.

Design rationale

See ADR 0055 · Driveable server surface for why caliban ships all three surfaces over one core rather than picking one, and how they reuse the existing headless / attach internals.

MCP Server

caliban mcp serve exposes caliban as an MCP server that another agent can drive as a worker or tool. This is the path for a gateway or control plane (e.g. Prospero) to adopt caliban as a backend, and for Codex-style mcp-server parity.

v1 is stdio-only with poll-based unary tools: MCP tool calls are request/response, but the drive core is a stream, so a run is driven by caliban_run → repeated caliban_poll rather than a live push.

caliban mcp serve

The peer connects over stdio and speaks MCP. Because stdio is loopback-inherent, the auth gate admits the peer; CALIBAN_DRIVE_TOKEN only bites on the network-facing HTTP surface.

Tools

Driving a run

1. caliban_run { "prompt": "list the crates", "interactive": false } → note the run_id.
2. Loop caliban_poll { "run_id": …, "cursor": 0 }, advancing cursor to the returned next_cursor each time, appending the events. Each event is a { v, event } envelope (see the event envelope).
3. Stop when status.state is done or failed.

For an interactive run, poll until status.state is awaiting_input, then caliban_send_input { "run_id": …, "text": "…" } to continue, or { "run_id": …, "end": true } to finish.

Answering permission prompts

When a poll returns a permission_request:

{ "tool_use_id": "toolu_01…", "tool_name": "Bash", "input": { "command": "rm -rf build" } }

answer it before the run can proceed:

caliban_permit { "run_id": "…", "tool_use_id": "toolu_01…", "allow": false, "reason": "destructive" }

Registering caliban in an MCP client

Point any MCP client's server config at the stdio command:

{
  "mcpServers": {
    "caliban": {
      "command": "caliban",
      "args": ["mcp", "serve"]
    }
  }
}

The transports and OAuth flow that a remote MCP endpoint layers on top follow ADR 0023; the drive surface itself is defined by ADR 0055.

ACP

caliban acp serve exposes caliban as an Agent Client Protocol (ACP) agent so editors and editor-shaped tools — the Zed / OpenCode / Grok Build drive-in path — can drive it interactively, turn by turn. Unlike the poll-based MCP and HTTP surfaces, ACP is push/streaming: a session/prompt call blocks for the duration of one agent turn while the adapter streams session/update notifications, then returns a stopReason.

The wire is newline-delimited JSON-RPC 2.0 over stdio — one JSON object per line, no LSP-style Content-Length framing.

caliban acp serve

Most editors don't run this by hand — they spawn it as the agent subprocess for their ACP integration. stdio is loopback-inherent, so the auth gate admits the peer.

Methods

Client → agent:

Agent → client:

• session/update (notification) — one TurnEvent mapped to an ACP update: agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update.
• session/request_permission (request) — a driven run's Ask, surfaced into the editor's own permission UI (see below).

v1 scope. The core session lifecycle above is implemented. loadSession, the fs/* and terminal/* client methods, and applying the mcpServers declared at session/new are not yet wired.

A minimal handshake

Each line below is one JSON-RPC frame (→ sent by the client, ← received). Requests are correlated by id; notifications have no id.

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{…},"authMethods":[]}}

→ {"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/repo","mcpServers":[]}}
← {"jsonrpc":"2.0","id":2,"result":{"sessionId":"sess-1"}}

→ {"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"sess-1","prompt":[{"type":"text","text":"summarize the README"}]}}
← {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"sess-1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"The README "}}}}
← {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"sess-1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"describes…"}}}}
← {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

Send another session/prompt on the same sessionId to continue the conversation (it resumes the same run), or session/cancel to end the current turn early — its prompt call returns { "stopReason": "cancelled" }.

Permission prompts

When the run hits a tool call gated by an Ask rule, the agent sends a request and waits for the editor's answer:

← {"jsonrpc":"2.0","id":7,"method":"session/request_permission","params":{
     "sessionId":"sess-1",
     "toolCall":{"toolCallId":"toolu_01…","title":"Bash","rawInput":{"command":"cargo test"}},
     "options":[{"optionId":"allow","name":"Allow","kind":"allow_once"},
                {"optionId":"reject","name":"Reject","kind":"reject_once"}]}}

→ {"jsonrpc":"2.0","id":7,"result":{"outcome":{"outcome":"selected","optionId":"allow"}}}

Selecting allow lets the tool run; reject (or a cancelled/absent outcome) denies it. The decision routes straight into the run through the permission-elicitation bridge.

See ADR 0055 for the design rationale.

HTTP Serve

caliban http serve exposes caliban over plain HTTP/JSON so a script or curl can drive it with no protocol client at all. Same poll-based, cursor-driven shape as the MCP surface, with the { v, event } event envelope.

caliban http serve                       # binds 127.0.0.1:8730 by default
caliban http serve --addr 127.0.0.1:9000

Auth and binding

This is where the bearer path actually bites:

• A loopback bind (the default) is open — no token needed.
• A non-loopback bind requires CALIBAN_DRIVE_TOKEN, and every remote request must send Authorization: Bearer <token>. Binding to a non-loopback address with no token set is refused (fail closed).

CALIBAN_DRIVE_TOKEN=s3cret caliban http serve --addr 0.0.0.0:8730

Endpoints

A curl session

Start a run:

RUN=$(curl -s localhost:8730/runs \
  -H 'content-type: application/json' \
  -d '{"prompt":"list the crates","interactive":false}' | jq -r .run_id)

Poll for events, advancing the cursor until the run is terminal:

cursor=0
while :; do
  resp=$(curl -s "localhost:8730/runs/$RUN/events?cursor=$cursor")
  echo "$resp" | jq -c '.events[].event'
  cursor=$(echo "$resp" | jq .next_cursor)
  state=$(echo "$resp" | jq -r .status.state)
  [ "$state" = "done" ] || [ "$state" = "failed" ] && break
  sleep 0.2
done

For an interactive run, poll until .status.state == "awaiting_input", then:

curl -s localhost:8730/runs/$RUN/input -H 'content-type: application/json' -d '{"text":"and now the tests"}'
curl -s localhost:8730/runs/$RUN/input -H 'content-type: application/json' -d '{"end":true}'

Answering a permission prompt

If an events response carries a permission_request, answer it before the run continues:

curl -s localhost:8730/runs/$RUN/permit \
  -H 'content-type: application/json' \
  -d '{"tool_use_id":"toolu_01…","allow":true}'

A remote client adds -H "Authorization: Bearer $CALIBAN_DRIVE_TOKEN" to every request.

See ADR 0055 for the design rationale.

Telemetry & Cost

caliban tracks token usage and USD cost for every session using caliban-telemetry (ADR 0033). Cost accounting and context-window tracking work for all users regardless of whether OTLP export is enabled. OTLP emission to an external collector is opt-in.

Cost accounting

After each provider response, caliban-telemetry multiplies token counts by per-model rates from a vendored YAML rate card. The card ships with known rates for Anthropic, OpenAI, Google, Bedrock, Vertex, and Ollama (Ollama rows are $0.00).

Unknown (provider, model) pairs contribute $0.00 and emit a single debounced warning per session. Rates are updated in-tree; operators can override the card with CALIBAN_RATES_YAML=/path/to/rates.yaml.

USD arithmetic uses rust_decimal internally to avoid floating-point drift. Values are converted to f64 only at OTLP emit boundaries.