Docs

Configuration

Defaults are meant to work after captain init and captain doctor. Bare prompts always hit captain.

Local data

~/.captaincode/state.json is the durable ledger: charges, decisions, quotas, budgets, task lifecycle, outcomes and handoffs. Daily history/*.jsonl files are append-only transcripts, not the same store. Saves merge append-only collections so concurrent writers cannot clobber each other.

Core

Variable	Default	Role
`CAPTAIN_BRAIN_URL`	`http://127.0.0.1:14097`	Brain endpoint
`CAPTAIN_DIRECTOR`	derived by init (claude preferred)	Director model (excluded from worker pool); first in comma list; may be frontier/quality/auto. Brain and init pick runnable when possible.
`CAPTAIN_FAST_ROUTE`	unset	Skip director; use heuristic ladder
`CAPTAIN_MAX_ATTEMPTS`	unset (unlimited)	Shared attempt cap for a task
`CAPTAIN_MAX_COST`	unset	USD cost cap (tracked; strict mode can reject cost-incapable legs)
`CAPTAIN_STRICT`	off	With a cost cap, only cost-reporting adapters may run
`CAPTAIN_TASK_TOKEN`	unset	Bearer token for `/v1/task/*`; unset ⇒ loopback-only
`CAPTAIN_ADI_URL`	published `leaderboard.json`	ADI feed for `/deterministic` (URL or local path). Cached in `~/.captaincode/adi.json`, refreshed every 6h. `CAPTAIN_ADI=0` turns the feed off.
`CAPTAIN_INTERRUPT_GRACE`	`3m`	How long a handoff interrupt may wait before a hard stop

Pools: `/oss` and `/deterministic`

/oss <task> runs on open-weight models only. /deterministic <task> runs on a leg whose serving tuple is green in the Agentic Determinism Index right now, and pins the OpenRouter request to that tuple (provider.order, allow_fallbacks: false, temperature: 0). Both are modifiers like /quality: they compose with /repeat, /parallel, /team, /frontier and a leg prefix in either order. Nothing in the pool → the turn runs without it and the feed says why. captain adi prints every leg’s standing. Full detail: ADI docs.

Stopping mid-run: `/interrupt`

/interrupt [reason] ends the in-flight worker and keeps what it did. Claude and opencode-served legs write a handoff note; codex-cli and cursor stop immediately and keep a marked partial. Interrupted runs are never rerouted. See also /btw for mid-run steering without stopping.

Minimal profile (Claude + Cursor only)

A common minimal machine has only claude and cursor. After captain init, director and fallback are derived from PATH (claude + cursor here). The director is excluded from the worker pool. If env still names an absent leg, doctor warns and the brain uses the first runnable instead.

# ~/.config/captain/env
CAPTAIN_DIRECTOR=claude
CAPTAIN_FALLBACK_LEG=cursor

Restart the brain after editing. Use CAPTAIN_FAST_ROUTE=1 (or --no-manager) for pure heuristic with no director.

Permissions and sandboxes

Workers run with approvals disabled by default so headless runs do not wait forever. If that is not acceptable:

Set CAPTAIN_CLAUDE_PERMISSIONS (and equivalents) to keep approvals on
Set CAPTAIN_CODEX_CLI_SANDBOX to a sandbox mode rather than bypass
Run in a container or VM with only the repository mounted

Read the security policy before pointing Captain Code at anything you do not own.

Legs

Legs live as data overlays, not hardcoded binaries.

captain legs add <id> <provider/model>
captain doctor

See Adding a leg and the CLI cheat sheet.

Decision leg: `jev`

A decision leg answers typed questions, a choice among options, a score against a rubric, a yes/no with its probability, and never generates text or runs a tool. jev is TypeSafe System One on the system-one transport. It is a registered leg (doctor, pricing and captain legs know it, which marks it decision) and nowhere a task is dispatched: no worker rung, no model in the picker, no /jev forcing command, no workflow stage, no reroute target. Set TYPESAFE_API_KEY, or drop a jev.env file holding the console API_KEY=… line next to your captain env. A brain started before the key was set needs a restart to see it.

Variable	Default	Role
`TYPESAFE_API_KEY`	unset	Enables the leg. Without it nothing changes except triage speed.
`CAPTAIN_TRIAGE_JEV`	on with the key (`0` disables)	Triage tier 1 asks jev for class and domain first. Its answer counts when the calibrated confidence clears the bar; otherwise the free-leg classifier decides as before.
`CAPTAIN_TRIAGE_JEV_CONF`	`CAPTAIN_TRIAGE_CONF` (0.6)	Confidence a jev classification must reach to be taken.
`CAPTAIN_TRIAGE_JEV_BELOW`	`0.9`	Heuristic confidence below which jev is consulted on its own. `0` closes that band, `1` asks it on every triaged task.
`CAPTAIN_JEV_SHADOW`	on with the key (`0` disables)	Asks the shadow questions (turn shape, which leg, which worker a `/btw` note concerns) beside the real decision and records them. Nothing is acted on.
`CAPTAIN_JEV_MODEL`	`jev-latest`	Pin a version to freeze a tuned confidence bar.

captain jev                                   # probe: models, latency, tokens, cost estimate
captain jev classify "fix the typo in README" # triage questions, probabilities, gate verdict
captain jev shadow --point leg                # agreement per decision point, by confidence
captain why                                   # one turn: jev beside what captain did

Each call is charged to the turn at the registry price ($0.042 per million input tokens, output free). See the models page for how the decision leg is used today.

State directories

~/.captaincode/state.json: durable ledger (charges, budgets, lifecycle, outcomes)
~/.captaincode/history/: daily JSONL transcripts
~/.captaincode/runs/: worker logs; overlays and priors alongside
Per-folder TUI state under ~/.captaincode/state/<folder>

captain init also narrows what a worker may read (notably denying the read tool on .env files). That is a guard rail, not a security boundary: a shell command can still read any file the user can.