Use with Claude Code¶

Route Claude Code through context-guru with one environment variable — no changes to Claude Code itself.

The plugin does all of this for you, including installing the binary and choosing a scope: Install the Claude Code plugin. What follows is the same thing by hand.

You do not need an API key¶

See Install the plugin: You do not need an API key — the same applies here, whether you route through the plugin or by hand below. One addition specific to routing by hand: setting ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in your Claude Code environment is what moves you onto metered API billing, and that's a separate concern from keeping the API key out of Claude Code below, which is about the proxy holding the key, not Claude Code.

Steps¶

Start the proxy:
```
context-guru-proxy --preset codesmart
```

Point Claude Code at it:

ANTHROPIC_BASE_URL=http://localhost:4000/anthropic claude

Check that traffic is arriving:

curl -s localhost:4000/stats | jq '.requests, .savings_pct'

That is the whole integration. Every request now flows through the pipeline, and the response path resolves context_guru_expand calls automatically.

Make it stick for a repo¶

Add to .claude/settings.json so you don't export anything by hand:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000/anthropic"
  }
}

Use .claude/settings.local.json instead if you do not want to commit it: a base URL pointing at localhost breaks Claude Code for everyone who clones the repo whenever the proxy is not running.

That is the shape the plugin writes, except that it does not use a fixed port: it allocates a free one per project and records it, so two projects with different configurations never end up sharing a proxy and restarting it out from under each other. The scan starts at 8787 and skips ports already in use: landing on one another local API proxy had already taken is a silent, confusing failure, because two proxies on loopback are indistinguishable from each other by URL alone.

Keep the API key out of Claude Code¶

Give the proxy the real key and hand Claude Code a placeholder; the proxy injects the credential on forward:

ANTHROPIC_API_KEY=sk-ant-real... context-guru-proxy --preset codesmart

ANTHROPIC_BASE_URL=http://localhost:4000/anthropic \
ANTHROPIC_AUTH_TOKEN=placeholder \
  claude

Leave ANTHROPIC_API_KEY unset on the proxy to pass Claude Code's own auth straight through instead.

Troubleshooting

No savings, and the dashboard stays empty. Almost always an env block in ~/.claude/settings.json that sets ANTHROPIC_BASE_URL. It wins over the variable you exported, and the failure is silent — Claude Code answers normally, the traffic just never reaches the proxy. Check it:

python3 -c "import json;print(json.load(open('$HOME/.claude/settings.json')).get('env',{}).keys())"

Fix it by putting the override in the settings file, or by passing a per-invocation settings file so your global config is left alone:

claude --settings '{"env":{"ANTHROPIC_BASE_URL":"http://localhost:4000/anthropic"}}'

Prove the routing rather than assume it. Point Claude Code somewhere impossible and check that it fails. If it still answers, it is not using your base URL:

ANTHROPIC_BASE_URL=https://127.0.0.1:1/nope ANTHROPIC_AUTH_TOKEN=bogus \
  claude -p 'say PONG' --max-turns 1     # must FAIL

Which preset? codesmart is the recommended pipeline and the cheapest arm in the benchmarks at the highest reward. Use coding if you want skeleton to strip function bodies out of large source reads — it needs a cg_skeleton build. See Choose a preset.

context-guru-proxy exits with unknown component "skeleton". The coding preset needs a build with the cg_skeleton tag; make build does not pass it.

Pinning the model. context-guru forwards whatever model Claude Code sends. Set FORCE_MODEL on the proxy to override it (useful in eval harnesses).

Starting the proxy and the agent in one command. scripts/with-guru.sh does both:

scripts/with-guru.sh codesmart -- claude

Edit this page