Caveman: Token Compression for AI Agents

1. Project Overview

Caveman is an open-source toolkit — a Claude Code-style skill plus a local proxy — that cuts the token consumption of AI coding agents by compressing both what they read (inputs) and what they say (outputs), without losing exact code, errors, or critical context.

2. Background & Positioning

Core mission: as agentic coding sessions grow longer, context windows fill up fast and API bills climb with them. Caveman's stated philosophy — "why use many token when few do trick" — is to shrink verbose tool output, logs, JSON, and diffs on the fly so agents can do more work inside the same budget, while guaranteeing the original bytes are always recoverable.
Two complementary products: the original Caveman skill makes an agent's own responses terser (roughly 65% output-token reduction in benchmarks) at the cost of a small per-turn overhead. Caveman 2, the newer local proxy, intercepts provider-bound traffic and compresses inputs before they ever leave the machine (a pinned benchmark reports 33.2% fewer provider-reported input tokens).
How it differs from similar projects: rather than trying to summarize or paraphrase content (which risks losing exact code or stack traces), Caveman applies content-type-aware, lossless-safe compression — it only ships a transform when it measures strictly smaller, keeps a content-addressed original for byte-exact recovery, and is explicit in its own documentation ("Honest Numbers") about which savings are locally inferred versus independently benchmarked.

3. Feature Categories

🗜️ Compression Engine
Type-aware compressors for the content agents deal with most:

JSON structural compression (keys/structure/error trees) — 70–90% typical reduction
Log compression (errors, traces, boundaries) — 85–95%
Code compression (imports, signatures, types) — 40–70%
Diff compression (headers, changed lines) — 60–80%
Search-result and text/HTML compression — 50–95%
Purpose: shrink the noisiest, most repetitive content types before they burn context tokens.

🖼️ Pixel Mode
Renders dense text (bundled tool catalogs, long logs) to PNG images for vision-capable models, with one documented case going from ~55k text tokens to ~11k image tokens (−79%).
Purpose: trade text tokens for image tokens when a model can read images more cheaply than raw text.

🧠 Learning & Analysis
The caveman learn command scans an agent's local history to find token sinks and classify fixes.
Purpose: surface concrete, quantified savings opportunities without sending data anywhere or billing the user.

🔌 Agent Wrapping
Native wrapping for Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent, and OpenClaw, plus baseURL-level compatibility with frameworks like Vercel AI SDK, LangChain, LiteLLM, CrewAI, and PydanticAI — 30+ agents in total.
Purpose: let any existing agent setup route through the compressing proxy with minimal or no code changes.

🧰 CLI Utilities
Standalone commands such as caveman shrink, caveman browse, caveman mem remember|recall, and caveman toon encode|decode.
Purpose: give developers direct, scriptable access to the same compression primitives outside of an agent session.

4. Key Highlights

Byte-exact recovery: every compressed payload has its original bytes stored in content-addressed storage before compression ships, so nothing is truly lost.
Compress-only-when-smaller guarantee: transforms only run when they measurably reduce size; declines are logged with a reason instead of silently degrading content.
Split input/output compression: the skill (outputs) and the proxy (inputs) can be adopted independently, so teams can start with whichever gives them more value.
Transparent benchmarking: the "Honest Numbers" documentation distinguishes locally inferred savings from independently measured benchmark results, avoiding inflated claims.
Selectable intensity levels: the in-agent /caveman skill supports multiple compression intensities (lite, full, ultra, and a "wenyan" variant) to match different verbosity needs.
Broad agent coverage: works across 30+ agents and frameworks via native wrapping or simple baseURL configuration, rather than locking users into a single agent product.

5. Use Cases by Role

General developers: reduce token spend and context bloat during everyday agentic coding sessions (Claude Code, Codex, Gemini CLI, Aider, etc.) without changing how they prompt.
DevOps/SRE: compress verbose CI logs, command output, and diagnostics (caveman shrink -- [command]) so agents can triage incidents inside a smaller context window.
Data/research scientists: use caveman learn to analyze agent session history and quantify where tokens — and therefore cost — are actually being spent, informing workflow changes.
Project managers: reference the benchmark and "Honest Numbers" documentation to evaluate realistic cost-reduction expectations before rolling Caveman out across a team.

6. Getting Started

Find what you need
Browse the docs/ directory for architecture, CLI reference, security/privacy notes, and benchmark methodology, starting from the docs README.md.

Install / integrate

# Proxy (Caveman 2) — compresses inputs
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude   # or: codex, gemini, aider, hermes, openclaw

# Skill — compresses outputs, installed into an agent's skill directory
npx skills add JuliusBrussee/caveman

Contribute

git commit -s -m "your message"   # DCO sign-off is required on every commit

Run the relevant test suite for the package you touched (go test ./..., pnpm test, or pytest), keep PRs small and focused, and open them against the main repository. Questions can go to [email protected] or a GitHub discussion.

7. Project Structure

caveman/
├── agents/profiles/       # Agent wrapping definitions (Claude Code, Codex, Gemini CLI, ...)
├── integrations/recipes/  # Provider SDK integration examples (LangChain, LiteLLM, ...)
├── engine/                # Compression engine and pixel-mode rendering
├── browse/                # Browser content compression implementation
└── docs/                  # Architecture, CLI reference, benchmarks, security docs

8. Related Ecosystem

Upstream agents/platforms: Claude Code (Anthropic), OpenAI Codex CLI, Gemini CLI (Google), Aider, opencode, Hermes Agent (Nous Research), OpenClaw — Caveman wraps these rather than replacing them.
Complementary frameworks: Vercel AI SDK, LangChain, LiteLLM, CrewAI, and PydanticAI can point at the Caveman proxy via standard baseURL configuration.
Bundled third-party components: pxpipe (MIT), the Spleen font (BSD-2-Clause), and GNU Unifont (OFL-1.1 / GPLv2-with-font-exception) are used internally, particularly for pixel-mode rendering.

9. License

Caveman uses a split license by directory.

✅ Use, modify, and redistribute the skill, agent SDK, CLI, client SDKs, and adoption-surface tooling freely under MIT.
✅ Self-host the engine, proxy, cache engine, rewriter, browse functionality, and MCP server for your own first-party traffic under BSL-1.1 at no cost.
❌ Offer the BSL-1.1-covered components (engine/proxy/MCP server) as a third-party hosted or embedded service without a commercial license from the project.
ℹ️ The BSL-1.1-covered code automatically converts to Apache-2.0 on June 21, 2030, or four years after each version ships, whichever comes first.
ℹ️ GitHub's own metadata lists the license as "NOASSERTION" because the split MIT/BSL-1.1 model doesn't map to a single SPDX identifier — check the LICENSE files in each directory for the terms that actually apply.

10. FAQ

Q: Does Caveman ever silently corrupt or lose data?
A: No — every compressed payload keeps a content-addressed copy of the original bytes, and transforms only ship when they measure strictly smaller than the input; otherwise the decline is logged with a reason.

Q: Can I use just the output-compressing skill without the proxy, or vice versa?
A: Yes. The skill (npx skills add JuliusBrussee/caveman) and the proxy (npm install -g @caveman-ai/cli) are independent products and can be adopted separately.

Q: Which coding agents does Caveman support?
A: Native wrapping covers Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent, and OpenClaw, with 30+ agents reachable in total, including frameworks configurable via baseURL.

Q: Can I self-host the proxy/engine for my own team?
A: Yes, self-hosting for first-party traffic is free under BSL-1.1; a commercial license is only required to offer it as a hosted or embedded service to third parties.

Q: Where do the benchmark numbers (65%, 33.2%) come from?
A: See docs/HONEST-NUMBERS.md and docs/WRAP-BENCHMARK.md, which distinguish locally inferred estimates from independently pinned benchmark results.

11. Quick Links

Repository: https://github.com/JuliusBrussee/caveman
Documentation: https://github.com/JuliusBrussee/caveman/tree/main/docs
Contributing guide: https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md
Discussions / contact: GitHub Discussions on the repository, or [email protected]

12. Summary

Caveman gives AI coding agents a practical way to say and read less while losing nothing that matters — pairing a terser-output skill with an input-compressing local proxy, both backed by byte-exact recovery guarantees. It's most valuable for developers and teams running long agentic coding sessions across Claude Code, Codex, Gemini CLI, or similar tools who want measurably lower token spend without giving up exact code, errors, or logs.