# Use Xantly with Claude Code

> **Status:** Live. The Anthropic-compatible `/v1/messages` endpoint is shipped and ready. Follow the instructions below to connect Claude Code to Xantly.

Anthropic designed Claude Code to work with any LLM gateway that speaks the Messages API. Their [official LLM-gateway docs](https://code.claude.com/docs/en/llm-gateway) walk through the setup for LiteLLM; the same pattern works for Xantly with two env vars.

## Prerequisites

- Claude Code installed: `npm install -g @anthropic-ai/claude-code` (or `pip install claude-code`)
- A Xantly API key, [create one](/dashboard/api-keys)

## Setup

Two env vars:

```bash
export ANTHROPIC_BASE_URL=https://api.xantly.com
export ANTHROPIC_AUTH_TOKEN=xantly_sk_...
```

That's it. Claude Code now routes every request, chat, edit, sub-agent spawn, hook trigger, MCP tool-use, through Xantly's `/v1/messages` endpoint. All routing, caching, memory, waterfall fallback applies automatically.

Drop them in your `~/.zshrc` or `~/.bashrc` to make them persistent.

## Model selection

Claude Code sends model names in the Anthropic shape (e.g., `claude-sonnet-4-5`). Xantly honors them exactly when you use pinned IDs, or you can override via Claude Code's built-in model selector:

```bash
claude --model xantly/auto-quality  # override, BaRP picks best T1 Claude
```

Or set a default in `~/.claude/settings.json`:

```json
{
  "default_model": "xantly/auto-quality"
}
```

## What works

Everything. Because Xantly's `/v1/messages` is a byte-accurate Messages adapter over the existing pipeline, Claude Code gets:

- Chat ✅
- Edit with diff application ✅
- Sub-agent spawning (`Task` tool) ✅
- Hooks (pre/post tool, session start) ✅
- Skills ✅
- MCP tool-use ✅
- Streaming with all event types (`message_start`, `content_block_delta`, etc.) ✅
- Prompt caching (opt in via `anthropic-beta: prompt-caching-2024-07-31` header) ✅
- Tool-use (input_json_delta streaming) ✅

## What you get

- **Semantic cache on repeated prompts.** Claude Code re-asks similar questions ("how does auth work?") across sessions, L1/L2 cache turns these into near-free hits.
- **Waterfall fallback to GPT/Groq.** If Anthropic overloads, Xantly silently falls back to an OpenAI model and translates the response back into Messages shape. Claude Code never sees the swap.
- **Memory across sessions.** Xantly's L3 graph memory remembers prior project context. Claude Code can recall it via `X-Xantly-Memory-Mode: recall` header.
- **Cost per turn.** Every Claude Code call logs in your Xantly dashboard with model, cache status, cost.
- **Session stitching.** `X-Claude-Code-Session-Id` is preserved through Xantly, so audit logs + memory scoping align with Claude Code's own session boundaries.

## Advanced: Anthropic betas

Claude Code automatically sends `anthropic-beta` headers for features like prompt caching, PDFs, and the computer-use tool. Xantly forwards them to the underlying provider and reflects them back in the response. No config needed on your side, it just works.

If you want to pin a specific beta set:

```bash
export ANTHROPIC_BETAS="prompt-caching-2024-07-31,pdfs-2024-09-25"
```

Xantly respects this and passes it through.

## Gotchas

**`ANTHROPIC_BASE_URL` has no `/v1` suffix.** Anthropic's SDK appends it. Use `https://api.xantly.com` (bare), **not** `https://api.xantly.com/v1`.

**macOS GUI apps don't inherit shell env.** If you launch Claude Code from Spotlight / a launcher app, shell-exported env vars won't reach it. Use `~/Library/LaunchAgents/` plist or set variables in `~/.claude/settings.json` → `env` block.

**Streaming diff strictness.** Claude Code parses SSE event names strictly. Xantly's `/v1/messages` preserves `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop` exactly, if you see a parse error, it's a bug on our side; report it.

## Verify

```bash
claude "summarize the largest file in this repo"
```

You should see Claude Code stream output character-by-character, identical to running it against Anthropic directly. Check your Xantly dashboard, the call will appear with cost, model, and cache status.

## Next steps

- [Copilot CLI](/docs/use-with-copilot-cli), same gateway, different CLI.
- [OpenCode](/docs/use-with-opencode), CLI agent with OpenAI-compatible shape.
- [Aider](/docs/use-with-aider), terminal-native pair programmer.
- [Memory & Context](/docs/memory-and-context), how Xantly's L0-L3 cascade extends Claude Code with persistent knowledge.