Configuration

File locations and precedence#

Configuration is layered JSON, merged with later layers winning:

built-in defaults
  → ~/.arcturn/config.json          (user scope)
  → <cwd>/.arcturn/config.json      (project scope, skipped if cwd is the user root)
  → ARCTURN_MODEL environment variable

Most keys simply overwrite (project beats user, env beats both). Three are different:

• permissions accumulates across layers instead of replacing — a user rule and a project rule can both apply. See Permissions for the rule schema and how the four permission modes interact with it.
• hooks also accumulates — a user-level hook and a project-level hook both fire for the same lifecycle event. See Lifecycle hooks.
• permissionMode is clamped: a project layer may only narrow it, never widen it. From narrowest to widest the modes are plan → default → acceptEdits → yolo, so a repository asking for plan is honored while one asking for yolo when you are at default is ignored with a warning. Otherwise a checked-in config would switch off your permission prompts for anyone who cloned the repository. To run a project at a wider mode deliberately, set it in your own ~/.arcturn/config.json or pass --permission-mode, which wins over both layers in either direction.

A malformed or unreadable config file is a warning, never a crash: Arcturn falls back to the layers it could read. An unrecognized top-level key is likewise a warning (unknown config key "..." (ignored)), not a hard failure — so a typo doesn't stop the CLI from starting, and upgrading Arcturn never breaks on an older config written for a newer key.

Override where the user directory itself lives with ARCTURN_HOME (default ~/.arcturn).

Config key reference#

Every key .arcturn/config.json accepts, in both user and project files:

In "screen" mode the transcript scrolls inside the app: mouse wheel, PgUp/PgDn, and — while the view is scrolled up — Home and End; sending a prompt returns to the live tail. A pure vertical scroll is painted by moving the terminal's own rows (a DECSTBM scroll region) rather than repainting the screen, which is what keeps a flick smooth on a slow connection. If your terminal misrenders it, ARCTURN_NO_SCROLL_REGION=1 turns that shortcut off and every frame takes the plain row diff.

Any key not in this table is rejected with a warning and ignored — there is no silent extension surface beyond systemPromptAppend.

verify#

{ "verify": "pnpm test" }

{
  "verify": {
    "command": "pnpm typecheck",
    "globs": ["*.ts", "*.tsx"],
    "timeoutMs": 60000,
    "runOn": "edit"
  }
}

• command — shell command, run in the runtime's working directory through the platform's shell: /bin/sh -c on macOS/Linux, %ComSpec% /d /s /c (cmd.exe by default) on Windows. See Platform support for what that means for a command written with POSIX syntax. command is not portable across the two shells — neither is a lifecycle hook's command, for the same reason. .arcturn/config.json is plain JSON with no per-platform branching, so a config checked in for a team that develops on both macOS/Linux and Windows can't put a shell one-liner straight in command; point it instead at something that is portable — an npm/pnpm script ("pnpm verify", with the platform-specific part inside package.json) or a Node script invoked directly ("node scripts/verify.mjs").
• globs — restricts which edited paths trigger the command. This is a simple suffix/segment check, not full glob syntax: a leading * ("*.ts") matches a path ending with the rest of the pattern; anything else matches the whole path, a trailing path suffix, or an exact path segment. There is no ** and no mid-pattern *. Omitted or empty matches every edited path.
• timeoutMs — defaults to 60000 (60s).
• runOn — "edit" (default: runs after every successful write/edit) or "manual".

A passing verify appends nothing to the tool result (quiet on green); a failing one appends the failure, roughly the trailing 40 lines, so the model sees its own breakage on the very next turn. It never turns a successful write/edit into a failure.

route#

Route a cheaper model to work that doesn't need the flagship:

{
  "route": {
    "subagent": "anthropic/claude-haiku-5-5",
    "compaction": "anthropic/claude-haiku-5-5",
    "title": "anthropic/claude-haiku-5-5"
  }
}

Each of main, subagent, compaction, title is an independent model id. An absent key falls back to main's route, and an absent main falls back to whatever model the session is actually running (typically what --model resolved to). A stale or typo'd id never throws or blocks startup — it falls back to the main model and surfaces a warning.

You don't have to edit this block by hand: /model route --auto picks a cheaper same-provider model and writes route.subagent and route.compaction into your user config (merging into the existing block), and /model route <kind> <id> / /model route clear [kind] manage single keys. See Model routing for the full precedence.

Provider API keys#

Arcturn resolves an API key for a model in this order:

1. A per-provider key passed explicitly to the client.
2. A shared explicit key passed to the client.
3. The model spec's own apiKeyEnv, if it names one.
4. The provider's default environment variable.
5. Provider-specific fallback variables.

A model declared in a providers config block skips that ladder entirely. Such a spec is registered key-exclusive: its apiKeyEnv is the only variable consulted, and an unset one means no key rather than a fall-through to OPENAI_API_KEY / ANTHROPIC_API_KEY or to an explicit client-wide key. A file that names an endpoint and a credential gets exactly the credential it named.

The default variables per provider:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...

An API key is the only credential Arcturn takes for a model provider. There is no subscription sign-in — see Model providers.

The model catalog#

Arcturn ships a curated catalog of ModelSpecs — context window, max output tokens, cost per million tokens, and capability flags (tools, vision, thinking, caching) — for every model it supports out of the box, keyed as <provider>/<model>:

anthropic/claude-fable-5-1
anthropic/claude-opus-5-5
anthropic/claude-sonnet-5-5
anthropic/claude-haiku-5-5
anthropic/claude-opus-4-8
anthropic/claude-sonnet-4-6
openai/gpt-5.1
openai/gpt-5.1-codex
google/gemini-3-pro-preview
google/gemini-2.5-flash

Pick one on the command line (arcturn --model anthropic/claude-sonnet-5-5), in-session (/model openai/gpt-5.1), or in code via requireModel(id) from @arcturn/ai. Switching models mid-session is recorded as a state entry in the session tree, so resuming later restores the model you were using. arcturn --list-models prints the full catalog and exits; arcturn --list-providers prints every provider and preset endpoint.

OpenAI-compatible endpoints#

Any endpoint that speaks the OpenAI chat-completions wire format — a local model server, a self-hosted gateway, a third-party router — works as an openai-compatible provider, and an Anthropic-Messages endpoint works as anthropic-compatible.

Declare one in the providers config key:

{
  "providers": {
    "mycorp": {
      "baseUrl": "https://llm.corp.internal/v1",
      "apiKeyEnv": "MYCORP_LLM_KEY",
      "protocol": "openai",
      "label": "MyCorp Gateway",
      "models": [{ "model": "llama-70b", "contextWindow": 128000 }]
    }
  }
}

Ids are namespaced <name>/<model>, so arcturn --model mycorp/llama-70b works and the entry shows up in --list-models, --list-providers, /model and arcturn doctor. Omitting models is fine: ids then pass through to the wire verbatim.

apiKeyEnv is required for a remote endpoint (a loopback one may omit it and is then contacted with no credential), baseUrl must be https: (or loopback http:) and free of control characters, and a project file may not name a variable holding a credential you keep for another service — including any built-in preset's, compared case-insensitively. A project-declared endpoint is also parsed-but-inert until you approve it once. Providers has the full rule list, and Permissions has the consent model.

Registering from code still works and still wins: openaiCompatible({ model, baseUrl, apiKeyEnv }) in @arcturn/ai — see Embedding with the SDK — runs after the config block, so an extension can override a config entry. Once registered, either way behaves like any other catalog entry, with the same cost/context-window bookkeeping.

Command-line flags#

Every flag arcturn accepts. Long flags may be written --flag value or --flag=value; boolean flags accept a --no- prefix.

Positional commands (arcturn <command> ...) take the place of a prompt: auth, completions, replay, audit, insights, blame, bisect, serve, acp, attach. See arcturn --help for each, and Sessions, Replay & bisect, Provenance, and Audit trail for the ones owned by other pages.

Anything not recognized as a flag or a positional command becomes prompt text — including everything after a literal --.

Other environment variables#

MCP config#

A server's entry also takes "sampling": true (default off) to let that server ask the session's model for a completion, billed to the session; see MCP: servers that ask back.

MCP servers are declared in a JSON file shaped { "servers": { ... } }, read from ~/.arcturn/mcp.json merged with <cwd>/.arcturn/mcp.json — see MCP for the full schema and ${ENV_VAR} expansion rules.

Extended thinking#

thinking (config key) or --thinking <level> is not currently a CLI flag — set it via .arcturn/config.json's thinking key (off, low, medium, high, xhigh, max) to control how much extended reasoning a thinking-capable model does before it answers or calls a tool. This maps to the ThinkingLevel type shared by every provider adapter, so the same setting works regardless of which model you're running.

Each model declares the levels it accepts, and a level it lacks is clamped down to the nearest one it has: Claude Opus 4.6 and Sonnet 4.6 have no xhigh, so xhigh runs as high there; OpenAI models stop at high, and Gemini tops out at HIGH (a 32K budget).

What off means is per model, and three of them changed. Some Claude models think unless told not to, so off has to be sent as something:

Adaptive requests to Opus 4.7 and later ask for display: "summarized", because the API's default became omitted and the thinking pane would otherwise be blank. Opus 5.5 always carries an explicit effort — its API default is medium, not high.

Compaction#

Arcturn automatically compacts the conversation before it would overflow the model's context window, reserving 16,384 tokens of headroom. What it keeps depends on compaction.shape: on Claude with adaptive thinking (4.6 and later) one summary replaces the whole history, because the thinking on those models is bound to the history a summary replaces; elsewhere it keeps roughly the most recent 20,000 tokens verbatim beside the summary. All of it is tunable; see Sessions for the knobs and how a compaction is recorded in the session tree, and Context management for the reasoning.

Writing a permission rule or setting from code#

persistSetting(key, value, scope, paths) and persistPermissionRule(rule, paths) in @arcturn/cli's config module write one key or one rule back to the right file for its scope ("project" → <cwd>/.arcturn/config.json, otherwise ~/.arcturn/config.json) — this is what the TUI's "always allow" permission prompt and /config commands call under the hood. Session-scoped permission rules are intentionally never written to disk: they live only in the running process's permission engine.