> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-de47a659.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Route Claude Code CLI requests through Venice with claude-code-router for pay-per-token access to Claude Opus, Sonnet, and Fable coding models.

[Claude Code](https://code.claude.com/docs) is Anthropic's CLI tool for agentic coding. This guide shows you how to run it through Venice for anonymized, pay-per-token access to Claude models.

<CardGroup cols={3}>
  <Card title="Pay Per Token" icon="coins">
    No subscription. Pay only for what you use
  </Card>

  <Card title="Claude Models" icon="cpu">
    Access current Opus, Sonnet, and Fable models through Venice
  </Card>

  <Card title="Prompt Caching" icon="bolt">
    Venice caching works alongside Claude Code
  </Card>
</CardGroup>

## Why You Need a Router

Claude Code connects directly to Anthropic's API by default. To use it with Venice, you need [claude-code-router](https://github.com/musistudio/claude-code-router), an open-source local proxy that:

<Steps>
  <Step title="Intercepts" icon="hand-stop">
    Catches Claude Code's outgoing requests before they reach Anthropic
  </Step>

  <Step title="Transforms" icon="refresh">
    Converts Anthropic Messages requests into Venice's OpenAI-compatible chat format
  </Step>

  <Step title="Redirects" icon="route">
    Forwards requests to `api.venice.ai/api/v1/chat/completions`
  </Step>
</Steps>

***

## Prerequisites

<CardGroup cols={3}>
  <Card title="Venice Account" icon="user" href="https://venice.ai/settings/api?utm_source=venice-api-documentation">
    With Venice credits
  </Card>

  <Card title="Node.js" icon="brand-nodejs" href="https://nodejs.org/">
    v22 or higher
  </Card>

  <Card title="Claude Code" icon="terminal" href="https://code.claude.com/docs">
    Installed via npm
  </Card>
</CardGroup>

***

## Setup

<Steps>
  <Step title="Install or update Claude Code">
    Install the latest Claude Code CLI:

    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code@latest
    claude --version
    ```
  </Step>

  <Step title="Install Claude Code Router">
    ```bash theme={null}
    npm install -g @musistudio/claude-code-router@latest
    npm list -g @musistudio/claude-code-router --depth=0
    ```
  </Step>

  <Step title="Get Your API Key">
    Generate a key from [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation). You will add it to CCR in the next step.
  </Step>

  <Step title="Add Venice as a provider">
    Start CCR's management UI:

    ```bash theme={null}
    ccr ui
    ```

    On the **Providers** page, choose **Add provider** and then **Other / custom API endpoint**. Enter:

    * **Name:** `Venice`
    * **API endpoint:** `https://api.venice.ai/api/v1`
    * **API key:** your Venice API key

    CCR should detect **OpenAI Chat** automatically. If it does not, open **Advanced settings**, turn off automatic protocol detection, and select **OpenAI Chat**.

    Use **Search models** or **Custom models** to add the Claude models you want, then run **Check Connection** and save the provider. The connection check sends a real request with a one-token output limit.
  </Step>

  <Step title="Create a Claude Code profile">
    In **Agent Config**, choose **Add profile** and then **Claude Code**:

    * Name the profile `Claude Code - Venice`.
    * Keep **Effect scope** set to **Only opened from CCR** while testing.
    * Choose **CLI only** or **CLI & APP**.
    * Set **Model** to a Venice model such as `Venice/claude-opus-4-8`.
    * To keep every Claude Code tier on Venice, set the optional Fable, Opus, Sonnet, and Haiku model fields to Venice models too.

    Save the profile.
  </Step>

  <Step title="Launch and verify">
    Launch the profile by name:

    ```bash theme={null}
    ccr "Claude Code - Venice"
    ```

    In Claude Code:

    1. Run `/context` and confirm the context window matches the selected model. For `claude-opus-4-8`, it should show `1M`.
    2. Run `/model` if you want to switch to another Venice model; 1M variants are marked **1M context**.
    3. Send a test message, then check **Request logs** in CCR to confirm that it used Venice.
  </Step>
</Steps>

***

## Supported Models

| Model                | Venice ID              | Context |
| -------------------- | ---------------------- | ------- |
| Claude Fable 5.1     | `claude-fable-5-1`     | 1M      |
| Claude Fable 5       | `claude-fable-5`       | 1M      |
| Claude Opus 5        | `claude-opus-5`        | 1M      |
| Claude Opus 5 Fast   | `claude-opus-5-fast`   | 1M      |
| Claude Opus 4.8      | `claude-opus-4-8`      | 1M      |
| Claude Opus 4.8 Fast | `claude-opus-4-8-fast` | 1M      |
| Claude Opus 4.7      | `claude-opus-4-7`      | 1M      |
| Claude Opus 4.6      | `claude-opus-4-6`      | 1M      |
| Claude Opus 4.5      | `claude-opus-4-5`      | 198K    |
| Claude Sonnet 5      | `claude-sonnet-5`      | 1M      |
| Claude Sonnet 4.6    | `claude-sonnet-4-6`    | 1M      |
| Claude Sonnet 4.5    | `claude-sonnet-4-5`    | 198K    |

The catalog changes over time. Use **Search models** in CCR or [`GET /models?type=text`](/api-reference/endpoint/models/list) for the current list and limits.

<Info>
  Claude Code is optimized for Claude models. While other models available through Venice (GPT, DeepSeek, Grok, etc.) may work, we cannot guarantee an equivalent experience since Claude Code relies on Claude-specific features like extended thinking. For other models, consider using Venice's [standard API](/api-reference/endpoint/chat/completions).
</Info>

***

## Updating an Existing Installation

Update CCR before troubleshooting an existing installation:

```bash theme={null}
npm install -g @musistudio/claude-code-router@latest
npm list -g @musistudio/claude-code-router --depth=0
ccr ui
```

Current CCR releases store live configuration in `~/.claude-code-router/config.sqlite`. An older `config.json` is imported when the database does not exist. After migration, make changes through `ccr ui` instead of continuing to edit `config.json`.

If a background process is still running after an update, restart it:

```bash theme={null}
ccr stop
ccr start
```

***

## Prompt Caching

Venice [prompt caching](/guides/features/prompt-caching) works with Claude Code's native cache markers. No additional cache transformer is required for the normal setup.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Context reaches 100% early or compaction fails">
    1. Update CCR with `npm install -g @musistudio/claude-code-router@latest`.
    2. Launch a new Claude Code session from the CCR profile.
    3. Run `/model` and select the Venice entry marked **1M context**.
    4. Run `/context` and confirm that the window is `1M`, not `200K`.

    Older CCR releases may not expose the correct context window or token usage to Claude Code.
  </Accordion>

  <Accordion title="CCR crashes during startup">
    Confirm Node.js 22 or newer and update CCR:

    ```bash theme={null}
    node --version
    npm list -g @musistudio/claude-code-router --depth=0
    ```

    Use `ccr serve` to run in the foreground and expose the original startup error. A `Cannot read properties of undefined (reading 'error')` stack from `server.logger.error` indicates an outdated CCR installation; update it before investigating further.
  </Accordion>

  <Accordion title="Claude Code reports ConnectionRefused">
    Start the gateway and verify its health:

    ```bash theme={null}
    ccr start
    curl http://127.0.0.1:3456/health
    ```

    A failed health check means the local CCR gateway is unavailable; the request has not reached Venice.
  </Accordion>

  <Accordion title="Configuration changes are ignored">
    Open `ccr ui` and make the change there. Current CCR releases store configuration in `config.sqlite`; `config.json` is only a migration source for older installations.
  </Accordion>
</AccordionGroup>

***

## Resources

<CardGroup cols={3}>
  <Card title="Venice API Docs" icon="book" href="/api-reference/api-spec">
    Full API reference
  </Card>

  <Card title="claude-code-router" icon="brand-github" href="https://github.com/musistudio/claude-code-router">
    Source code and issues
  </Card>

  <Card title="CCR Releases" icon="history" href="https://github.com/musistudio/claude-code-router/releases">
    Current versions and release notes
  </Card>
</CardGroup>