--- title: Add the local tools summary: Install the CLI, wrap your agent through the proxy, find your token sinks, and measure a real session. canonical: https://docs.caveman.so/docs/quickstart/cli license: MIT capability: cli updated: 2026-09-16T21:32:40-07:00 basis: inferred --- # 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](/docs/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/`. ```bash npm install -g @caveman-ai/cli && caveman setup --install ``` `caveman setup` with no flag prints what resolved: ``` 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. ```bash 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: ``` 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](/docs/skill/learn). **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. ```bash caveman claude ``` The README lists the rest on the same line: `codex`, `gemini`, `aider`, `kilo`, `qwen`, `opencode`, `hermes`, `openclaw` and `pi`. `caveman wrap ` runs one session and leaves nothing behind, while `caveman ` writes the routing so it survives restarts. [Wrap an agent](/docs/proxy/wrap) 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](/docs/mcp). `caveman claude` installs that server into Claude Code's own config as part of the integration, and `caveman ` 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: ```bash caveman mcp install kilo ``` [Wrap an agent](/docs/proxy/wrap#recovery-has-to-be-installed) 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: ```bash ~/.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](https://github.com/JuliusBrussee/caveman/blob/main/docs/WRAP-BENCHMARK.md), 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. ```bash 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](/docs/counting). **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. ```bash 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](/docs/trial). ## Verify ```bash 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: ```bash 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](https://github.com/JuliusBrussee/caveman/blob/main/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.