Metadata-Version: 2.4
Name: caprock
Version: 0.1.14
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: 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
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's silently broken) and on the **direct
Anthropic API**. Nothing leaves your machine.

## Install

Prereqs — check, don't guess: `python3 --version` (need 3.10+) 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`).

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 · −61.4% input · ctx 46.2k (23%) → /clear resets ~$0.14/turn
```

Same honesty as `caprock stats`: on a flat-rate Claude subscription it shows
tokens cut (and the /clear figure in tokens), never "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
   6,400,000 tokens cut · −85% input cost · 40 requests
   this month: $19.20 so far → ~$74/mo at this pace
```

On a Claude subscription (Pro/Max) caprock is honest about the money: your
plan is flat-rate, so the summary shows the real tokens cut plus an API-price
comparison explicitly labeled **notional** — lighter usage against your plan's
limits, not cash saved:

```
💰 caprock cut 6,120,000 tokens on your Claude subscription
   −90% input · 158 requests — easier on your plan's usage limits
   at API prices that's $20.40 → $2.04 (−$18.36) — notional: your subscription is flat-rate
```

Bedrock and API-key traffic keeps the real dollar line; a mixed history shows
the two separately, never blended into one figure.

Measured live against real Bedrock: **−48%** billed input on a clean install,
**−59.7%** re-confirmed on a six-turn agent session, up to **−70%** with the
full pipeline. On the direct Anthropic API (compression only — caching already
works there): up to **−55%** on tool-heavy JSON. 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.
- Runs on **localhost**, signs with **your** Bedrock credentials. No caprock
  service in the request path — nothing leaves your machine.

## 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 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.
