caprock 0.1.30

Cut AWS Bedrock LLM spend from Claude Code — compression + prompt caching, on your machine.

caprock

Cut your Claude Code token bill — context compression + prompt caching, on your machine, with your own credentials. Works on AWS Bedrock (where it also fixes prompt caching that silently never engages on Claude Code's proxy path) and on the direct Anthropic API. Nothing leaves your machine.

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 what you saved

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 savings data).

Upgrades: pipx upgrade caprock / pip install -U caprock — what's new: https://caprock.dev/changelog. Backends, savings, 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 when caprock runs as a shared gateway in a container behind a load balancer, so other hosts can 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:

Your setup	What happens
CLAUDE_CODE_USE_BEDROCK=1	signs Bedrock with your creds
ANTHROPIC_API_KEY set	routes to the Anthropic API
Plain Claude subscription (Pro/Max, no env key)	routes to the Anthropic API — detected via your Claude login
None of the above	Bedrock (the default)

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 [e-mail]

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 savings under Claude Code's input box, updated after every turn:

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

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

Same honesty as caprock stats: on a flat-rate Claude subscription it leads with tokens cut and marks the money as an API-price equivalent — cut 8.8M tok 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 the money you saved:

💰 You've saved $19.20 with caprock — on AWS Bedrock
   6.4M tokens cut · −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) caprock is honest about the money — twice over. The dollars are an API-price equivalent labeled notional (your plan is flat-rate), and the cut is attributed honestly: on the direct-Anthropic path the prompt cache is Anthropic's own feature (Claude Code sets the markers itself and would cache without caprock too) — caprock's added cut there is compression:

💰 On your Claude subscription: cut 144.7M tokens (≈$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 slower limit burn — and any extra usage past your limits bills at API rates, which caprock cuts for real.

On AWS Bedrock the cache line IS caprock's doing — stock proxying leaves Bedrock's cache silently dead, we fix it — so the Bedrock block keeps the unified real-dollar line. On the direct Anthropic API (your key) the dollars are real too, but the block credits the prompt cache to Anthropic (Claude Code sets the markers itself) and caprock with compression:

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

Measured live against real Bedrock: −48% billed input on a clean install, −58.4% on Claude Code Bedrock sessions, up to −70.4% with the full pipeline (SDK, compression + caching stacked). On the direct Anthropic API the prompt cache is Anthropic's own and already works — there caprock is the honest per-session meter; compression adds up to −55% only on uncached one-shot JSON payloads (SDK calls), and deliberately stands aside in cached sessions to protect the cache. Your number will vary with your workload — run caprock measure to see yours. How we got these: https://caprock.dev/methodology.

What it does

• Compression — shrinks tool outputs / logs / JSON before they reach the model.
• Prompt caching — makes Bedrock's prompt cache actually engage (stock Headroom's markers die in conversion → 0% on Bedrock; caprock fixes that).
• Savings meter — caprock stats and the end of every wrap session show what you saved, computed locally from real Bedrock cache tokens. caprock stats --reset starts the count from zero (the old log is archived, never deleted). The log itself is append-only and survives upgrades — format changes are additive, old records stay readable forever.
• Runs on localhost, signs with your Bedrock 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

Command	What it does
caprock wrap claude	Runs Claude Code through the local proxy on your own creds
caprock start	Starts the proxy on its own (point any client at it)
caprock stats	Shows what you've saved (cache + compression, all time)
caprock measure	Replays a workload direct vs through caprock — your own number
caprock statusline	Live savings under Claude Code's input (… install to set up)
caprock doctor	Checks your whole setup: backend, creds, proxy, meter — locally
caprock dashboard	The team-tier dashboard (per-user & per-role spend, in your VPC)

Team?

Running Claude across a team? The managed tier is a shared in-VPC gateway with per-user / per-role cost attribution, a team dashboard, deployment and support — deployed inside your own AWS account, nothing leaves your VPC. Pricing and a 20-min call: https://caprock.dev/pricing.

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.