Configuration

OrbCode CLI stores its state and configuration under ~/.orbcode/. Two files live there:

config.json — state written by the app itself (login token, chosen model, approval defaults). Created on first save, mode 0600.
settings.json — user-managed configuration, Claude-Code style. Created automatically as an empty {} on first run so it’s easy to find. A project-level .orbcode/settings.json in the working directory layers on top of the user-level file.

Lifecycle hooks

Block, auto-approve, rewrite, or inject context at fixed points in the agent loop

Install & authentication

First-run setup, login, and troubleshooting

File layout

Path	Written by	Mode	Purpose
`~/.orbcode/config.json`	the app	`0600`	login token, model, approval defaults
`~/.orbcode/settings.json`	you (user)	`0644`	user-level config; merged in
`<project>/.orbcode/settings.json`	you (project)	`0644`	project-level config, layered on top
`<project>/.orb/AGENTS.md`	you or `/init`	`0644`	repo-level project memory, shared with the Orbital IDE extension
`<project>/.orb/links.json`	you or `/link`	`0644`	linked repositories (see Linked repositories)
`~/.orbcode/sessions/<id>.json`	the app	`0600`	saved sessions for `/resume` and `--resume`
`~/.orbcode/hook-trust.json`	the app	`0600`	your trust decisions for project hooks
`~/.orbcode/snapshots/…`	hooks	`0644`	optional: pre-compact transcript snapshots

Override the config directory with MATTERAI_CONFIG_DIR.

settings.json (full reference)

{
  "apiKey": "<token used instead of logging in>",
  "baseUrl": "https://my-gateway.example.com/v1",
  "model": "my-custom-model",
  "autoApproveEdits": false,
  "autoApproveSafeCommands": false,
  "customModels": [
    {
      "id": "my-custom-model",
      "name": "My Custom Model",
      "contextWindow": 128000,
      "maxOutputTokens": 32000,
      "inputPrice": 0.000001,
      "outputPrice": 0.000002
    }
  ],
  "env": { "MY_VAR": "value" },
  "hooks": { "PreToolUse": [] }
}

All keys are optional.

key	type	default	effect
`apiKey`	string	—	token used instead of logging in. Takes precedence over `MATTERAI_TOKEN` only if `MATTERAI_TOKEN` is unset.
`baseUrl`	string	MatterAI gateway	point the chat client at any OpenAI-compatible gateway. Honoured when the chosen model has no `provider` (or `provider: "matterai"`).
`model`	string	`axon-eido-3-code-mini`	default model id. Overridden by `--model`/`-m` on the CLI.
`autoApproveEdits`	boolean	`false`	session default for file-edit approvals (`y` vs. prompt). Dangerous commands still always prompt.
`autoApproveSafeCommands`	boolean	`false`	session default for safe command approvals. Dangerous commands are never auto-approved.
`customModels`	array	`[]`	extra models that appear in the `/model` picker alongside the built-in Axon models. See Custom models.
`env`	object	`{}`	applied to the process at startup (e.g. `{"NODE_ENV":"development"}`).
`hooks`	object	`{}`	lifecycle hooks. See the Hooks reference.

Precedence

For the same key, the order is:

Environment variables (always win, e.g. MATTERAI_TOKEN, MATTERAI_MODEL).
Project .orbcode/settings.json (in the working directory).
User ~/.orbcode/settings.json.
config.json (state the app wrote for itself).

For hooks, user and project files are merged — projects can add hooks without clobbering yours (see Where hooks live).

Environment variables

env var	effect
`MATTERAI_TOKEN`	auth token (overrides everything, including `apiKey` in settings)
`MATTERAI_API_KEY`	same as `apiKey` in `settings.json`
`MATTERAI_BASE_URL`	same as `baseUrl` in `settings.json`
`MATTERAI_MODEL`	model override (what `--model` sets internally)
`MATTERAI_CONFIG_DIR`	config directory (default `~/.orbcode`)
`MATTERAI_BACKEND_URL`	device-auth backend (default `https://api.matterai.so`)
`MATTERAI_APP_URL`	webapp for the authorize page (default `https://app.matterai.so`)
`MATTERAI_TRUST_PROJECT_HOOKS`	set to `1` to auto-trust project hooks in non-interactive (`-p`) mode; ignored in interactive sessions

For the device flow, MATTERAI_BACKEND_URL and MATTERAI_APP_URL are useful against a local stack.

Custom models

customModels entries appear in the /model picker alongside the built-in Axon models. Each entry needs an id, a display name, a contextWindow, and maxOutputTokens. Optional inputPrice / outputPrice (per token) drive the status-bar cost display.

{
  "customModels": [
    {
      "id": "my-custom-model",
      "name": "My Custom Model",
      "contextWindow": 128000,
      "maxOutputTokens": 32000,
      "inputPrice": 0.000001,
      "outputPrice": 0.000002
    }
  ]
}

Other providers (Anthropic, OpenAI-compatible)

The Axon models go through the MatterAI gateway. A customModels entry that sets a provider is instead served through the Vercel AI SDK, reusing the same agent loop, tools, and approvals — auth is the provider’s own key (env var or apiKey), not the MatterAI login.

{
  "model": "claude-opus-4-8",
  "customModels": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "provider": "anthropic",
      "contextWindow": 1000000,
      "maxOutputTokens": 64000,
      "inputPrice": 0.000005,
      "outputPrice": 0.000025,
      "effort": "high"
    },
    {
      "id": "some-model",
      "provider": "openai-compatible",
      "baseUrl": "https://api.other-host.com/v1"
    }
  ]
}

provider: "anthropic" → native /v1/messages (@ai-sdk/anthropic). Key from ANTHROPIC_API_KEY (or apiKey on the entry). Adaptive thinking and reasoning streaming are on by default; effort (low…max) tunes depth; prompt caching breakpoints are set on the system prompt and conversation prefix automatically. Thinking blocks are preserved across turns (stored with the session and replayed with their signatures), so interleaved thinking with tool use round-trips correctly. Set "reasoning": false to disable thinking.
provider: "openai-compatible" → any OpenAI-compatible endpoint; requires baseUrl. Key from apiKey on the entry.

Anything without a provider (or provider: "matterai") keeps using the MatterAI gateway untouched. baseUrl only applies to the gateway path; for a custom provider, set baseUrl on the entry itself.

MCP servers

OrbCode connects to external tools via the Model Context Protocol (MCP). Servers are configured in three scopes (user, project .mcp.json, local) and their tools appear alongside the native tools as mcp__<server>__<tool>. Manage them with the orbcode mcp subcommand or the /mcp slash command. The full reference — configuration scopes, server types (stdio/http/sse), the orbcode mcp add/remove/list CLI, OAuth and static-header auth, the interactive /mcp manager, and headless-mode behavior — is on the MCP servers page.

Skills & AGENTS.md memory

Skills — reusable instruction sets the model loads on demand. Place a SKILL.md under ~/.orbcode/skills/ (user) or .orbcode/skills/ (project); the catalog is injected into the system prompt and use_skill loads the full body when a task matches.
AGENTS.md memory — project- and user-level instructions (build commands, code style, conventions) injected into every system prompt. OrbCode’s equivalent of Claude Code’s CLAUDE.md, using the open AGENTS.md filename. The repo-level file lives at .orb/AGENTS.md — the same folder the Orbital IDE extension reads — so a single source of truth covers your terminal and your editor. Use /init to generate or refine a starter file.

The full reference — creating skills, the SKILL.md format, how skills are used, AGENTS.md discovery order, and @include directives — is on the Skills & memory page.

Linked repositories

The repo-level .orb/ folder is shared with the Orbital IDE extension. It holds the two project-level files OrbCode reads ahead of every session:

.orb/AGENTS.md — the project’s cold-start memory (see Skills & memory). Use /init to generate or refine it.
.orb/links.json — linked repositories: other repos whose AGENTS.md should be considered when working in this one. Use the /link slash command (or the IDE’s /link) to add or remove entries.

links.json schema:

{
  "links": [
    { "path": "/Users/me/projects/shared-lib" },
    { "path": "~/projects/design-system" },
    { "path": "../api-server" }
  ]
}

Resolution and validation of each path happens at read time, so links written by the CLI or the IDE stay portable. At session start, OrbCode walks the links, reads each linked repo’s AGENTS.md (from .orb/, .orbital/, or .orbcode/), and pulls them in ahead of time into the agent’s environment details — so a change here is checked for impact on, or propagated to, the linked repos.

Sessions

Sessions are stored in ~/.orbcode/sessions/<id>.json and power /resume and --resume <id>. Each session records the conversation, tool results, task title, and cost. The backend-generated task title is fetched once per task and shows in the status bar, the session file, and the terminal window title (<title> (orbcode)).

Hooks (summary)

settings.json can also declare hooks, a per-event list of shell commands that run at fixed points in the agent loop. They use the same contract as Claude Code’s hooks (stdin JSON, exit-code protocol, JSON output schema). The full reference — every event, the JSON output schema, the exit-code protocol, a copy-paste cookbook, debugging, and security — is on the Hooks page.

Project-level hooks (.orbcode/settings.json inside a repo) are disabled until you approve them in a one-time trust prompt, since they run shell commands from a repo. See Security on the Hooks page.

Troubleshooting

Problem	Fix
`config.json` keeps reverting	That’s expected — it’s app state. Edit `settings.json` (or env vars) instead.
`customModels` entry doesn’t show in `/model`	Check that `id`, `name`, `contextWindow`, `maxOutputTokens` are all set; restart the session.
`baseUrl` is being ignored	The chosen model has a `provider` set; move `baseUrl` onto the model entry.
`MATTERAI_TOKEN` not picked up	Conflicting `apiKey` in `config.json` from a prior login — run `/logout` to clear it, or unset `MATTERAI_TOKEN` and re-login.
Hook from a project never runs	Approve it in the one-time trust prompt, or set `MATTERAI_TRUST_PROJECT_HOOKS=1` for non-interactive runs.

Getting Started

AI Coding Agents

Axon Models

AI Code Reviews

Integrations

OrbCode CLI Configuration

Configuration

Lifecycle hooks

Install & authentication

File layout

settings.json (full reference)

Precedence

Environment variables

Custom models

Other providers (Anthropic, OpenAI-compatible)

MCP servers

Skills & AGENTS.md memory

Linked repositories

Sessions

Hooks (summary)

Troubleshooting

​Configuration

Lifecycle hooks

Install & authentication

​File layout

​settings.json (full reference)

​Precedence

​Environment variables

​Custom models

​Other providers (Anthropic, OpenAI-compatible)

​MCP servers

​Skills & AGENTS.md memory

​Linked repositories

​Sessions

​Hooks (summary)

​Troubleshooting

Configuration

File layout

settings.json (full reference)

Precedence

Environment variables

Custom models

Other providers (Anthropic, OpenAI-compatible)

MCP servers

Skills & AGENTS.md memory

Linked repositories

Sessions

Hooks (summary)

Troubleshooting