Caveman is a token-reduction toolkit for coding agents made of two parts. The original skill makes an agent answer in terse "caveman-speak" while code, commands, and error messages stay exact, cutting output tokens. Caveman 2 adds a local proxy that compresses what the agent reads before each provider call, with byte-exact recovery of the original content.
The skill installs into Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Copilot, and more than 30 other agents, and is switched with /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off. Across a ten-prompt benchmark the average reply dropped from 1,214 to 294 tokens (65%), with per-task savings from 22% to 87%. The skill only shrinks output tokens: input and reasoning tokens are untouched, and the skill itself adds roughly 1–1.5k input tokens per turn, so whole-session savings are smaller and can be negative on already-terse workloads.
The proxy (caveman ) wraps Claude Code, Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent, OpenClaw, and Pi without editing their config files, and forwards traffic to your chosen provider with credentials passed through. In a pinned 54-run Claude Code benchmark it used 33.2% fewer provider-reported input tokens while passing all 18 exact-answer checks. Other SDKs and frameworks connect through a baseURL swap.
The engine detects each payload type and routes it to a matching compressor:
| Detected type | Keeps | Target savings |
|---|---|---|
| json | keys, structure, error/message subtrees | 70–90% |
| log | errors, stack traces, first/last lines | 85–95% |
| code | imports, signatures, types; bodies elided | 40–70% |
| diff | file/hunk headers and changed lines | 60–80% |
| search-result | top/bottom hits plus diagnostic hits | 80–95% |
| text / HTML | headings and important sections | 50–80% |
Features
- Skill modes: lite, full, ultra, and three wenyan (classical Chinese) intensities, plus /caveman-commit, /caveman-review, /caveman-compress, and /caveman-stats commands
- Subagent presets: cavecrew-investigator, cavecrew-builder, and cavecrew-reviewer for locating, editing, and reviewing code
- Work patterns: investigate-first, lean-build, surgical-patch, safe-refactor, migration, and verify-and-stop prompts that aim to write less code per task
- caveman learn: reads local agent history from Claude Code, Codex, Gemini CLI, and opencode and ranks token sinks with a suggested fix; learn implement applies fixes through your own agent with per-edit consent
- Context packing: contextwindow.Pack() fits candidate context to a token budget by BM25 relevance, recency, and error signal while preserving order
- MCP server: cavemancompress, cavemanretrieve, cavemanstats, cavemantoonencode, and cavemantoon_decode for any MCP host
- Browse: a local Chrome session exposed as a compressed accessibility tree
- Pixel mode: caveman convert renders installed SKILL.md bodies to PNG pages when that costs fewer tokens than text, with byte-identical revert
- Memory and shrink: caveman mem remember|recall for durable memory and caveman shrink -- for compressed command output
- Telemetry: anonymous command and token-count stats are sent by default and disabled with caveman telemetry off or DONOTTRACK=1
Integrates with
Aider
Command-line LLM pair programmer that maps your repo, edits files, and auto-commits each change to git
Claude Code
Terminal-based agentic coding tool that reads your codebase and runs tasks through natural-language commands
Codex
Lightweight coding agent that runs in your terminal
Hermes
Self-improving AI agent with a learning loop that creates and refines skills, recalls past sessions, and runs across chat platforms
