caveman Documentation

Why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman

97,806 stars Go Go 1 file · ~6,390 tokens #ai#anthropic#caveman#claude#claude-code#llm#meme#prompt-engineering
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy caveman on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name caveman -p 8787:8787 --restart always ghcr.io/juliusbrussee/caveman-proxy:bin-v2.1.0@sha256:da293df3c6929c7b31eba580f7af74da0448e83a55a973cca86e81041877d0bb
Configured Services & Ports
⚙️ caveman-proxy
image: ghcr.io/juliusbrussee/caveman-proxy:bin-v2.1.0@sha256:da293df3c6929c7b31eba580f7af74da0448e83a55a973cca86e81041877d0bb
🔌 Ports: 8787:8787
⚙️ postgres
image: postgres:17-alpine@sha256:b0f9560a2de083e2cc7382e75f808c7381a32852a7ec49117deedb300e552b24
docker-compose.yml
yaml (docker-compose.yml) 
services:
  caveman-proxy:
    image: ghcr.io/juliusbrussee/caveman-proxy:bin-v2.1.0@sha256:da293df3c6929c7b31eba580f7af74da0448e83a55a973cca86e81041877d0bb
    # Alternative to pulling: build from a clone with `docker compose build`.
    build: ..
    ports:
      - "8787:8787"
    # Put configuration in deploy/.env, e.g.
    #   CAVEMAN_AUTH_TOKEN=
    #     This file's only inbound credential, so required for the image's
    #     default 0.0.0.0 listen. Clients send it as x-cave-api-key or
    #     Authorization: Bearer.
    #   CAVEMAN_MODE=record          # record (default) | compress | pixel
    #   CAVEMAN_MIDDLEWARE_MODE=compress  # framework middleware; default follows CAVEMAN_MODE
    #   ANTHROPIC_API_KEY=sk-ant-...  # or OPENAI_API_KEY / GEMINI_API_KEY / AWS_*
    # With the postgres profile (`docker compose --profile postgres up -d`) add:
    #   CAVEMAN_POSTGRES_PASSWORD=
    #   CAVEMAN_MIDDLEWARE_DATABASE_URL=postgres://caveman:@postgres:5432/caveman?sslmode=disable
    #     The middleware store then lives in Postgres instead of SQLite under
    #     /data. sslmode=disable is for this compose network only; any other
    #     database needs sslmode=verify-full.
    env_file:
      - path: .env
        required: false
    environment:
      # No inline default on purpose: an example token in a committed file is a
      # real token on someone's VPC. Compose refuses to start when it is unset.
      CAVEMAN_AUTH_TOKEN: ${CAVEMAN_AUTH_TOKEN:?required - put it in deploy/.env, generate with "openssl rand -hex 32"}
    volumes:
      # SQLite spend store, CCR store, proxy.log and run state live here.
      # A named volume inherits the image's uid 65532 ownership; a bind mount
      # does not — chown the host directory to 65532 first if you use one.
      - caveman-data:/data
    depends_on:
      # Only with the postgres profile; otherwise the proxy starts alone.
      postgres:
        condition: service_healthy
        required: false
    restart: unless-stopped
    # No healthcheck: the image is distroless, so there is no shell or curl to
    # run one inside the container. Probe GET http://localhost:8787/health/ready
    # from the host, or let a real orchestrator do it (see kubernetes.yaml).

  postgres:
    profiles: ["postgres"]
    image: postgres:17-alpine@sha256:b0f9560a2de083e2cc7382e75f808c7381a32852a7ec49117deedb300e552b24
    environment:
      POSTGRES_USER: caveman
      POSTGRES_DB: caveman
      # Empty when unset, and the image then refuses to initialize: no default
      # password ships in this file.
      POSTGRES_PASSWORD: ${CAVEMAN_POSTGRES_PASSWORD:-}
    volumes:
      - caveman-postgres:/var/lib/postgresql/data
    # Not published: only the proxy on this compose network reaches it.
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "caveman", "-d", "caveman"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped

volumes:
  caveman-data:
  caveman-postgres:

File: README.md

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.

bash
npm install @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.

bash
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+):

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

Windows (PowerShell 5.1+):

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

One agent only:

bash
# 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.

bash
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).

bash
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.

Mode What it does Bytes the model sees
default stack (caveman claude) Structural compression routed per content type, plus JSON tool results re-encoded as TOON when measured smaller. Changed, recoverable
--off Counts tokens and cost. Changes nothing. Byte-identical
--pixel Dense text slabs rendered to PNG pages for vision models. Changed, recoverable

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:

Detected type Keeps Target
json keys, structure, error/message subtrees; collapses repetitive arrays 70–90%
log errors, stack traces, first/last lines; drops INFO and progress noise 85–95%
code imports, signatures, types; elides function bodies, syntax stays valid 40–70%
diff file/hunk headers and changed lines; elides repeated context 60–80%
search-result top/bottom hits plus diagnostic/security hits 80–95%
text / HTML headings, opening/closing context, important sections 50–80%

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:

bash
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             # 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.

bash
caveman wrap --pixel claude

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):

text
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.

bash
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 with /caveman off or normal mode.

One install also brings the small tools:

Tool / command What you get
/caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off] Shorter replies at the intensity you choose.
cavecrew-investigator, cavecrew-builder, cavecrew-reviewer Compressed subagent presets for locating, editing, and reviewing code.
/caveman-commit Terse Conventional Commit messages.
/caveman-review One-line, actionable review findings.
/caveman-compress <file> Smaller Markdown memory files, with the original backed up.
/caveman-stats Local session token usage and estimated savings in Claude Code.
/caveman-help One-screen reminder of every mode and command.
investigate-first, lean-build, surgical-patch, safe-refactor, migration, verify-and-stop Work patterns that write less code, so the agent bills fewer tokens. Your agent picks these up on its own when a task fits.
/caveman-setup, /caveman-discover, /caveman-learn, /caveman-manage, /caveman-optimize, /caveman-explore, /caveman-evidence-review Drive the caveman engine and proxy: set it up, find where tokens go, act on what it finds.
Task Normal Caveman Saved
Explain React re-render bug 1180 159 87%
Fix auth middleware token expiry 704 121 83%
Set up PostgreSQL connection pool 2347 380 84%
Explain git rebase vs merge 702 292 58%
Refactor callback to async/await 387 301 22%
Architecture: microservices vs monolith 446 310 30%
Review PR for security issues 678 398 41%
Docker multi-stage build 1042 290 72%
Debug PostgreSQL race condition 1200 232 81%
Implement React error boundary 3454 456 87%
Average 1214 294 65%

[!IMPORTANT]
Honest number warning. The skill only shrinks output tokens. Input and reasoning tokens are untouched, and the skill itself adds ~1–1.5k input tokens per turn. Whole-session savings run smaller than the output number, and on already-terse workloads they can go net-negative. The real win is readability and speed; cost savings are the bonus. When caveman wins, when it loses, and how to measure it yourself: docs/HONEST-NUMBERS.md.

"Normal" above means an unprompted assistant, not a terse one. Some of that 65% is what any "answer concisely" instruction would buy you. benchmarks/run.py now runs a terse control arm alongside the other two, so the next regenerated table splits the two apart; the numbers above predate it.

Wrap any agent

caveman <agent> wraps eight agents natively. Adding one is a data change, a single JSON profile in agents/profiles/, no code.

Agent Vendor How it's wrapped
Claude Code Anthropic env vars
OpenAI Codex CLI OpenAI env vars (API key) · ephemeral CODEX_HOME (ChatGPT login)
Gemini CLI Google env vars
Aider OpenAI/Anthropic env vars
opencode sst inline config via env, your opencode.json untouched
Hermes Agent Nous Research --provider custom + env
OpenClaw OpenClaw ephemeral merged config, your config read-only
Pi pi.dev bundled native extension, your ~/.pi config untouched

Wrap never edits your own config files. Real sessions round-trip in record mode, tested against Hermes v0.18.0, OpenClaw 2026.6.11, and Pi 0.84.2.

Not on the list? Point any provider SDK or framework (Vercel AI SDK, LangChain, LiteLLM, OpenAI Agents, CrewAI, PydanticAI) at the local proxy with a baseURL swap: integrations/recipes/.

[!NOTE]
Subscription logins work. Claude Pro/Max OAuth tokens pass through the proxy as-is, so a wrapped Claude Code on a subscription gets full compression and metering. Codex ChatGPT logins wrap too: an ephemeral CODEX_HOME (your ~/.codex is never written) points a custom provider at the proxy's /chatgpt passthrough, OAuth headers ride through byte-exact. That path is metering-only for now: honest token counts, dollars stay zero because subscription traffic has no per-token price. One exception: a provider pinned inside another agent (e.g. openai-codex inside OpenClaw) is left on its own path with a printed note instead of a broken login.

The default wrap hands the agent the whole loadout: the five caveman MCP tools, the browse MCP server when Chrome resolves, command-output shrink through a real hook on Claude, opencode, Gemini, Hermes, and OpenClaw (Codex gets an honest soft note, its runtime rejects the rewrite: openai/codex#18491), and skills-as-images on new skill installs. Turn pieces off in ~/.caveman-cloud/config.json.

The whole cave

One idea. Agent do more with less.

Repo What it shrinks Status
caveman (you here) What the agent says, and now what it reads live
caveman-browse What the agent sees in the browser live
caveman-agent-sdk What your production agent loads, calls, and spends own repo · in dev
cavegemma The compression baked into weights (Gemma fine-tune) labs
caveman-code The whole agent, end to end frozen
cavemem What the agent remembers, across sessions frozen
cavekit The build loop, spec-driven frozen

Frozen repos still install and work; they are no longer in active development. Their best ideas live on here: cavemem's compressed-memory core ships inside caveman, and caveman-code's lesson became caveman wrap. Make the agent you already use cheaper instead of replacing it.

From `inferred` to `verified`

Caveman make token small. Caveman Cloud make it provable.

Local runtime results report inferred; controlled benchmark results report benchmark_counterfactual. Neither is a provider invoice. Caveman Cloud is where qualifying live evidence can become verified: baseline in record mode, changes behind eval gates, rollback on quality loss, savings from real traffic with signed receipts. Offline caveman never says verified.

Join the waitlist → caveman.so

Privacy

Your agent still talks to the provider you chose. Local compression needs no Caveman account. The caveman CLI sends anonymous usage stats by default: which commands ran, plus token counts through and cut. Never your prompts, code, or file paths. It says so on first run, and one command turns it off forever: caveman telemetry off (or DO_NOT_TRACK=1). Skill and hooks run locally; the proxy forwards provider traffic; CCR stays in a SQLite file on your disk. Exact network, telemetry, and storage boundaries: SECURITY.md.

License

Split license. Skill and adoption surfaces are MIT. Engine-linked runtime is BSL-1.1 source-available, not OSI Open Source before Change Date.

MIT — the skill, Agent SDK and initializer, the CLI, both client SDKs (TS + Python), kit, evals/graders, contracts, provider catalog, the extension shell, and the thin cavemem clients.

BSL-1.1 — Engine, Proxy, Cache Engine, rewriter, Browse, MCP server, shrink, cavemem Go core, and shared Go platform. New Engine-linked runtime modules default to BSL-1.1. Source-available: read it, fork it, self-host it for your own first-party traffic free, production included. Every BSL version auto-converts to Apache-2.0 on the earlier of 2030-06-21 or four years after that version first ships. Third-party hosted, managed, or embedded service use needs commercial license. BSL text and per-directory map ship with source.

engine/pixel embeds pxpipe (MIT) plus glyph atlases derived from Spleen 5×8 (BSD-2-Clause) and GNU Unifont (dual OFL-1.1 / GPLv2-with-font-exception); its NOTICE travels with that source.

"Caveman" and the rock logo are trademarks of Julius Brussee. "Powered by Caveman" is fine when true.

Star this repo

Caveman save you token, save you money. Star cost zero. Fair trade. ⭐

**Docs:** [Technical manual](./docs/README.md) · [Install matrix](./INSTALL.md) · [Honest numbers](./docs/HONEST-NUMBERS.md) · [License](./LICENSE) · [Contributing](./CONTRIBUTING.md) · [Maintainer guide](./CLAUDE.md) · [Issues](https://github.com/JuliusBrussee/caveman/issues)

MIT skill · BSL-1.1 engine — few token. no lie.

File: evals/README.md

Evals

Measures real token compression of caveman skills by running the same
prompts through Claude Code under three conditions and comparing the
generated output token counts.

The three arms

Arm System prompt
__baseline__ none
__terse__ Answer concisely.
<skill> Answer concisely.\n\n{SKILL.md}

The honest delta for any skill is <skill> vs __terse__ — i.e.
how much the skill itself adds on top of a plain "be terse" instruction.
Comparing a skill to the no-system-prompt baseline conflates the skill
with the generic terseness ask, which is what an earlier version of
this harness did and is why its numbers were inflated.

Why this design

  • Real LLM output, not hand-written examples (no circularity).
  • Same Claude Code the skills target — no separate API key.
  • Snapshot committed to git so CI runs are deterministic and free,
    and so any change to the numbers is reviewable as a diff.
  • Control arm isolates the skill's contribution from the generic
    "be terse" effect.

Files

  • prompts/en.txt — fixed list of dev questions, one per line.
  • llm_run.py — runs claude -p --system-prompt … per (prompt, arm),
    captures real LLM output, writes snapshots/results.json along with
    metadata (model, CLI version, generation timestamp).
  • measure.py — reads the snapshot, counts tokens with tiktoken
    o200k_base, prints a markdown table with median / mean / min / max /
    stdev across prompts.
  • snapshots/results.json — committed source of truth, regenerated only
    when SKILL.md files or prompts change.

Refresh the snapshot (requires `claude` CLI logged in)

bash
uv run python evals/llm_run.py

This calls Claude once per prompt × (N skills + 2 control arms). Use
a small model to keep it cheap:

bash
CAVEMAN_EVAL_MODEL=claude-haiku-4-5 uv run python evals/llm_run.py

Read the snapshot (no LLM, no API key, runs in CI)

bash
uv run --with tiktoken python evals/measure.py

Adding a prompt

Append a line to prompts/en.txt, then refresh the snapshot.

Adding a skill

Drop a skills/<name>/SKILL.md, then refresh the snapshot. llm_run.py
picks up every skill directory automatically.

What this does NOT measure

  • Fidelity — does the compressed answer preserve the technical
    claims? A skill that replies k to everything would score −99% and
    "win". A future v2 could add a judge-model rubric.
  • Latency or cost — out of scope. Note that skills add input tokens
    on every call, so output savings are not the full economic picture.
  • Cross-model behavior — only the model used to generate the
    snapshot is measured.
  • Exact Claude tokens — tiktoken o200k_base is OpenAI's BPE and is
    only an approximation of Claude's tokenizer. Ratios between arms are
    meaningful; absolute numbers are approximate.
  • Statistical significance — single run per (prompt, arm) at default
    temperature. The min/max/stdev columns let you eyeball whether a
    number is solid or noisy, but this is not a powered experiment.

File: docs/README.md

Caveman technical documentation

This manual explains the public Caveman repository from installation through
runtime behavior. It covers the files and interfaces that users can inspect in
this repository. Hosted-service implementation details are outside its scope.

Start here

Runtime

Agent-facing tools

Building on Caveman

Package READMEs remain the narrow API references. This manual supplies the
cross-component model and links to those references where details belong.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai Browse ai catalog → #anthropic Browse anthropic catalog → #caveman Browse caveman catalog → #claude Browse claude catalog → #claude-code Browse claude-code catalog → #llm Browse llm catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →