Metadata-Version: 2.4
Name: caprock
Version: 0.1.38
Summary: Cut AWS Bedrock LLM spend from Claude Code — compression + prompt caching, on your machine.
Author: Cybrix LLC
License: Apache-2.0
Project-URL: Homepage, https://caprock.dev
Keywords: aws,bedrock,claude,claude-code,llm,cost,compression,prompt-caching,headroom
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: headroom-ai[proxy]==0.31.0
Requires-Dist: boto3
Requires-Dist: httpx
Requires-Dist: click>=8
Requires-Dist: orjson>=3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

# 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](https://docs.anthropic.com/claude-code) — install it first).

```bash
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:

```bash
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 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.:

```bash
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:

```bash
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](https://github.com/headroomlabs-ai/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.
