# How Caveman Reduces AI Coding Agent Output Tokens: A Technical Deep Dive > Discover how Caveman reduces AI coding agent output by compressing prose up to 65% while preserving essential code and instructions. Learn the technical details. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: deep-dive - Published: 2026-07-07 --- **Caveman reduces AI coding agent output by truncating natural-language prose while preserving every technical token, achieving approximately 65% compression without altering code blocks, file paths, or functional instructions.** JuliusBrussee/caveman is an open-source skill that intercepts LLM responses to reduce AI coding agent output volume. By applying deterministic rewrite rules to conversational text while leaving technical content untouched, Caveman cuts token costs and improves response latency for Claude Code, Gemini, Cursor, and other agents. ## The Compression Algorithm: Four Deterministic Rules Caveman processes agent replies through a deterministic pipeline defined in [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md). The system targets only natural language, ensuring that functional instructions remain intact. ### 1. Filler Word Elimination The system strips hedging phrases like "you should", "I recommend", and "maybe" from responses. According to [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) (lines 10-12), this step removes conversational padding while retaining the core technical proposition. ### 2. Fragment Substitution Multi-word expressions collapse into short synonyms or abbreviations. For example, "new object reference each render" becomes "new obj ref each render" as implemented in [`src/plugins/opencode/commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman.md) (lines 8-10). ### 3. Technical Content Preservation The rewrite engine explicitly preserves code blocks, inline code, file paths, URLs, and markdown syntax. As documented in [`src/plugins/opencode/commands/caveman-compress.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md) (lines 8-10), this guarantees that the functional portion of any answer remains byte-for-byte identical. ### 4. Configurable Intensity Levels Four modes control compression aggressiveness, detailed in [`skills/caveman/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md) (lines 13-16): - **lite**: Removes only filler words and articles - **full** (default): Balanced reduction suitable for most workflows - **ultra**: Collapses phrases to bare fragments and abbreviations - **wenyan**: Extreme compression using minimal character sets ## Runtime Architecture and Hook System Caveman operates through a skill file dropped into the agent's workspace. The hook system detects when the agent emits a reply and invokes the rewrite algorithm before display. A flag file maintains the compression state for the session duration, as detailed in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) (lines 69-75). This architecture requires no modification to the underlying LLM—Caveman acts as a post-processor on the output stream. ## Command Reference Enable compression with the core command defined in [`src/plugins/opencode/commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman.md): ```bash # Enable full-mode compression (default) /caveman # Use lighter compression /caveman lite # Disable compression and return to normal prose stop caveman # or /caveman off ``` Process existing documentation for persistent compression: ```bash # Compress a markdown file for future sessions /caveman-compress docs/CLAUDE.md # Original preserved as CLAUDE.md.original.md ``` ## Measuring Token Savings The `/caveman-stats` command reads session logs to calculate efficiency gains: ```bash # Display savings with shareable format /caveman-stats --share # Output: [CAVEMAN] ⛏ 12.4k tokens saved (≈ $0.12) ``` Benchmarks in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) (lines 55-69) demonstrate a reduction from 1,180 tokens to 159 tokens—a ~65% decrease—while maintaining 100% technical accuracy. ## Summary - Caveman intercepts LLM responses to reduce AI coding agent output by approximately 65% - Four intensity levels (lite, full, ultra, wenyan) control compression aggressiveness - Technical content—code blocks, paths, URLs—remains unmodified per [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) - Installation requires dropping a skill file into the agent workspace - Session persistence managed via flag files in the hook system - Token savings measurable via `/caveman-stats --share` ## Frequently Asked Questions ### Does Caveman modify code inside my responses? No. The algorithm in [`src/plugins/opencode/commands/caveman-compress.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md) explicitly preserves code blocks, inline code, and file paths. Only natural language surrounding the technical content undergoes compression, ensuring functional integrity. ### Which AI agents support Caveman? Caveman works with Claude Code, Gemini, Cursor, and other coding agents that support skill file injection. The system detects replies generically through hook interception rather than agent-specific APIs, making it compatible with any tool that accepts workspace skills. ### How much token reduction can I expect? Benchmarks show approximately 65% reduction in output tokens when using the default `full` mode. For example, a 1,180-token response compresses to 159 tokens. The `ultra` and `wenyan` modes achieve even higher compression ratios by aggressively abbreviating prose. ### Can I permanently compress existing documentation? Yes. Use `/caveman-compress ` to rewrite markdown files into Caveman style. The command backs up the original as `.original.md` before applying the rewrite rules, allowing you to maintain compressed documentation for future reference without losing the source.