How to connect Reality Router to Claude Code

Two environment variables. Claude Code speaks the Anthropic Messages API and Reality Router serves that API directly — no adapter, no proxy in between — so every step of an agent run gets routed across your whole pool.

Claude Code is an agent, not a chat window. A single task is dozens of model calls: read a file, grep for a symbol, edit, run tests, read the output, try again. Most of those steps are mechanical. All of them, by default, go to the same model at the same price.

Reality Router serves the Anthropic Messages API at /v1/messages, so Claude Code talks to it natively and each of those steps gets scored on its own:

• Per-step routing. The file reads and the greps can go somewhere cheap; the reasoning steps still reach for a strong model.
• No adapter to install. The router speaks Messages, including tool calls and streaming.
• Your whole pool is in play, not only Anthropic models — and the router still calls Anthropic when that's the right answer.
• Receipts per step, in a dashboard you own.

Here's the setup.

1. Point Claude Code at the router (30 seconds)

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="rr-local"

That's it. Put them in your shell profile to make it permanent.

[!IMPORTANT] No /v1 on the base URL. Claude Code appends /v1/messages itself. With http://localhost:8000/v1 it calls /v1/v1/messages, gets a 404, and reports it as "There's an issue with the selected model." — which sends you looking in entirely the wrong place.

The API key is a placeholder for a local router; the router calls providers with its own keys. If you've turned on API keys on the router, use one of those instead — Claude Code sends it the way the router expects.

Check the port first if you're not sure it's 8000:

reality-router status --json

2. Verify it worked (30 seconds)

Start Claude Code and give it something that needs a tool, not just an answer:

Create a file called rr-test.txt containing: routed via RR

Then open the dashboard at http://localhost:8000/metrics/dashboard. Claude Code appears in Agent Activity as claude-cli/<version> — for example claude-cli/2.1.278. One instruction produces several routed calls: the tool call, the result, and the reply are separate requests, each scored on its own.

If chat works but tools silently do nothing, you're on a router older than 0.0.7. Tool definitions weren't translated before that, so models either rejected them or answered with raw tool markup as plain text. Update the router.

Worth knowing: whose prompts, whose models

Claude Code's prompts are tuned for Claude models, and that shows when steps get routed elsewhere. In our own testing, small non-Claude models would sometimes invent file paths in tool calls — writing to /mnt/data/, a sandbox path from their own training, instead of the working directory — and then report success. The protocol worked perfectly; the model just went somewhere else.

Two practical consequences:

• Keep capable Claude models in the pool for this agent. Routing every step to nano-class models saves money and costs you reliability.
• This is a routing-policy question, not a compatibility one. If you want Claude Code's steps to stay on stronger models, raise the model preferences for the ones you trust, or pin them.

Why bother

If you use Claude Code seriously, you already know the shape of the bill: it isn't the hard questions, it's the volume. Hundreds of small, dull steps that would have been fine on a cheap model, all charged at the same rate.

• Per-step routing puts the boring steps on cheap models without changing how you work.
• One agent, many providers. The router can reach Anthropic, OpenAI, DeepSeek, Gemini and local models from inside Claude Code, and picks per call.
• You see the run. Every step, model, token count and cost, in real time — instead of discovering the shape of a long agent session after the fact.

Same CLI, same agent, same workflow. Just routed, and visible.

→ realityrouter.dev

Reality Router is open source and self-hosted. Setup verified with Claude Code 2.1.278 against Reality Router 0.0.7, September 2026.