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

> Route the Claude Desktop app through Valar on macOS

The Claude Desktop app hosts the Code and Cowork tabs. ValarCode routes them through Valar with `valar claude-desktop`, which writes a Valar profile the app reads at startup. Both tabs keep speaking the Anthropic Messages API and you keep picking Claude models; the gateway maps whatever they send to the target your cohort resolves to. See [Set up ValarCode](/valarcode/setup) for the shared setup and the client-id model.

<Note>
  `valar claude-desktop` is separate from `valar claude`, which routes the [Claude Code](/valarcode/claude-code) CLI. The app keeps its routing in its own config store, so the two are enabled, disabled and reported apart. This is a macOS-only integration.
</Note>

## Prerequisites

* macOS with the Claude desktop app installed (the app that hosts the Code and Cowork tabs).
* 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-desktop on --api-key <your-coding-key>
```

The app reads its config only at startup. If it is running, valar offers to quit and relaunch it for you — pass `--force` to skip that prompt and restart it right away, at the cost of interrupting any session open in the app. Decline, and the change applies on the app's next launch. Check the state any time:

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

The status output reports whether the app is installed and whether it is currently routed through Valar.

Routing covers the Code and Cowork tabs. The Chat tab is opt-in, per run:

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

The choice is not remembered — pass `--with-chat` on every `on` that should keep the tab, including the re-enable an upgrade performs. Omitting it removes the Chat tab, which Code and Cowork never do.

<Note>
  The Chat tab starts a separate history: chats made through Valar stay here, and your claude.ai chats stay on your account. Its traffic also runs through the gateway and bills as this harness.
</Note>

## What gets written

The CLI writes a profile named **Valar** into the desktop app's third-party config store under `~/Library/Application Support/Claude-3p/configLibrary/`:

* `_meta.json` selects the Valar profile and preserves any profiles you already had.
* `<uuid>.json` holds the profile body:

```json theme={"system"}
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.valarhq.ai",
  "inferenceCredentialKind": "static",
  "inferenceGatewayApiKey": "vlrcode_…",
  "inferenceModels": [ … ],
  "modelDiscoveryEnabled": false,
  "inferenceCustomHeaders": {
    "X-Valar-Harness": "claude",
    "X-Valar-Client-Id": "jdoe",
    "X-Valar-Cli-Version": "1.4.2"
  }
}
```

In detail, enabling:

* Points the app's inference at Valar (`inferenceProvider: "gateway"`, base URL written as the host without a `/v1` suffix). Both tabs route over the Anthropic Messages surface.
* Uses the bare coding key as a static bearer (`inferenceCredentialKind: "static"`).
* Pins the model picker with `inferenceModels` and sets `modelDiscoveryEnabled: false`, so the picker shows the Valar models rather than filling from the raw catalog. The first entry is the chat default (for example Sonnet), since Cowork is a chat surface.
* Carries attribution in `inferenceCustomHeaders`. This is how Cowork's isolated sessions stay attributed: they never see the `ANTHROPIC_CUSTOM_HEADERS` env that the Code tab and Claude Code use, so the client id and harness ride on the profile instead.

Before the first change, the app's existing config is snapshotted to `~/.valar/claude/desktop-backup.json`.

<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 instance

To run a Valar-routed Claude Desktop beside your main app, without touching its config:

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

This launches a separate Claude Desktop instance pinned to its own data dir (`~/.valar/claude/desktop-session`) and routed through Valar. Your main app, its login and its config stay untouched, and `valar claude-desktop status` stays `off`.

One single-session instance runs at a time. If a previous one is still open, pass `--force` to replace it:

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

## Turn off routing

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

This restores the pre-enable snapshot byte-for-byte. If the CLI created the whole `Claude-3p` config tree, it removes it. As with `on`, valar offers to restart the app for you, and `--force` skips the prompt.

## Next steps

<CardGroup cols={2}>
  <Card title="Claude Code" icon="code" href="/valarcode/claude-code">
    The Claude Code CLI, routed separately, and how it edits `~/.claude/settings.json`.
  </Card>

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