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.

Install · See it · Adoption paths · Caveman Proxy · Payloads · Browse · Pixel · Skill→PNG · Wrap · License

Start small

Install the MIT skill first. It needs no Caveman account, proxy, Go toolchain, or code changes. Your agent and provider stay the same; only the answer style changes.

# macOS · Linux · WSL · Git Bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v1.10.0/install.sh | bash

# Windows · PowerShell 5.1+
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v1.10.0/install.ps1 | iex

The installer needs Node.js 18+, finds supported agents already on your machine, skips the rest, and is safe to rerun. Prefer 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

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 with /caveman off or normal mode. See INSTALL.md for the full 30+ agent matrix, dry run, flags, verification, and uninstall.

One install also brings the small tools:

That is the whole adoption path for shorter answers. Stop there if that is all you need. Add the local Proxy later when you want Caveman to shrink what the agent reads too.

Caveman started as a skill/plugin for Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, and 30+ other agents. Install once; the agent drops filler and answers in tight caveman-speak while keeping code, commands, and errors byte-for-byte exact.

Agent mouth got smaller. Appetite did not. Tool schemas, files, logs, history, and skill bodies still crossed the provider boundary in full, often on every turn. Caveman 2 shrinks that input before the provider call. Caveman Proxy sits under your existing agent; Caveman Engine powers compression and stores every moved byte for exact recovery.

Keep your agent

Caveman works underneath the stack you already use. Adopt only the layer you need.

The skill

The original. MIT, and it stays MIT.

🗣️ 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 concrete fix, fewer words. Broader reduction and quality-equivalence claims stay unpublished until a reproducible run with raw outputs is committed.

No published output-style benchmark result. Run benchmarks/run.py, review paired output quality, and commit raw results before publishing a percentage.

Use the skill by itself, or keep going when input compression becomes worth the extra setup.

Output-token counts measure length only. They do not prove semantic or technical equivalence; raw paired outputs require separate review before any quality claim.

Shorter answers only fixed output. Tool catalogs, MCP results, logs, repeated files, and skill bodies ride upstream again and again. Caveman Proxy catches them before the next model call; Caveman Engine compresses them locally.

Caveman Proxy

One command wraps your agent and routes provider traffic through a local proxy. Caveman Engine powers its compression. In a pinned 54-run Claude Code benchmark, Caveman 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. In local mode, Caveman sends no prompts or outputs to a Caveman backend: the proxy forwards each request to your chosen provider, while CCR recovery copies stay on your disk. Claude Pro/Max OAuth credentials pass through to Anthropic as-is.

Install the CLI

npm install -g @caveman-ai/cli
caveman setup --install   # downloads the signed runtime binaries

setup --install verifies the signed checksum manifest and the SHA-256 of every binary before an atomic install. Prefer building from source? A clone plus scripts/install-local-cli.sh (macOS/Linux) or pwsh -File scripts/install-local-cli.ps1 (Windows) still works — that path needs Go and pnpm. SDK users can point provider base URLs at the local Proxy directly (ANTHROPIC_BASE_URL=http://127.0.0.1:8787/anthropic).

caveman claude                  # full stack (default): S4 compress + TOON best-of + caveman & browse MCP tools + output shrink
caveman wrap --off codex        # byte-safe pass-through metering only
caveman wrap --pixel claude     # lossy text → PNG pixel mode (model-gated)

Subscription logins work — see the note below.

Safety gates stay explicit:

• CCR first. Before a lossy transform goes upstream, original bytes land in CCR, a content-addressed store on your disk. The agent retrieves them through caveman_retrieve or caveman retrieve <handle>. Parse problem, store failure, or larger result sends original bytes unchanged.
• Visible declines. Pixel refuses sparse code. Convert refuses skills when PNG pages do not beat text. TOON runs only when its output measures smaller. Each decline includes its reason.
• Labeled evidence. Local results report inferred: estimates for choosing what to try. verified requires real traffic and eval gates. Offline caveman never reports it.

What the engine does to a payload

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.

Beyond the proxy, the same engine powers a set of verbs:

caveman explore install         # read-only FastContext subagent: finds code as path:line
                                #   cites without burning your solver's context (Claude Code)
caveman shrink -- pnpm test     # compress noisy command output, byte-exact recoverable
caveman browse <url>            # local Chrome driver over a compressed a11y tree
caveman mem remember|recall     # durable memory; `mem recover <handle>` = original bytes
caveman learn                   # scan your real agent history → Cave Score + ranked token sinks
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.

Caveman Browse benchmark

Measured 2026-08-10 across five independent Chrome runs with Chrome 151.0.7922.108, Playwright 1.56.1, and Caveman's offline o200k_base counter. Results are inferred token counts, reported as medians.

Large pages reward query-focused disclosure. Tiny pages can lose because Caveman also returns action UIDs, a recovery handle, and exact accounting. Playwright baseline contains only ARIA text, so comparison favors Playwright.

Captured serializer fixture improved from 380 tokens to 58, an 84.7% reduction. Full delivered payload is 126 tokens after CCR and accounting metadata; four-tool MCP catalog costs 287 tokens. Full method, ranges, fixtures, functional gates, and claim boundary live in browse/BENCHMARK.md.

Pixel mode

The headline trick. A dense wall of text costs a lot of text tokens. Rendered to a PNG for a vision model, the same wall costs image tokens, far fewer for the right content. Pixel mode renders big request slabs (minified JSON tool catalogs, long-line logs, old history) into glyph-rendered PNG pages the model reads as vision input.

<img src="https://github.com/JuliusBrussee/caveman/raw/v2.0.0/docs/assets/pixel-pipeline.svg" alt="a