# Claude Code

Claude Code can talk to The Grid directly through The Grid's beta Anthropic Messages endpoint. No local proxy, no LiteLLM bridge, no format translation. Set two environment variables, map Claude Code's family aliases (Sonnet, Haiku, Opus) to Grid instruments, and run `claude` normally.

## Prerequisites

* Claude Code installed (`npm install -g @anthropic-ai/claude-code` or the native installer).
* A Grid account at [app.thegrid.ai](https://app.thegrid.ai).
* Credits in your account. The Grid is prepaid.
* A Grid consumption API key from **Settings → API Keys → Create Consumption Key**.

{% hint style="info" %}
The Anthropic Messages endpoint on The Grid is in beta. The main flow works; the most visible gap is that `count_tokens` is not yet exposed, so Claude Code's pre-flight size checks, `/cost`, `/context`, and auto-compaction can be less accurate on long sessions.
{% endhint %}

## Setup

### 1. Create `~/.claude/settings.json`

Pick instrument IDs from the [current instruments list](/docs/instrument-specifications/current-instruments.md). A reasonable default mapping is Sonnet → Text Prime, Haiku → Text Standard, Opus → Text Max.

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://messages-beta.api.thegrid.ai",
    "ANTHROPIC_API_KEY": "your-grid-consumption-api-key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "text-prime",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "text-standard",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "text-max",
    "CLAUDE_CODE_SUBAGENT_MODEL": "text-standard"
  }
}
```

`settings.json` persists across terminal sessions and is shared with the VS Code extension. Set `ANTHROPIC_BASE_URL` to the host root, not the full `/v1/messages` path.

If you prefer shell exports over `settings.json`, the same variables work in `~/.zshrc` or `~/.bashrc`.

### 2. (Optional) Pin specific Anthropic versions with modelOverrides

If your team needs deterministic mapping at the version level instead of family aliases, use `modelOverrides`:

```json
{
  "modelOverrides": {
    "claude-sonnet-4-6": "text-prime",
    "claude-opus-4-6": "text-max",
    "claude-haiku-4-5": "text-standard"
  }
}
```

Keys must be full Anthropic model IDs. Short aliases like `sonnet` are silently ignored.

### 3. Start Claude Code

```bash
claude
```

## Verification

Run a simple prompt: "Summarize this repository in two sentences." A normal response confirms Claude Code is connected. `/status` inspects current settings.

## Troubleshooting

{% hint style="warning" %}
**403 from `/v1/messages`.** First, verify the key works directly:

```bash
curl https://messages-beta.api.thegrid.ai/v1/messages \
  -H "x-api-key: $YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"text-prime","max_tokens":128,"messages":[{"role":"user","content":"hello"}]}'
```

If that succeeds but Claude Code still 403s on an HTML page, restart Claude Code after editing `settings.json`. The beta endpoint can also surface 403s when Claude Code tries unsupported secondary endpoints during startup.
{% endhint %}

{% hint style="warning" %}
**Model mapping not working.** Check the instrument names against the [current instruments list](/docs/instrument-specifications/current-instruments.md), confirm `settings.json` is valid JSON (a trailing comma breaks it), and restart Claude Code after any change.
{% endhint %}

{% hint style="info" %}
**`/model` picker doesn't show Grid instruments.** Expected. Claude Code's picker uses Anthropic-facing names. Tier mapping happens through the env vars.
{% endhint %}

{% hint style="info" %}
**VS Code extension keeps prompting to log into Anthropic.** Set `claudeCode.disableLoginPrompt` to `true` in your VS Code settings. This is Anthropic's documented approach for third-party providers.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/claude-code.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.