github.com/JuliusBrussee/caveman @v2.2.0@v2.0.0@v1.10.0@v1.9.1@v1.9.0@bin-v1.1.1@bin-v1.1.0

why use many token when few do trick

Original skill made agents say less. Caveman 2 makes them read less too.

33.2% fewer provider-reported input tokens in a pinned Claude Code benchmark. benchmark_counterfactual

Keep your agent. Brain big. Context small.

See it · Install · Learn · Proxy · Pixel · Wrap · Docs · License

See it

🗣️ Normal agent — 69 tokens	Caveman agent — 19 tokens
> The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object.	> New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.

Same fix, fewer words. That was Caveman 1. Agent mouth got smaller. Appetite did not: tool schemas, files, logs, and history still cross the wire in full, every turn. Caveman 2 shrinks that too.

Install

Two products. Pick one or both.

Save input with Caveman Proxy, the new release. A local proxy that shrinks what your agent reads before every provider call, with byte-exact recovery. BSL-1.1 runtime, MIT CLI.

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

Save output with the skill, the original. Your agent answers in tight caveman-speak while code, commands, and errors stay byte-for-byte exact. MIT, works in 30+ agents.

npx skills add JuliusBrussee/caveman

Full installer, Windows, one agent only, uninstall

The full installer also wires the Claude Code hooks and statusline, finds every supported agent on your machine, and is safe to rerun (Node.js 18+):

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

Windows (PowerShell 5.1+):

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

One agent only:

# Claude Code
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

# Gemini CLI
gemini extensions install https://github.com/JuliusBrussee/caveman

# Codex, Cursor, Windsurf, Cline, and other skills-compatible agents
npx skills add JuliusBrussee/caveman --skill '*' -a codex --yes  # replace codex with your agent profile

Full 30+ agent matrix, dry run, flags, verification, and uninstall: INSTALL.md.

Prefer building the proxy from source instead of signed binaries? scripts/install-local-cli.sh (macOS/Linux) or pwsh -File scripts/install-local-cli.ps1 (Windows); needs Go and pnpm.

Where your tokens go

You have months of agent history on disk. caveman learn reads it and scores your setup. Local, read-only, no account.

caveman learn             # Claude Code + Codex + Gemini CLI + opencode; aider via CAVEMAN_AIDER_ROOT

The report shows your Cave Score, every token sink ranked by flow with a one-line fix behind each row, how deep each session ran into its context window, a replay of what the fixes would have cut from your past sessions, and a list-price illustration of what the ranked sinks cost over 30 days. Sink and cost numbers are inferred; the saved-so-far card is proxy-measured. None of it is a bill.

Every sink wears its class: safe fix (a bloated CLAUDE.md, a skill you never invoke), offload (context you re-paste every session, moved to caveman memory when recall measures cheaper), habit (numbers plus a soft suggestion, never an imperative), load-bearing (config you need, counted in the score and never touched).

caveman learn implement   # hand the plan to Claude Code or Codex

The analyzer never edits your files. learn implement opens your own agent with the plan and the caveman-learn skill, which instructs it to propose each fix as a diff, apply only on your yes, re-measure, and revert anything that did not lower tokens per turn. Caveman never makes your agent dumber to make it cheaper.

Fix land? caveman learn applied <sink_id> records it. Future runs say improved, unchanged, regressed, or need more data. No fake win.

Caveman Proxy

One command wraps your agent and routes provider traffic through a local proxy powered by Caveman Engine. In a pinned 54-run Claude Code benchmark it used 33.2% fewer provider-reported input tokens than direct Claude Code while passing all 18 exact-answer checks. Method, per-case results, and limits. benchmark_counterfactual

No code change, no Caveman backend: the proxy forwards each request to your chosen provider, and recovery copies stay on your disk. Claude Pro/Max OAuth credentials pass through to Anthropic as-is.

Three rules keep it safe:

• CCR first. Original bytes land in a content-addressed store on your disk before any lossy transform ships. The agent pulls them back with caveman_retrieve. Parse problem, store failure, or larger result sends original bytes unchanged.
• Visible declines. Every transform runs only when it measures smaller, and every decline states its reason.
• Labeled evidence. Local results say inferred. verified requires real traffic and eval gates; offline caveman never says it.

What the engine does to a payload — per-type compressors and targets

detect() types each payload, then routes it to a compressor that keeps what answers depend on:

All targets inferred. The code compressor uses tree-sitter (Go, Python, JS/TS) under cgo, with a pure-Go fallback that handles Go only. contextwindow.Pack() additionally fits candidate context into a token budget by BM25 relevance, recency, and error signal, returned in original order so chronology survives.

The same engine powers a set of verbs:

caveman learn                   # scan your real agent history → score + ranked token sinks
caveman learn implement         # fix the findings with your own agent, consent-gated per edit
caveman explore install         # read-only FastContext subagent: finds code as path:line
caveman shrink -- pnpm test     # compress noisy command output, byte-exact recoverable
caveman browse <url>            # local Chrome over a compressed a11y tree
caveman mem remember|recall     # durable memory; `mem recover <handle>` = original bytes
caveman trial -- claude         # A/B a real session, then `trial report`
caveman toon encode|decode      # the TOON re-encoder, standalone
caveman stats                   # what caveman actually did, by content type

The MCP server exposes five tools to any MCP host: caveman_compress, caveman_retrieve, caveman_stats, caveman_toon_encode, caveman_toon_decode.

On browse (needs Chrome): a focused query against a 200-row operations table costs 121 tokens, 129.8× smaller than the Playwright ARIA baseline of 15,704. On a tiny checkout form Caveman is honestly larger (67 → 111 tokens) because it also returns action UIDs and a recovery handle, and the Playwright baseline carries only ARIA text, which favors Playwright. Medians over five pinned Chrome runs, inferred. Full method: browse/BENCHMARK.md.

Pixel mode

The headline trick. Text is priced per token; images are not. A dense wall of text rendered to a PNG costs a fraction as vision input, so the proxy renders big request slabs (minified JSON tool catalogs, long-line logs, old history) into glyph-rendered PNG pages.

caveman wrap --pixel claude

_{Real render, bundled here: 8,622 chars → one 1568×232 PNG, est. 2,597 text → 534 image tokens, inferred.}

On a genuinely dense request (a 63.7k-char minified JSON tool-catalog slab plus a 93k-char long-line log, model claude-fable-5):

55,413 est. text tokens  →  11,402 est. image tokens   ·  −79%  ·  7 PNG pages  ·  inferred

Originals go to CCR first; the agent pulls real bytes back via caveman_retrieve.

[!IMPORTANT] Pixel only pays on dense, long-line content. Sparse code with short lines is honestly not profitable: the PNG carries more overhead than the text it replaces, so the profitability gate declines it and the bytes pass through untouched.

Runs only for models with measured render legibility, claude-fable-5 and gpt-5.6 by default; override with pixel_models config / CAVE_PIXEL_MODELS. Pixel ports pxpipe (MIT); font attribution in the License.

Skills as images

Full circle: the engine now compresses the thing caveman started as. Every fat skill you install re-loads its whole prompt body on every invocation, and you pay that tax forever. caveman convert renders each installed SKILL.md body to PNG pages in place. Frontmatter stays text, so discovery and triggering work exactly as before; the model reads the body as an image.

caveman convert --dry-run        # every installed skill, with the token math, no writes
caveman convert --agent claude   # convert the profitable ones
caveman convert --revert         # byte-identical restore from SKILL.orig.md

Measured on the caveman skill itself: 1,069 → 415 est. tokens, −61%, inferred. Convert only fires when pages beat the text; any failure leaves the skill byte-identical and names the gate that said no. New skills installed through caveman skills install auto-pixel by default (--no-pixel to opt out).

The skill

The original, and still the fastest way to feel caveman. MIT forever. Works in Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, and 30+ other agents.

Type /caveman if your agent does not activate it automatically. Switch with /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra; turn it off w