Caveman compacts agent output and input to cut token spend without changing your model

The problem: agents burn tokens on noise

Caveman targets a specific waste: agents like Claude Code spend tokens on verbose command output, long error messages, and chatty replies. The README shows a normal agent response about React re-rendering at 69 tokens versus a Caveman-style reply at 19 tokens. That gap matters when you run agents for hours. The tool does two things: it compresses what the agent reads (via a proxy) and it changes how the agent answers (via a skill). The intended user is someone who lives inside a terminal with an AI coding agent and wants to stretch context windows or cut API costs. It is not for people who need full verbatim logs in every interaction.

Two products, two different token-saving mechanisms

Caveman splits into two installable pieces. The first is the Caveman Proxy, which sits between your agent and the provider. It detects the type of each payload (json, log, code, diff, search-result, text) and routes it to a compressor that keeps only what answers depend on. For example, a log payload keeps errors, stack traces, and first/last lines, and drops INFO and progress noise, targeting 85 to 95 percent savings. The second piece is the skill, which makes the agent itself answer in terse 'caveman-speak' while keeping code, commands, and errors exact. The proxy uses a runtime under BSL-1.1, while the CLI and skill are MIT. That licensing split matters if you plan to embed the proxy in a commercial product.

Install paths: from a one-liner to a full hook setup

The README gives several routes. The quickest for the proxy is `npm install -g @caveman-ai/cli && caveman setup --install`, then `caveman claude` (or `codex`, `gemini`, `aider`, `opencode`, `hermes`, `openclaw`). For the skill alone, `npx skills add JuliusBrussee/caveman` works for skills-compatible agents. A full installer script (`curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.3.1/install.sh | bash`) wires Claude Code hooks and a statusline, and is safe to rerun with Node.js 18+. Windows users get a PowerShell equivalent. There are agent-specific commands, like `claude plugin marketplace add JuliusBrussee/caveman` for Claude Code and `gemini extensions install` for Gemini CLI. The installation is not a single universal command; you pick based on your agent and whether you want hooks.

How the engine decides what to keep

The proxy's engine calls `detect()` to classify a payload, then applies a compressor tuned to that type. The table in the README is the core of the design. For JSON, it keeps keys, structure, and error/message subtrees while collapsing repetitive arrays, targeting 70 to 90 percent savings. For code, it keeps imports, signatures, and types, and elides function bodies while keeping syntax valid. For diffs, it keeps file/hunk headers and changed lines, dropping repeated context. The `contextwindow.Pack()` function then fits candidate context into a token budget using BM25 relevance, recency, and error signal, and returns items in original order so chronology survives. That ordering guarantee is important for agents that rely on conversation flow. The compression is lossy by design, but the proxy keeps recovery copies on disk, and the `caveman_retrieve` MCP tool can fetch original bytes.

The learning tool: measure before you compress

Caveman includes `caveman learn`, which scans your local agent history (Claude Code, Codex, Gemini CLI, opencode, and aider via `CAVEMAN_AIDER_ROOT`) and produces a report: a Cave Score, ranked token sinks with one-line fixes, context-window depth per session, and a list-price illustration of what each sink costs over 30 days. The command is read-only and local. `caveman learn implement` hands the plan to your own agent with the `caveman-learn` skill, which proposes each fix as a diff, applies only on your yes, re-measures, and reverts anything that did not lower tokens per turn. This is a practical way to find the biggest token drains in your actual workflow before you commit to a proxy. The README claims the tool never makes your agent dumber to make it cheaper, but that is a promise about the skill's instructions, not a measured guarantee.

The benchmark: one pinned run, not a general proof

The README links to `docs/WRAP-BENCHMARK.md` and claims a 33.2% reduction in provider-reported input tokens in a pinned 54-run Claude Code benchmark, passing all 18 exact-answer checks. That is a specific result under a specific setup. The benchmark is labeled `benchmark_counterfactual`, which suggests it compares a counterfactual scenario, but the details are in the linked doc, not in the README itself. The claim is notable because it uses provider-reported tokens, not local estimates, which adds credibility. However, a single benchmark with 54 runs does not cover all command outputs, all agent versions, or all provider quirks. You should treat the 33.2% as a best-case or typical-case figure for that pinned setup, and measure your own workload with `caveman learn` before assuming the same savings.

Limitations and failure modes

The compression is lossy. If the compressor drops an INFO line that later turns out to be the clue to a bug, you lose that signal. The README acknowledges this by keeping recovery copies on disk and offering `caveman_retrieve`, but that only helps if you know to look. The `code` compressor elides function bodies, which means an agent reading a compressed file might miss a subtle bug inside a function. The `text`/HTML compressor keeps headings and important sections, but 'important' is determined by heuristics, not by your task. The proxy requires you to route traffic through it, which adds a local dependency and a potential point of failure. The `browse` verb needs Chrome, so it will not work headless without a browser. Also, the BSL-1.1 runtime for the proxy is not OSI-approved, which could be a problem for some organizations even though the CLI is MIT.

Alternatives and how they differ

The obvious alternative is to do nothing and simply use a longer context window or a cheaper model. That approach avoids any risk of information loss but does not reduce the tokens you send. Another alternative is to write your own output filters, for example by piping command output through `grep` or `tail` before it reaches the agent. That gives you full control but requires manual effort for every command and does not compress JSON or code structures. A third alternative is to use a different agent that natively summarizes tool output, but that changes your toolchain. Caveman's difference is that it sits at the payload level, applies type-specific compressors automatically, and provides recovery. The trade-off is that you trade control for convenience, and you must trust the compressor's notion of what is 'important'.

Maintenance and upgrade cost

The repository shows recent activity: v2.3.1 was pushed on 2026-08-23, with v2.3.0 and bin-v1.1.3 the same day. That suggests active maintenance, but it also means you should expect frequent updates. The install script is safe to rerun, which helps with upgrades. The proxy is a local process, so you need to keep it running and updated. The MCP server exposes five tools, which means if you use an MCP host, you have a stable interface to compress, retrieve, and inspect stats. The skill is versioned via the `npx skills add` command, so you can pin a version if needed. The license situation is a maintenance cost in itself: you have to track which component is under which license, and the BSL-1.1 runtime may require a license change for commercial use. There is no documentation in the README about upgrade procedures beyond rerunning the installer, so plan to check the changelog before each update.

Editorial conclusion

Adopt Caveman if you run Claude Code, Codex, Gemini CLI, or similar agents daily and your token bill or context-window pressure comes from routine tool output and verbose replies. Skip it if you need byte-exact fidelity in every agent response or if you cannot accept a proxy that rewrites payloads before they reach your provider. Before production use, verify the compressor's behavior on your specific command outputs: run `caveman shrink -- <your command>` and inspect the recovered bytes with the retrieval tool, and check the WRAP-BENCHMARK.md limits for cases where exact-answer checks might fail. Also confirm the BSL-1.1 runtime terms for the proxy component if you plan to use it commercially, since the MIT license covers only the CLI and skill.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes