MIT

Add the local tools

Install the CLI, wrap your agent through the proxy, find your token sinks, and measure a real session.

The CLI puts a local proxy in front of your coding agent so the logs, JSON, diffs and tool output it reads arrive at the provider smaller, and gives you the commands to find your token sinks and measure the difference on your own sessions. Everything runs on your machine and needs no account.

Only want shorter answers out of the agent? That is the Quickstart, and it needs none of this.

Needs Node.js 22.13 or newer.

Install the CLI and the binaries. The CLI is plain JavaScript; compression and metering run in signed Go binaries that setup --install fetches, about 205 MB into ~/.caveman/bin/.

terminal

npm install -g @caveman-ai/cli && caveman setup --install

caveman setup with no flag prints what resolved:

text

caveman setup — Go binary status
The CLI itself is plain JS; compression/metering run in these binaries.

✓ caveman-proxy   …/.caveman/bin/caveman-proxy
    powers: start · wrap · stats · verify — local compression + truthful metering
✓ caveman-engine  …/.caveman/bin/caveman-engine
    powers: compress · shrink · retrieve · toon · evals
✓ caveman-mcp     …/.caveman/bin/caveman-mcp
    powers: mcp install — agent-side recovery that lets streaming requests compress
✓ cavemem         …/bin/cavemem
    powers: remember · recall · learn offload
✓ caveman-browse  …/.caveman/bin/caveman-browse
    powers: browse + agent-side compressed browsing MCP tools — wrap auto-registers once present
✓ caveman-shrink  …/.caveman/bin/caveman-shrink
    powers: compress catalog — dedicated tool-schema compression, lint, and recovery

✓ All required binaries found. Try: caveman claude

Paths are shortened here with …; yours print in full.

Find where your tokens go. caveman learn reads the agent history already on your disk, locally, and ranks the sinks worst first.

terminal

caveman learn --plain

Trimmed from one real run over 30 days of Claude Code and Codex history, which took 12 seconds on a machine holding 4,357 sessions:

text

scanning local sessions (last 30d)…
claude-code 2057 · codex 2300 · scoring…
Setup Score 79/100
local setup · inferred · not billed spend · separate from org Cave Score
4357 sessions · Claude 2057 · Codex 2300
since your last run 13d ago: 226 moves gone · 41 new

top moves
1  457 context blocks repeat across sessions
   recurring context · largest ~3k tokens · up to 68 sessions · inferred
   Review selected blocks before moving them to memory; repetition does not prove they are unnecessary.
2  Bash re-fetched 3 times in one session
   behavioral · inferred
   Request enough output once, or narrow the query before repeating pagination variants.
protected  agent config loads ~2102 tokens into every turn · included in score, never auto-fixed

next:  caveman learn implement   fix with Claude Code or Codex; asks before every edit
details: caveman learn --all   553 findings

report: /Users/…/.caveman/reports/caveman-learn.html

Drop --plain for the interactive view, or add --json or --md for a machine-readable one. caveman learn implement hands the findings to Claude Code or Codex one diff at a time and asks before every edit. Full detail on caveman learn.

3
Wrap your agent. caveman claude starts the local proxy, points Claude Code at it through that agent's own wiring, and launches it. Your provider key and your Claude subscription login pass through to the provider; the proxy compresses eligible context on the way out and keeps the original bytes on disk.
terminal
```
caveman claude
```
The README lists the rest on the same line: codex, gemini, aider, kilo, qwen, opencode, hermes, openclaw and pi. caveman wrap <agent> runs one session and leaves nothing behind, while caveman <agent> writes the routing so it survives restarts. Wrap an agent has the per-agent detail.
The proxy only elides bytes from a streaming turn when the agent can ask for them back, which is the caveman_retrieve tool from the MCP server. caveman claude installs that server into Claude Code's own config as part of the integration, and caveman <agent> does the same for codex, gemini, hermes and opencode. A session-only caveman wrap hands Claude Code and Codex a temporary copy. Every other agent needs it registered once:
terminal
```
caveman mcp install kilo
```
Wrap an agent has the per-agent table, including the two agents that prove the tool per request instead.
Check both facts on the running proxy, in another terminal while the agent is up:
terminal
```
~/.caveman/bin/caveman-proxy status
```
json
```
{
  "owner": "wrap",
  "mode": "compress",
  "recovery_via_mcp": true
}
```
Trimmed from one real run: the full document also carries the port, the pid, the instance token, the start time and the binary version. "mode": "compress" is the proxy rewriting payloads rather than only metering them, and "recovery_via_mcp": true is the retrieve tool being reachable. Without the tool that line reads false, the proxy still compresses non-streaming API-key traffic, and streaming turns pass through untouched.
In a pinned Claude Code benchmark, wrapping used 33.2 percent fewer provider-reported input tokens across 18 paired runs, 95 percent interval 14.6 to 48.5. One case regressed 9.9 percent. All exact-answer checks passed. That is pinned counterfactual evidence, not your traffic.

Read what the proxy did. caveman stats aggregates the local store.

terminal

caveman stats

Trimmed to the token fields from one machine's store:

json

{
  "requests": 38293,
  "compression_tokens_before": 13096725,
  "compression_tokens_after": 10212723,
  "compression_tokens_saved": 2884002,
  "compression_token_count_basis": "estimated_engine_o200k",
  "requests_eligible_for_compression": 18449,
  "basis": "inferred"
}

basis: inferred is the whole point of the field: these are offline tokenizer counts for your own payloads, not a provider invoice. See Numbers and limits.

5
Measure it on your own work. caveman trial runs one session through its own proxy on its own port, so the before and after come from the same task rather than from this page.
terminal
```
caveman disable claude
caveman trial -- claude
caveman enable claude
```
The disable is not optional when you have already run caveman claude. Persistent routing pins the base URL inside the agent's config file, the agent prefers its config over the environment, and the trial's own listener would then capture nothing. The CLI refuses up front and prints those three lines rather than handing you a report full of zeros.
Read the result with caveman trial report, or caveman trial report --html. More on caveman trial.

Verify#

terminal

caveman setup                                   # every binary, its resolved path, and what it powers
caveman stats                                   # the local store, aggregated
npx -y github:JuliusBrussee/caveman -- --list   # every supported agent, with the detected ones marked

Undo#

Turn off proxy routing for one agent with caveman disable claude, then remove everything the installer wired:

terminal

npx -y github:JuliusBrussee/caveman -- --uninstall

Run that before npm uninstall -g @caveman-ai/cli: it hands the native agent integrations to caveman disable --all, so it needs the CLI still on PATH.

Three things survive the uninstaller, per INSTALL.md:

Skills installed through npx skills add, which the skills CLI owns. Remove them with npx skills remove caveman.
Per-repo rule files written by --with-init: .cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md, .opencode/AGENTS.md and AGENTS.md.
$CLAUDE_CONFIG_DIR/.caveman-history.jsonl, which keeps lifetime stats.

Delete the last two by hand if you want them gone.