> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matterai.so/llms.txt
> Use this file to discover all available pages before exploring further.

# OrbCode CLI Configuration

> settings.json, environment variables, custom models, providers, and sessions

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

<CardGroup cols={2}>
  <Card title="Lifecycle hooks" icon="link" href="/orbcode-cli/hooks">
    Block, auto-approve, rewrite, or inject context at fixed points in the agent loop
  </Card>

  <Card title="Install & authentication" icon="key" href="/orbcode-cli/install">
    First-run setup, login, and troubleshooting
  </Card>
</CardGroup>

## 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](#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)

```json theme={null}
{
  "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](#custom-models).              |
| `env`                     | object  | `{}`                    | applied to the process at startup (e.g. `{"NODE_ENV":"development"}`).                                                                |
| `hooks`                   | object  | `{}`                    | lifecycle hooks. See the [Hooks reference](/orbcode-cli/hooks).                                                                       |

### Precedence

For the same key, the order is:

1. **Environment variables** (always win, e.g. `MATTERAI_TOKEN`, `MATTERAI_MODEL`).
2. **Project** `.orbcode/settings.json` (in the working directory).
3. **User** `~/.orbcode/settings.json`.
4. **`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](/orbcode-cli/hooks#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.

```json theme={null}
{
  "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](https://sdk.vercel.ai), reusing the same agent loop, tools, and approvals — auth is the provider's own key (env var or `apiKey`), not the MatterAI login.

```json theme={null}
{
  "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](/orbcode-cli/mcp).

## 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](/changelog/orbital-changelog) 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](/orbcode-cli/skills).

## 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](#skills--agentsmd-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:

```json theme={null}
{
  "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](/orbcode-cli/hooks).

<Note>
  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](/orbcode-cli/hooks#security).
</Note>

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