Metadata-Version: 2.4
Name: caprock
Version: 0.3.0
Summary: Free, local stats for Claude Code — see your tokens, cache hit-rate and per-session spend, on your own machine.
Author: Cybrix LLC
License: Apache-2.0
Project-URL: Homepage, https://caprock.dev
Project-URL: Documentation, https://caprock.dev/docs
Project-URL: Changelog, https://caprock.dev/changelog
Keywords: aws,bedrock,claude,claude-code,llm,cost,tokens,usage,stats,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.14,>=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

**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](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 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:

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

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

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

| 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 your tokens, cache hit-rate & per-session spend (all time) |
| `caprock measure`     | Replays a workload direct vs through caprock — your own numbers  |
| `caprock statusline`  | Live stats under Claude Code's input (`… install` to set up)     |
| `caprock doctor`      | Checks your whole setup: backend, creds, proxy, meter — locally  |
| `caprock dashboard`   | Opens your local stats dashboard (served by the proxy)           |

## Built on Headroom

caprock builds on the open-source [Headroom](https://github.com/headroomlabs-ai/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](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.
