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

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:

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-4-5",
    "compaction": "anthropic/claude-haiku-4-5",
    "title": "anthropic/claude-haiku-4-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.

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.

The default variables per provider:

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

Or sign in with an OAuth subscription instead of holding a raw key — arcturn auth login <provider> — see Getting started. Credentials land in ~/.arcturn/auth/.

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-opus-4-5
anthropic/claude-sonnet-4-5
anthropic/claude-haiku-4-5
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-4-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. This is registered from code, via openaiCompatible({ model, baseUrl, apiKeyEnv }) in @arcturn/ai, rather than a config file key — see Embedding with the SDK for how to register a spec and hand it to createAgent. Once registered it behaves like any other catalog entry: selectable by id, 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, 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#

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

Compaction#

Arcturn automatically compacts the conversation before it would overflow the model's context window — by default it keeps roughly the most recent 20,000 tokens verbatim and folds everything older into a structured markdown summary, reserving 16,384 tokens of headroom. All of it is tunable; see Sessions for the knobs and how a compaction is recorded in the session tree.

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.