My savings numbers aren't moving. Why?

Usually one of three things: you haven't accepted the Terms (optimization stays paused until you do), the hooks aren't installed, or Claude Code is on a different gateway port. Re-run --install-claude-hooks, accept consent, and confirm the port with --status.

Claude Code setup — TokenBeaver Docs

Q: tokenbeaver is missing from 'claude mcp list'.

Re-run the install (--install-claude-hooks or Repair Claude Code Hooks). The restore tool is gated on recoverable compaction being enabled, so make sure that's on.

Q: Some output looks truncated with an 'id=... call tokenbeaver_expand' stub.

That's recoverable compaction. Trimmed content isn't lost — the agent restores it on demand via the tokenbeaver_expand tool. If expand is ever unreachable, a safe head/tail of the content is kept as a fallback.

What Claude Code gets

Installing wires two things into Claude Code, both pointed at your local gateway on 127.0.0.1:

Hooks

Slimming on every turn

Read dedup, per-tool line budgets, and structural + recoverable compaction run as Claude Code hooks — each request is trimmed before it's sent, nothing the model needs is dropped. A cost-discipline skill nudges the agent toward leaner tool use.

MCP restore tool

`tokenbeaver_expand`

Recoverable compaction leaves a small stub in place of trimmed content. When the agent actually needs the full text, it calls tokenbeaver_expand to restore it on demand — so slimming is lossless, not lossy.

Two kinds of Claude users

The install is identical for both. What changes is how savings are framed — because a per-token bill and a flat subscription are two different things to optimize.

Cost · API key

Dollars saved

You pay Anthropic per token. Route Claude Code's Anthropic traffic through the gateway with the anthropic provider (or dual upstream), keeping your own key (BYOK, never stored). The dashboard shows dollars saved — an estimate on Free, verified on Pro.

Capacity · Pro / Max

Context stretched

On a Claude subscription there's no per-token bill to cut, so savings show as context stretched % and tokens reclaimed — how much further your 5-hour and weekly quota goes. These are honest estimates of quota runway, not a billed measurement, and you won't see an absolute dollar figure (by design).

Install

Pick your surface. Both wire the same hooks and restore tool.

CLI

One command

# wire hooks + the restore tool
tokenbeaver-gateway --install-claude-hooks
# then watch it work
tokenbeaver-gateway --dashboard

Keep the gateway running while you use Claude Code.

VS Code extension

From the status bar

The ⚡ TokenBeaver status-bar item wires Claude Code for you. To re-apply after a Claude Code update, run TokenBeaver: Repair Claude Code Hooks from the Command Palette.

What it writes

Nothing hidden — two files in your home directory, each written atomically, backed up first, and fail-open (if the gateway is unreachable, Claude Code keeps working normally).

File	What's added
`~/.claude/settings.json`	PostToolUse, PreToolUse, PreCompact, SessionStart and UserPromptSubmit hooks that call the gateway on `127.0.0.1:<port>`
`~/.claude.json`	`mcpServers.tokenbeaver` — the gateway's `/mcp` restore tool (`tokenbeaver_expand`)

Verify

Confirm the restore tool registered, then keep the gateway up:

claude mcp list # should list: tokenbeaver

If tokenbeaver shows up and the gateway is running, you're optimizing. Numbers appear on the dashboard (--dashboard) as you work.

Undo

Remove every hook and the restore tool with one command — your backups are restored:

tokenbeaver-gateway --uninstall-claude-hooks

Good to know

A couple of honest limits

The gateway is local. From the CLI it runs while the process is up; started from VS Code it runs in-process and stops when you close the editor. An always-on background service is the future desktop app, not shipped yet.
"Claude in Visual Studio" (Anthropic's own IDE extension) can't be captured — it has no localhost base-URL override and no hook file, so there's nothing to point at the gateway. Use the Claude Code CLI instead.
Capacity / "context stretched" figures are estimates, not billed measurements.

Troubleshooting

My numbers aren't moving

Usually one of three things: consent isn't accepted (optimization stays paused until you accept the Terms), the hooks aren't installed, or Claude Code is pointed at a different gateway port. Re-run --install-claude-hooks, accept consent on first run, and confirm the port with --status.

tokenbeaver is missing from claude mcp list

Re-run the install (--install-claude-hooks or TokenBeaver: Repair Claude Code Hooks). The restore tool is gated on recoverable compaction being enabled — make sure it's on.

Output looks truncated with an id=… call tokenbeaver_expand stub

That's recoverable compaction doing its job. The trimmed content isn't lost — the agent restores it on demand via tokenbeaver_expand. If expand is ever unreachable, a safe head/tail of the content is kept as a fallback, so the agent never loses the thread.

Consent re-prompt after a policy update

When the Terms change, optimization pauses until you re-accept — a deliberate safeguard. Accept again (first run, or --accept-terms) and it resumes.

"Estimate" vs "verified" on my numbers

Free shows estimated savings computed locally; Pro shows verified savings. Both use the same slimming — the label reflects how the dollars are measured, not how much you save.

I'm on Pro/Max — where's my "$ saved"?

By design. Subscription users don't pay per token, so there's no dollar bill to cut. You see context stretched and tokens reclaimed instead — an estimate of how much further your quota goes.

Found a bug or have a feature request?

Open a GitHub issue → · Questions? Support

Stuck on setup?

Email [email protected] or visit the support page — a real developer will get back to you.