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

# Claude Code

> Route Claude Code through Valar, and what the CLI writes to ~/.claude/settings.json

ValarCode routes Claude Code through Valar by editing its `settings.json`. Claude Code keeps speaking the Anthropic Messages API and you keep choosing models with `/model`; the gateway maps whatever it sends to the target model your cohort resolves to. See [Set up ValarCode](/valarcode/setup) for the shared setup and the client-id model.

## Prerequisites

* Claude Code installed, with a `~/.claude` config directory.
* A Valar coding key (`vlrcode_…`) and the `valar` CLI ([install](/valarcode/setup#install-the-cli)).

## Enable routing

Run once per machine:

```bash theme={"system"}
valar claude on --api-key <your-coding-key>
```

<Note>
  This routes the Claude Code CLI only. The Claude Desktop app is a separate harness — see [Claude Desktop](/valarcode/claude-desktop).
</Note>

Claude Code hot-applies `settings.json` env additions, so `on` takes effect on the next request without a restart. Check the state any time:

```bash theme={"system"}
valar claude status
```

Routing through a gateway normally disables Remote Control (`/rc`), the Chrome extension and claude.ai MCP connectors, which only run on a first-party login. `--remote` keeps them working:

```bash theme={"system"}
valar claude on --api-key <your-coding-key> --remote
```

It serves inference over a local socket and adds a `claude()` wrapper to your shell config. valar asks before editing that file — pass `-y` to answer ahead of time, since a non-interactive run declines rather than edit it. Open a new terminal afterwards. `valar claude off` stops the proxy and removes the wrapper.

valar detects your shell; `--shell` overrides it. zsh, bash, fish and POSIX shells (sh, dash, ksh) are supported; tcsh, csh, nushell and PowerShell cannot be served.

## What gets written

`valar claude on` edits the `env` block of `~/.claude/settings.json`. It points the base URL and auth token at Valar, carries the client id in a custom header, and removes anything that would override the gateway's server-side routing:

```json theme={"system"}
{
  "availableModels": [ … ],
  "enforceAvailableModels": true,
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.valarhq.ai",
    "ANTHROPIC_AUTH_TOKEN": "vlrcode_…",
    "ANTHROPIC_CUSTOM_HEADERS": "X-Valar-Client-Id: jdoe\nX-Valar-Harness: claude\nX-Valar-Cli-Version: 1.4.2",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1",
    "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "0",
    "DISABLE_TELEMETRY": "1",
    "DO_NOT_TRACK": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

In detail, enabling:

* Sets `ANTHROPIC_BASE_URL` to Valar. Claude Code appends `/v1/messages`, so the host is written without a `/v1` suffix.
* Writes the bare coding key to `ANTHROPIC_AUTH_TOKEN` and removes any `ANTHROPIC_API_KEY` (which takes precedence as `x-api-key` and would conflict).
* Adds `X-Valar-Client-Id`, `X-Valar-Harness` and `X-Valar-Cli-Version` lines to `ANTHROPIC_CUSTOM_HEADERS`, preserving any other custom headers you set and replacing stale Valar lines on re-enable.
* **Strips client-side model-mapping pins** (`ANTHROPIC_MODEL`, the `ANTHROPIC_DEFAULT_OPUS_MODEL` / `SONNET` / `HAIKU` / `FABLE` sets, `CLAUDE_CODE_SUBAGENT_MODEL`, and the custom-model-option set) so the gateway's routing is authoritative. Your top-level `model` alias is left alone, as long as it names one of the models Valar routes.
* **Scopes the `/model` picker** to the models Valar routes, via the top-level `availableModels` and `enforceAvailableModels` keys. An id that is not on the list is rejected — including one passed as `--model` or `ANTHROPIC_MODEL`. Both are restored by `off`.
* **Merges a behavior/telemetry block** to cut Anthropic-bound nonessential traffic while you are routed.

<Note>
  If you are signed in to claude.ai, enabling writes the key as an `Authorization: Bearer` line in `ANTHROPIC_CUSTOM_HEADERS` instead of `ANTHROPIC_AUTH_TOKEN`, which would otherwise take precedence over your login. In that mode `DISABLE_TELEMETRY`, `DO_NOT_TRACK` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` are left unset too: any of the three disables feature-flag evaluation, and the last also turns off /feedback, Projects, DesignSync and live preview.
</Note>

The file is written user-only (`0600`), since it now holds a bearer token. Before the first change, the original `settings.json` is snapshotted to `~/.valar/claude/backup.json`, so `off` restores it byte-for-byte, including the model-mapping pins and the original permissions.

<Note>
  The client id defaults to your OS username, so the header reads `X-Valar-Client-Id: jdoe`. Use `--user-id RANDOM` for an opaque `vc_…` id instead. See [per-engineer attribution](/valarcode/setup#per-engineer-attribution).
</Note>

## Route a single session

To try Valar without changing anything on the machine, or to run one routed session beside a first-party setup, open a single Valar-routed session instead of enabling globally:

```bash theme={"system"}
valar claude on --single-session
```

This starts one `claude` whose routing rides its process environment, with the model picker scoped via a `--settings` argument. Nothing in your Claude setup is written: no `settings.json` edit, no backup, no stored defaults. (valar refreshes only its own model-list cache under `~/.valar`.) Every other session, and `valar claude status`, stays untouched. When the session ends, so does the routing.

Because there is nothing persistent to manage, `--single-session` cannot be combined with `--remote`.

## Turn off routing

```bash theme={"system"}
valar claude off
```

This restores the pre-enable snapshot (any `settings.json` edits made while routing was on are overwritten). Claude Code hot-applies additions but does **not** unset removals on a running session, so it keeps the old routing until you **restart Claude Code**. The CLI warns you when it detects a running session.

## Next steps

<CardGroup cols={2}>
  <Card title="Model routing" icon="route" href="/valarcode/routing">
    How cohorts and the split decide which model serves each request.
  </Card>

  <Card title="LiteLLM integration" icon="diagram-project" href="/valarcode/litellm">
    Route Claude Code through a LiteLLM proxy without losing attribution.
  </Card>
</CardGroup>