> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/integrations-and-best-practices/integrations/claude-code.md).

# Claude Code Integration with The Grid | Anthropic API Setup

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. Point Claude Code at the base URL, supply your key through a small helper script, 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 %}

{% hint style="info" %}
The Code instruments (`code-standard`, `code-prime`, `code-max`) are in preview. They work today and are the right default for Claude Code, but their qualifying specs can change. See the [current instruments list](/docs/instrument-specifications/current-instruments.md) for current status.
{% 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 → Code Prime, Haiku → Code Standard, Opus → Code Max.

```json
{
  "apiKeyHelper": "~/.claude/thegrid_key.sh",
  "env": {
    "ANTHROPIC_BASE_URL": "https://messages-beta.api.thegrid.ai",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "code-prime",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "code-standard",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "code-max",
    "CLAUDE_CODE_SUBAGENT_MODEL": "code-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. `apiKeyHelper` points at the script you create in the next step, so your key never sits inline in `settings.json`.

### 2. Create the API key helper script

Create `~/.claude/thegrid_key.sh` and have it print your Grid consumption API key:

```bash
echo "YOUR_GRID_API_KEY"
```

### 3. Make the helper script executable

```bash
chmod +x ~/.claude/thegrid_key.sh
```

Claude Code runs this script and uses its stdout as the API key. If you prefer plain shell exports instead of `apiKeyHelper`, you can set `ANTHROPIC_API_KEY` along with the same variables in `~/.zshrc` or `~/.bashrc`.

### 4. (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": "code-prime",
    "claude-opus-4-6": "code-max",
    "claude-haiku-4-5": "code-standard"
  }
}
```

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

### 5. 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":"code-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="warning" %}
**Key helper not picked up.** Confirm `~/.claude/thegrid_key.sh` is executable (`chmod +x`), prints only the key (no extra output), and that `apiKeyHelper` sits at the top level of `settings.json`, not inside `env`. Restart Claude Code after changes.
{% 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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