[GitHub] JuliusBrussee/caveman
Caveman 2 introduces a local proxy that compresses agent input (tool schemas, files, logs, history) before every provider call, achieving 33.2% fewer input tokens in a pinned Claude Code benchmark The original Caveman skill (v1) compressed agent output into concise "caveman-speak" while preserving byte-exact code/commands/errors; v2 extends this to input reduction The `caveman learn` analyzer scans local agent history, scores token sinks, and proposes fixes across four categories: safe fix, offl
Analysis
TL;DR
- Caveman 2 introduces a local proxy that compresses agent input (tool schemas, files, logs, history) before every provider call, achieving 33.2% fewer input tokens in a pinned Claude Code benchmark
- The original Caveman skill (v1) compressed agent output into concise "caveman-speak" while preserving byte-exact code/commands/errors; v2 extends this to input reduction
- The
caveman learnanalyzer scans local agent history, scores token sinks, and proposes fixes across four categories: safe fix, offload, habit, and load-bearing - The proxy requires no code changes, forwards requests to the original provider (e.g., Anthropic), and preserves OAuth credentials and recovery copies locally
- Supports 30+ agents including Claude Code, Codex, Gemini CLI, Cursor, Windsurf, and Cline, with dual licensing (BSL-1.1 runtime, MIT CLI)
Why It Matters
Token cost and context window management are among the most pressing operational challenges for AI agent practitioners; tools that demonstrably reduce input tokens without degrading agent capability directly lower inference costs and enable longer, more complex sessions. Caveman's approach of compressing both directions of agent communication (input and output) while guaranteeing byte-exact recovery of critical artifacts represents a practical, deployable optimization that doesn't require model fine-tuning or provider lock-in.
Technical Details
- Caveman Proxy: A local middleware that intercepts and compresses all input flowing to the provider (tool schemas, file contents, conversation history, logs) before each API call, with byte-exact recovery of original content stored locally
- Caveman Skill: An agent prompt/skill that instructs the model to produce compressed textual responses ("caveman-speak") while keeping code blocks, commands, error messages, and other structured output byte-for-byte identical to uncompressed output
- Benchmark Results: In a pinned 54-run Claude Code benchmark, the proxy achieved 33.2% reduction in provider-reported input tokens while passing all 18 exact-answer verification checks
caveman learnAnalyzer: Reads local agent history from disk (Claude Code, Codex, etc.), computes a "Cave Score," ranks token sinks by flow volume, and classifies each sink as safe fix / offload / habit / load-bearing;caveman learn implementproposes diffs for each fix and re-measures after application- Architecture: Go-based proxy runtime with Node.js CLI; supports OAuth passthrough for Claude Pro/Max; no backend dependency—traffic routes directly to the chosen provider through the local proxy
Industry Insight
- Input compression via proxy is a near-term, high-ROI optimization for any team running agentic workflows at scale; the 33% token reduction demonstrated here likely generalizes across providers and agent frameworks, directly translating to cost savings on per-token pricing models
- The "caveman-speak" output compression strategy could inspire a new class of agent prompt engineering techniques that decouple communicative efficiency from artifact fidelity—a principle worth formalizing and benchmarking across model families
- The
caveman learndiagnostic framework (history scanning, sink classification, diff-based remediation) represents a reusable pattern for agent observability and cost auditing that other tooling vendors could adopt or integrate into their platforms
Disclaimer: The above content is generated by AI and is for reference only.