A Beginner's Guide to Caveman: Cutting Token Costs for AI Coding Agents

If you use an AI coding agent like Claude Code, Codex, or Gemini CLI regularly, you've probably noticed the token bill adds up fast. Every reply the model writes, every file it reads, every tool result it processes — all of it costs tokens, and tokens cost money. Caveman is an open-source project built entirely around one idea: agents can do the same work with a lot fewer tokens, if you tighten what goes in and what comes out.

The name is a joke — the tool literally makes your AI agent talk like a caveman ("why use many token when few token do trick") — but the engineering behind it is serious. This guide covers what it does, how it's put together, and how to try it.

The Core Idea

The first version of Caveman was simple: a skill that made an agent's replies short and blunt instead of long-winded. Compare these two answers to the same bug report:

A normal, unprompted agent might spend 69 tokens explaining that a React component re-renders because an inline object prop gets a new reference on every render, then recommend wrapping it in useMemo. Caveman's version gets there in 19 tokens: same fix, way fewer words.

That's Caveman 1 — it only shrank what the agent said. Caveman 2 goes further and shrinks what the agent reads too, since tool schemas, files, logs, and conversation history are sent in full on every single turn regardless of how terse the replies are. That's where most of the real cost lives, and it's what the newer parts of the project focus on.

Two Separate Products

Caveman is really two tools you can use independently or together:

• The skill (the original) makes the agent answer in short, caveman-style language while keeping code, commands, and error output byte-for-byte exact. It's MIT-licensed and works in more than 30 different agents.
• Caveman Proxy (the newer piece) is a local proxy that sits between your agent and the model provider, compressing what the agent reads — tool results, logs, file contents — before it ever reaches the model, with the original bytes always recoverable. The proxy runtime is licensed BSL-1.1 (source-available, not full open source), while the CLI itself is MIT.

Getting Started

To save on input (what the agent reads), install the proxy and wrap your agent with it:

npm install -g @caveman-ai/cli && caveman setup --install
caveman claude        # or codex · gemini · aider · opencode · hermes · openclaw

To save on output (what the agent says), just add the skill:

npx skills add JuliusBrussee/caveman

There's also a full installer (Node.js 18+) that sets up Claude Code hooks and a statusline, and detects every supported agent already on your machine:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.2.0/install.sh | bash

On Windows (PowerShell 5.1+):

irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.2.0/install.ps1 | iex

Once installed, you switch the skill's intensity with a slash command:

/caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
/caveman off

Finding Out Where Your Tokens Actually Go

One of the more useful pieces is caveman learn. It reads your existing agent session history on disk — locally, read-only, no account needed — and produces a report scoring your setup and ranking the biggest sources of wasted tokens (an oversized config file, a skill you never actually use, context you keep re-pasting every session, and so on).

caveman learn

Each finding is labeled by type: a safe fix you can apply without thinking twice, an offload opportunity (moving repeated context into memory), a habit worth reconsidering, or something load-bearing you genuinely need and shouldn't touch. If you want, you can hand the whole report to your own agent to act on:

caveman learn implement

This never edits files on its own — it proposes each change as a diff, applies only what you approve, then re-measures to confirm the fix actually lowered token usage per turn (and reverts anything that didn't).

Pixel Mode: The Headline Trick

This is the part that tends to raise eyebrows. Text is billed per token, but images generally aren't priced the same way. So Caveman Proxy can render dense blocks of text — large JSON tool catalogs, long log files, old conversation history — into PNG images and send those to the model instead, for models capable of reading them accurately.

caveman wrap --pixel claude

According to the project's own measurements, one dense request went from an estimated 55,413 text tokens down to about 11,402 image tokens — a roughly 79% reduction. It's worth noting this only pays off on dense, long-line content; sparse code with short lines doesn't compress well as an image, and Caveman's own "profitability gate" will skip the conversion in that case rather than force a bad trade.

Other Small Tools Bundled In

Installing the skill also brings along a handful of extras:

There are also a few "compressed subagent" presets (cavecrew-investigator, cavecrew-builder, cavecrew-reviewer) for locating, editing, and reviewing code with less overhead.

The Honest Caveat

To its credit, the project is upfront about a limitation: the skill only reduces output tokens. Input and reasoning tokens aren't touched by the skill alone, and the skill itself adds roughly 1,000–1,500 input tokens of overhead per turn just by being loaded. So the widely quoted 65% savings figure applies to output tokens specifically — whole-session savings will usually be smaller, and on tasks where the agent was already terse, it can occasionally go net-negative. The maintainers frame the bigger win as readability and speed, with cost savings as a bonus on top.

Which Agents Are Supported

Caveman wraps eight agents natively — Claude Code, OpenAI's Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent, OpenClaw, and Pi — using each agent's own configuration mechanism (mostly environment variables) rather than patching the agent itself. If your framework isn't on that list, you can typically point it at the local proxy by swapping its baseURL, which works with common frameworks like the Vercel AI SDK, LangChain, and LiteLLM.

Licensing, Briefly

Caveman uses a split license. The skill, CLI, client SDKs, and a few other adoption-facing pieces are MIT. The compression engine, the proxy itself, and a handful of other core runtime pieces are licensed under BSL-1.1 — source-available and free to self-host, but not OSI-approved open source until an automatic conversion to Apache-2.0 kicks in a few years after each version ships.

Where to Go Next

• Technical docs: docs/README.md
• Full install matrix (30+ agents, uninstall, flags): INSTALL.md
• Benchmark methodology: docs/WRAP-BENCHMARK.md
• Source code: github.com/juliusbrussee/caveman

If your agent bills are creeping up and you're not sure why, caveman learn alone is worth trying before you touch anything else — it's read-only, and it'll tell you exactly where the tokens are going.