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

# Use LithosAI with Claude Code

> Connect Claude Code to LithosAI through a LiteLLM Anthropic Messages compatibility proxy.

## Before you begin

Create a key on the [API Keys](https://console.lithosai.cloud/keys) page, confirm the model ID
on the [Models](https://console.lithosai.cloud/models) page, and export the key in the shell where you start Claude Code or its local proxy.

```bash theme={null}
export LITHOSAI_API_KEY="your-key"
```

Claude Code speaks the Anthropic Messages API, so its proxy needs a different configuration
from the one Codex uses. Run it on a second port to use both agents at once.

<Warning>
  This is a community compatibility path for non-Claude models, not a configuration supported
  by Anthropic. LiteLLM maps common Messages API behavior to Chat Completions, but native
  thinking blocks, prompt caching, token counting, streaming details, and some tool-use flows
  may behave differently.
</Warning>

<Steps>
  <Step title="Install LiteLLM">
    [LiteLLM](https://docs.litellm.ai) bridges the Anthropic Messages API to Chat
    Completions.

    ```bash theme={null}
    pip install 'litellm[proxy]'
    ```

    <Warning>
      Install a current release. LiteLLM 1.82.7 and 1.82.8 were briefly replaced on PyPI in
      March 2026 by a [credential stealer](https://docs.litellm.ai/blog/security-update-march-2026).
    </Warning>
  </Step>

  <Step title="Configure the proxy">
    Give each model the `hosted_vllm/` prefix. It translates `/v1/messages` requests into
    Chat Completions requests for LithosAI.

    ```yaml claude-code.litellm.yaml theme={null}
    model_list:
      - model_name: kimi-k3
        litellm_params:
          model: hosted_vllm/moonshotai/Kimi-K3
          api_base: https://api.lithosai.cloud/v1
          api_key: os.environ/LITHOSAI_API_KEY
      - model_name: kimi-k3-fast
        litellm_params:
          model: hosted_vllm/moonshotai/Kimi-K3-fast
          api_base: https://api.lithosai.cloud/v1
          api_key: os.environ/LITHOSAI_API_KEY

    litellm_settings:
      drop_params: true

    general_settings:
      master_key: sk-claude-proxy
    ```

    <Warning>
      Do not reuse the Codex configuration here. An `openai/` entry with
      `use_chat_completions_api` answers `/v1/messages` with `200 OK` and empty content, so
      Claude Code appears to hang rather than reporting an error.
    </Warning>
  </Step>

  <Step title="Start the proxy">
    ```bash theme={null}
    litellm --config claude-code.litellm.yaml --host 127.0.0.1 --port 4001
    ```

    Leave it running, and confirm it is up. The proxy holds your LithosAI key, so keep it
    bound to `127.0.0.1` and do not expose it to a network.

    ```bash theme={null}
    curl http://127.0.0.1:4001/health/liveliness
    ```
  </Step>

  <Step title="Point Claude Code at it">
    ```bash theme={null}
    export ANTHROPIC_BASE_URL="http://127.0.0.1:4001"
    export ANTHROPIC_AUTH_TOKEN="sk-claude-proxy"
    export ANTHROPIC_MODEL="kimi-k3"
    export ANTHROPIC_DEFAULT_HAIKU_MODEL="kimi-k3-fast"
    claude
    ```

    `ANTHROPIC_DEFAULT_HAIKU_MODEL` handles background work such as session titles. Without it,
    those requests fail against a model the proxy does not serve.

    <Warning>
      Setting `ANTHROPIC_AUTH_TOKEN` overrides a Claude.ai login for that shell. Export these
      in a dedicated shell or profile to keep an existing subscription usable elsewhere.
    </Warning>
  </Step>
</Steps>

Claude Code does not recognize LithosAI model names, so it assumes a 200k-token context
window and compacts early. Set the real window to avoid that.

```bash theme={null}
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=262144
```

<Note>
  Check the [Models](https://console.lithosai.cloud/models) console page for each model's
  context window.
</Note>

## Troubleshooting

| Symptom                                       | Cause                                                                                                                  |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Empty replies, or the session appears to hang | The model entry uses `openai/` with `use_chat_completions_api`. Claude Code needs `hosted_vllm/`.                      |
| Background requests fail while chat works     | `ANTHROPIC_DEFAULT_HAIKU_MODEL` is unset or names a model the proxy does not serve.                                    |
| `400` with `No connected db.`                 | `ANTHROPIC_AUTH_TOKEN` does not match the proxy's `master_key`. LiteLLM reports the lookup failure, not an auth error. |

Issues common to every agent are listed under [Common issues](/coding-agents#common-issues).