caprock

Free, local stats for Claude Code. See your token usage, cache hit-rate and what each session really costs — right in your terminal. caprock runs your session through a small local proxy and shows what the terminal normally hides. It measures; it never touches your prompts or your bill. Works on AWS Bedrock, the direct Anthropic API, or a plain Claude subscription — auto-detected. Nothing leaves your machine.

Does it save money? caprock itself doesn't cut your bill — it shows you where the money goes. The saving you'll see comes from prompt caching, which Claude Code already turns on for you (Bedrock and the Anthropic API both bill cached tokens at a fraction of the input price). caprock splits the cached share out line by line so you can see it working — and see when it stops.

Install

Prereqs — check, don't guess: python3 --version (need 3.10+ — the AWS Bedrock backend needs 3.10–3.13: litellm has no Python 3.14 support yet, and caprock will refuse to start Bedrock on 3.14 with the fix printed: pipx install --force --python python3.13 caprock; the Anthropic/subscription path is fine on 3.14) and claude --version (caprock wraps Claude Code — install it first).

pipx install caprock         # recommended — works where plain pip is refused (PEP 668)
caprock --version            # verify
caprock wrap claude          # your Claude Code now runs through it
caprock stats                # see your tokens, cache hit-rate & spend

No pipx? brew install pipx (macOS) / sudo apt install pipx (Debian/Ubuntu), then pipx ensurepath. Alternatives: uvx caprock (zero-install) · pip install caprock (fine in a venv or CI). Hit externally-managed-environment, an old-Python stub, or any other install error — every case is solved at https://caprock.dev/install.

Windows: we develop and test on macOS and Linux; native Windows is untested — recommended: WSL2, then the Linux steps unchanged. Uninstall: pipx uninstall caprock (plus rm -rf ~/.caprock for local stats data).

Upgrades: pipx upgrade caprock / pip install -U caprock — what's new: https://caprock.dev/changelog. Backends, stats, troubleshooting: https://caprock.dev/docs.

Which backend?

Say it explicitly and it always wins:

caprock wrap claude --bedrock                     # force AWS Bedrock (your AWS creds)
caprock wrap claude --bedrock --profile work      # …signing with a specific AWS profile
caprock wrap claude --anthropic                   # force the direct Anthropic API

--profile <name> picks which AWS profile signs Bedrock (it implies --bedrock); without it caprock uses your AWS_PROFILE / default profile — the startup line tells you which one it picked. --region picks the Bedrock region (default us-east-1 or your AWS_REGION).

caprock start --host <addr> sets the bind interface (default 127.0.0.1, local only). Use --host 0.0.0.0 only if you deliberately run caprock in a container and need other hosts to reach it. On your own machine you never need it — the default keeps the proxy local.

With no flag, caprock wrap claude auto-detects from your environment:

Whichever way it's chosen, the session's first line states it explicitly — you never have to guess what you're running on:

Backend: AWS Bedrock — profile “work” · region us-east-1
Backend: Anthropic API — your ANTHROPIC_API_KEY (…1234)
Backend: Anthropic subscription — logged in as you@company.com

The subscription line comes from Claude Code's own login (the account email in ~/.claude.json) — caprock never reads tokens or your keychain.

The backend and profile are baked in when the proxy starts. If a caprock proxy is already running (another wrapped session), your flags apply only once it's gone — exit the other session, or use a different --port.

Tip: alias claude='caprock wrap claude' — every session runs through caprock. Sessions started without wrap bypass caprock entirely.

Anything after caprock wrap claude that isn't a caprock flag (--bedrock, --anthropic, --profile, --region, --port) is passed straight through to Claude Code itself, so its normal flags work unchanged, e.g.:

caprock wrap claude --dangerously-skip-permissions
caprock wrap claude --bedrock --profile work --dangerously-skip-permissions
caprock wrap claude --resume

Never run caprock wrap with sudo — it doesn't need root, and running it once as root can leave ~/.caprock files owned by root that your normal user can no longer write to.

Known limitation: /remote-control doesn't work in wrapped sessions. Claude Code (≥2.1.196) disables Remote Control whenever ANTHROPIC_BASE_URL points anywhere but api.anthropic.com — any proxy or gateway, caprock included. That check lives in Claude Code itself, so we can't fix it from our side. Need Remote Control? Start that session with plain claude.

Live status line (optional, recommended)

One command puts your stats under Claude Code's input box, updated after every turn:

caprock statusline install   # backs up ~/.claude/settings.json first

⛰ caprock · $4.12 from cache this session · −54.7% input · context 46.2k (23% full) · each turn costs ~$0.14 — /clear resets it

Honest per payment path: on a flat-rate Claude subscription it marks the money as an API-price equivalent — 8.8M tok from cache this session (≈$26.45 @API) — never an unqualified "saved $". In a session started without caprock wrap it says so instead. Remove any time by deleting the statusLine key from ~/.claude/settings.json.

Every session ends with a summary of what the cache did for you:

💰 Cache saved $19.20 this session — on AWS Bedrock
   6.4M tokens served from cache · −85.0% input cost · 40 requests
   this month: $19.20 so far → ~$74/mo at this pace

Your payment path rides the headline. Since 0.1.23 caprock stats prints one labeled block per payment path — run on several (say Bedrock at work, a subscription at home) and each gets its own block with its own attribution, never blended into one figure.

On a Claude subscription (Pro/Max) the money is shown as an API-price equivalent labeled notional (your plan is flat-rate), and the cache is attributed honestly: the prompt cache is Anthropic's own feature (Claude Code sets the markers itself), so caprock just makes it visible:

💰 On your Claude subscription: 144.7M tokens from cache (≈$434.08 @API — notional, flat-rate plan)
   prompt cache (Anthropic's own): 144.2M tok · ≈$432.54
   compression (caprock): 512k tok · ≈$1.54
   −90.0% input · 187 requests — easier on your plan's usage limits

Cheat-sheet — what the numbers mean on YOUR plan: AWS Bedrock or an Anthropic API key → real dollars, per token. A Claude Enterprise seat → also real dollars (Enterprise bills all usage at API rates on top of the seat). Pro / Max / Team seat → flat rate, so the dollars are notional; the real win is seeing when the cache stops engaging and your context balloons.

On the direct Anthropic API (your key) the dollars are real, and the block credits the prompt cache to Anthropic (Claude Code sets the markers itself):

💰 Cache saved $16.50 this session — on the Anthropic API
   5.5M tokens from cache · −91.7% input cost · 203 requests
   prompt cache (Anthropic's own): 4.5M tok · compression (caprock): 1M tok

Want to see the effect on your own workload? Run caprock measure — it replays a session direct vs through caprock and prints your own numbers. No promised percentages here: caprock shows what your traffic actually does.

What it does

• Shows your usage — caprock stats and the end of every wrap session print tokens, cache hit-rate and per-session spend, computed locally from your own cache tokens. caprock stats --reset starts the count from zero (the old log is archived, never deleted). The log is append-only and survives upgrades — old records stay readable forever.
• Splits out the cache — separates the cached share (billed at a fraction of input price) from the rest, so you can see caching working and see when it stops.
• Compression — shrinks tool outputs / logs / JSON before they reach the model. Note: in cached agent sessions it stands aside to protect the cached prefix, so its effect there is near zero; it helps mainly on uncached one-shot payloads. caprock measure shows what it does on your traffic.
• Runs on localhost, signs with your credentials. No caprock service in the request path — nothing leaves your machine.
• Upgrade-aware — a running proxy outlives pipx upgrade caprock; wrap claude and doctor say out loud when the proxy was started by an older caprock, so you know to restart the wrapped session.

Commands

Built on Headroom

caprock builds on the open-source Headroom engine (Apache-2.0). While building the meter we contributed general-purpose fixes back upstream — cache-usage visibility and token counting. See https://caprock.dev/contributing.

Built on Headroom

caprock builds on the open-source Headroom project (Apache 2.0). It applies the general-purpose fixes that make caching and compression work on AWS Bedrock (contributed back upstream) over the stock headroom-ai package. Licensed Apache-2.0.