caveman

why use many token when few do trick

Before/After • Install • Levels • Skills • Benchmarks • Evals

🪨 Caveman Ecosystem  ·  caveman talk less _{(you are here)}  ·  cavemem remember more  ·  cavekit build better

---

A Claude Code skill/plugin and Codex plugin that makes agent talk like caveman — cutting ~75% of output tokens while keeping full technical accuracy. Now with 文言文 mode, terse commits, one-line code reviews, and a compression tool that cuts ~46% of input tokens every session.

Based on the viral observation that caveman-speak dramatically reduces LLM token usage without losing technical substance. So we made it a one-line install.

Before / After

🗣️ Normal Claude (69 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."	🪨 Caveman Claude (19 tokens) "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
🗣️ Normal Claude "Sure! I'd be happy to help you with that. The issue you're experiencing is most likely caused by your authentication middleware not properly validating the token expiry. Let me take a look and suggest a fix."	🪨 Caveman Claude "Bug in auth middleware. Token expiry check use < not <=. Fix:"

Same fix. 75% less word. Brain still big.

Pick your level of grunt:

🪶 Lite "Your component re-renders because you create a new object reference each render. Inline object props fail shallow comparison every time. Wrap it in useMemo."

🪨 Full "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

🔥 Ultra "Inline obj prop → new ref → re-render. useMemo."

📜 文言文 "物出新參照，致重繪。useMemo Wrap之。"

Same answer. You pick how many word.

┌─────────────────────────────────────┐
│  TOKENS SAVED          ████████ 75% │
│  TECHNICAL ACCURACY    ████████ 100%│
│  SPEED INCREASE        ████████ ~3x │
│  VIBES                 ████████ OOG │
└─────────────────────────────────────┘

• Faster response — less token to generate = speed go brrr
• Easier to read — no wall of text, just the answer
• Same accuracy — all technical info kept, only fluff removed (science say so)
• Save money — ~71% less output token = less cost
• Fun — every code review become comedy

Install

One line, every agent on your machine:

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

# Windows (PowerShell)
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

Installer detect every agent on machine (Claude Code, Gemini CLI, Codex, Cursor, Windsurf, Cline, Copilot). Run native install for each. Skip what you not have. Safe to re-run. Pass --only <agent> for one target, --dry-run to preview.

Or pick your agent manually:

Agent	Install
Claude Code	claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman
Codex	Clone repo → Open Codex in repo → /plugins → Search "Caveman" → Install
Gemini CLI	gemini extensions install https://github.com/JuliusBrussee/caveman
Cursor	npx skills add JuliusBrussee/caveman -a cursor
Windsurf	npx skills add JuliusBrussee/caveman -a windsurf
Copilot	npx skills add JuliusBrussee/caveman -a github-copilot
Cline	npx skills add JuliusBrussee/caveman -a cline
Any other	npx skills add JuliusBrussee/caveman

Install once. Use in every session for that install target after that. One rock. That it.

What You Get

Auto-activation is built in for Claude Code, Gemini CLI, and the repo-local Codex setup below. npx skills add installs the skill for other agents, but does not install repo rule/instruction files, so Caveman does not auto-start there unless you add the always-on snippet below.

Feature	Claude Code	Codex	Gemini CLI	Cursor	Windsurf	Cline	Copilot
Caveman mode	Y	Y	Y	Y	Y	Y	Y
Auto-activate every session	Y	Y¹	Y	—²	—²	—²	—²
/caveman command	Y	Y¹	Y	—	—	—	—
Mode switching (lite/full/ultra)	Y	Y¹	Y	Y³	Y³	—	—
Statusline badge	Y⁴	—	—	—	—	—	—
caveman-commit	Y	—	Y	Y	Y	Y	Y
caveman-review	Y	—	Y	Y	Y	Y	Y
caveman-compress	Y	Y	Y	Y	Y	Y	Y
caveman-help	Y	—	Y	Y	Y	Y	Y
caveman-stats	Y	—	—	—	—	—	—
cavecrew (subagents)	Y	—	—	—	—	—	—

Note

Auto-activation works differently per agent: Claude Code uses SessionStart hooks, this repo's Codex dogfood setup uses .codex/hooks.json, Gemini uses context files. Cursor/Windsurf/Cline/Copilot can be made always-on, but npx skills add installs only the skill, not the repo rule/instruction files.

¹ Codex uses $caveman syntax, not /caveman. This repo ships .codex/hooks.json, so caveman auto-starts when you run Codex inside this repo. The installed plugin itself gives you $caveman; copy the same hook into another repo if you want always-on behavior there too. caveman-commit and caveman-review are not in the Codex plugin bundle — use the SKILL.md files directly. ² Add the "Want it always on?" snippet below to those agents' system prompt or rule file if you want session-start activation. ³ Cursor and Windsurf receive the full SKILL.md with all intensity levels. Mode switching works on-demand via the skill; no slash command. ⁴ Available in Claude Code, but plugin install only nudges setup. Standalone install.sh / install.ps1 configures it automatically when no custom statusLine exists.

Claude Code — full details

The plugin install gives you skills + auto-loading hooks. If no custom statusLine is configured, Caveman nudges Claude to offer badge setup on first session.

claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

Standalone hooks (without plugin): If you prefer not to use the plugin system:

# macOS / Linux / WSL
bash <(curl -s https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.sh)

# Windows (PowerShell)
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.ps1 | iex

Or from a local clone: bash hooks/install.sh / powershell -File hooks\install.ps1

Windows manual fallback — if automated install fails (#249, #199, #72), set up plugin-skill activation by hand. Does not install standalone hooks/statusline.

$ClaudeDir = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME ".claude" }
$PluginSkillDir = Join-Path $ClaudeDir ".agents\plugins\caveman\skills\caveman"
$MarketplaceDir = Join-Path $ClaudeDir ".agents\plugins"
$MarketplaceFile = Join-Path $MarketplaceDir "marketplace.json"

# Copy SKILL.md into plugin path
New-Item -ItemType Directory -Path $PluginSkillDir -Force | Out-Null
Copy-Item ".\skills\caveman\SKILL.md" "$PluginSkillDir\SKILL.md" -Force

# Create or update marketplace.json with caveman entry
New-Item -ItemType Directory -Path $MarketplaceDir -Force | Out-Null
if (Test-Path $MarketplaceFile) {
  $marketplace = Get-Content $MarketplaceFile -Raw | ConvertFrom-Json
} else {
  $marketplace = [pscustomobject]@{}
}
if (-not ($marketplace.PSObject.Properties.Name -contains "plugins")) {
  $marketplace | Add-Member -NotePropertyName plugins -NotePropertyValue ([pscustomobject]@{})
}
$plugins = [ordered]@{}
foreach ($p in $marketplace.plugins.PSObject.Properties) { $plugins[$p.Name] = $p.Value }
$plugins["caveman"] = [ordered]@{ name = "caveman"; source = "JuliusBrussee/caveman"; version = "main" }
$marketplace.plugins = [pscustomobject]$plugins
$marketplace | ConvertTo-Json -Depth 10 | Set-Content -Path $MarketplaceFile -Encoding UTF8

Verify: Test-Path "$PluginSkillDir\SKILL.md" (should print True), then restart Claude Code and run /caveman.

Uninstall: bash hooks/uninstall.sh or powershell -File hooks\uninstall.ps1

Statusline badge: Shows [CAVEMAN], [CAVEMAN:ULTRA], etc. in your Claude Code status bar.

• Plugin install: If you do not already have a custom statusLine, Claude should offer to configure it on first session
• Standalone install: Configured automatically by install.sh / install.ps1 unless you already have a custom statusline
• Custom statusline: Installer leaves your existing statusline alone. See hooks/README.md for the merge snippet

Codex — full details

macOS / Linux:

1. Clone repo → Open Codex in the repo directory → /plugins → Search "Caveman" → Install
2. Repo-local auto-start is already wired by .codex/hooks.json + .codex/config.toml

Windows:

1. Enable symlinks first: git config --global core.symlinks true (requires Developer Mode or admin)
2. Clone repo → Open VS Code → Codex Settings → Plugins → find "Caveman" under local marketplace → Install → Reload Window
3. Codex hooks are currently disabled on Windows, so use $caveman to start manually

This repo also ships .codex/hooks.json and enables hooks in .codex/config.toml, so caveman auto-activates while you run Codex inside this repo on macOS/Linux. The installed plugin gives you $caveman; if you want always-on behavior in other repos too, copy the same SessionStart hook there and enable:

[features]
codex_hooks = true

Gemini CLI — full details

gemini extensions install https://github.com/JuliusBrussee/caveman

Update: gemini extensions update caveman · Uninstall: gemini extensions uninstall caveman

Auto-activates via GEMINI.md context file. Also ships custom Gemini commands:

• /caveman — switch intensity level (lite/full/ultra/wenyan)
• /caveman-commit — generate terse commit message
• /caveman-review — one-line code review
• /caveman-stats — real token usage + estimated savings (reads session log)

Cursor / Windsurf / Cline / Copilot — full details

npx skills add installs the skill file only — it does not install the agent's rule/instruction file, so caveman does not auto-start. For always-on, add the "Want it always on?" snippet below to your agent's rules or system prompt.

Agent	Command	Not installed	Mode switching	Always-on location
Cursor	npx skills add JuliusBrussee/caveman -a cursor	.cursor/rules/caveman.mdc	Y	Cursor rules
Windsurf	npx skills add JuliusBrussee/caveman -a windsurf	.windsurf/rules/caveman.md	Y	Windsurf rules
Cline	npx skills add JuliusBrussee/caveman -a cline	.clinerules/caveman.md	—	Cline rules or system prompt
Copilot	npx skills add JuliusBrussee/caveman -a github-copilot	.github/copilot-instructions.md + AGENTS.md	—	Copilot custom instructions

Uninstall: npx skills remove caveman

Copilot works with Chat, Edits, and Coding Agent.

Any other agent (opencode, Roo, Amp, Goose, Kiro, and 40+ more)

npx skills supports 40+ agents:

npx skills add JuliusBrussee/caveman           # auto-detect agent
npx skills add JuliusBrussee/caveman -a amp
npx skills add JuliusBrussee/caveman -a augment
npx skills add JuliusBrussee/caveman -a goose
npx skills add JuliusBrussee/caveman -a kiro-cli
npx skills add JuliusBrussee/caveman -a roo
# ... and many more

Uninstall: npx skills remove caveman

Windows note: npx skills uses symlinks by default. If symlinks fail, add --copy: npx skills add JuliusBrussee/caveman --copy

Important: These agents don't have a hook system, so caveman won't auto-start. Say /caveman or "talk like caveman" to activate each session.

Want it always on? Paste this into your agent's system prompt or rules file — caveman will be active from the first message, every session:

Terse like caveman. Technical substance exact. Only fluff die.
Drop: articles, filler (just/really/basically), pleasantries, hedging.
Fragments OK. Short synonyms. Code unchanged.
Pattern: [thing] [action] [reason]. [next step].
ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift.
Code/commits/PRs: normal. Off: "stop caveman" / "normal mode".

Where to put it:

Agent	File
opencode	.config/opencode/AGENTS.md
Roo	.roo/rules/caveman.md
Amp	your workspace system prompt
Others	your agent's system prompt or rules file

Usage

Trigger with:

• /caveman or Codex $caveman
• "talk like caveman"
• "caveman mode"
• "less tokens please"

Stop with: "stop caveman" or "normal mode"

Intensity Levels

Level	Trigger	What it do
Lite	/caveman lite	Drop filler, keep grammar. Professional but no fluff
Full	/caveman full	Default caveman. Drop articles, fragments, full grunt
Ultra	/caveman ultra	Maximum compression. Telegraphic. Abbreviate everything

文言文 (Wenyan) Mode

Classical Chinese literary compression — same technical accuracy, but in the most token-efficient written language humans ever invented.

Level	Trigger	What it do
Wenyan-Lite	/caveman wenyan-lite	Semi-classical. Grammar intact, filler gone
Wenyan-Full	/caveman wenyan	Full 文言文. Maximum classical terseness
Wenyan-Ultra	/caveman wenyan-ultra	Extreme. Ancient scholar on a budget

Level stick until you change it or session end.

Caveman Skills

caveman-commit

/caveman-commit — terse commit messages. Conventional Commits. ≤50 char subject. Why over what.

caveman-review

/caveman-review — one-line PR comments: L42: 🔴 bug: user null. Add guard. No throat-clearing.

caveman-help

/caveman-help — quick-reference card. All modes, skills, commands, one command away.

caveman-stats

/caveman-stats — real token usage + estimated savings + dollar amount. Reads the Claude Code session JSONL directly so the numbers are not the model's guess. Pricing comes from the model id stamped on each turn; ratio comes from benchmarks/ (only full has measured data so far).

Caveman Stats
──────────────────────────────────
Session:  ...projects/my-app/abc123.jsonl
Turns:    47
──────────────────────────────────
Output tokens:         3,210
Cache-read tokens:     128,400
──────────────────────────────────
Est. without caveman:  9,171
Est. tokens saved:     5,961 (~65%)
Est. saved (USD):      ~$0.089
──────────────────────────────────
Memory compressed:     2 files, ~1,920 tokens saved per session start (approx)
Savings est. from benchmarks/ (mean per-task). Pricing for claude-sonnet-4-7. Actual varies by task.

Lifetime totals — caveman-stats appends a snapshot to ~/.claude/.caveman-history.jsonl on every run:

Command	What
/caveman-stats	This session only
/caveman-stats --all	Everything ever recorded (one row per session, latest snapshot wins)
/caveman-stats --since 7d	Last 7 days (Nh or Nd)
/caveman-stats --share	One-line tweetable summary 🪨

Statusline savings — opt-in. Set CAVEMAN_STATUSLINE_SAVINGS=1 in your shell environment, then your status bar shows [CAVEMAN] ⛏ 12.4k (lifetime tokens saved). Updates every time /caveman-stats runs.

Claude Code only — needs the hook system to read the session transcript.

cavecrew

Caveman-flavored subagent presets for Claude Code. Three drop-ins:

• @cavecrew-investigator — read-only research. Returns file:line references in fragment form. No suggestions.
• @cavecrew-builder — small surgical edits in 1-2 files. Returns a caveman-style diff summary.
• @cavecrew-reviewer — PR review in L<line>: <severity> <problem>. <fix>. form. No praise, no scope creep.

When you delegate work to a subagent, agent-to-agent prose is exactly the spot where caveman's grammar earns the most. All three subagents inherit caveman rules at ultra intensity, so handoffs stay terse without you having to remind them every turn.

Claude Code only — subagents are a Claude Code primitive.

caveman-init (cavepack)

Drop the always-on caveman rule into any repo, for every IDE agent at once. Idempotent.

# In your project root:
node tools/caveman-init.js              # writes rule files for all targets
node tools/caveman-init.js --dry-run    # preview what would change
node tools/caveman-init.js --only cline # one target only

Targets installed (skips any that already contain the caveman sentinel):

• .cursor/rules/caveman.mdc — Cursor frontmatter (alwaysApply: true)
• .windsurf/rules/caveman.md — Windsurf frontmatter (trigger: always_on)
• .clinerules/caveman.md — Cline (auto-discovered)
• .github/copilot-instructions.md — Copilot (appended below existing content)
• AGENTS.md — generic agent context (appended)

Existing rule files are left alone unless --force is passed; appendable targets (Copilot, AGENTS.md) get the caveman block appended below your existing content. To compress an existing CLAUDE.md, use /caveman:compress instead — that's a separate, higher-stakes operation.

caveman-compress

/caveman:compress <filepath> — caveman make Claude speak with fewer tokens. Compress make Claude read fewer tokens.

Your CLAUDE.md loads on every session start. Caveman Compress rewrites memory files into caveman-speak so Claude reads less — without you losing the human-readable original.

/caveman:compress CLAUDE.md

CLAUDE.md          ← compressed (Claude reads this every session — fewer tokens)
CLAUDE.original.md ← human-readable backup (you read and edit this)

File	Original	Compressed	Saved
claude-md-preferences.md	706	285	59.6%
project-notes.md	1145	535	53.3%
claude-md-project.md	1122	636	43.3%
todo-list.md	627	388	38.1%
mixed-with-code.md	888	560	36.9%
Average	898	481	46%

Code blocks, URLs, file paths, commands, headings, dates, version numbers — anything technical passes through untouched. Only prose gets compressed. See the full caveman-compress README for details. Security note: Snyk flags this as High Risk due to subprocess/file patterns — it's a false positive.

caveman-shrink (MCP middleware)

Wrap any MCP server. Cut the prose. Keep the substance.

{
  "mcpServers": {
    "fs-shrunk": {
      "command": "npx",
      "args": [
        "caveman-shrink",
        "npx", "@modelcontextprotocol/server-filesystem", "/path/to/dir"
      ]
    }
  }
}

caveman-shrink is a stdio proxy. It spawns the upstream MCP server, intercepts tools/list / prompts/list / resources/list responses, and runs caveman compression over the description fields (and anything else you list in CAVEMAN_SHRINK_FIELDS). Code, URLs, paths, and identifiers stay byte-for-byte identical — same boundaries as the parent skill.

What it does NOT touch in v1: tool-call response bodies, request bodies, or any non-prose data. See mcp-servers/caveman-shrink/ for full docs.

Benchmarks

Real token counts from the Claude API (reproduce it yourself):

Task	Normal (tokens)	Caveman (tokens)	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%

Range: 22%–87% savings across prompts.

Important

Caveman only affects output tokens — thinking/reasoning tokens are untouched. Caveman no make brain smaller. Caveman make mouth smaller. Biggest win is readability and speed, cost savings are a bonus.

A March 2026 paper "Brevity Constraints Reverse Performance Hierarchies in Language Models" found that constraining large models to brief responses improved accuracy by 26 percentage points on certain benchmarks and completely reversed performance hierarchies. Verbose not always better. Sometimes less word = more correct.

Evals

Caveman not just claim 75%. Caveman prove it.

The evals/ directory has a three-arm eval harness that measures real token compression against a proper control — not just "verbose vs skill" but "terse vs skill". Because comparing caveman to verbose Claude conflate the skill with generic terseness. That cheating. Caveman not cheat.

# Run the eval (needs claude CLI)
uv run python evals/llm_run.py

# Read results (no API key, runs offline)
uv run --with tiktoken python evals/measure.py

Star This Repo

If caveman save you mass token, mass money — leave mass star. ⭐

🪨 The Caveman Ecosystem

Three tools. One philosophy: agent do more with less.

Repo	What	One-liner
caveman (you are here)	Output compression skill	why use many token when few do trick — ~75% fewer output tokens across Claude Code, Cursor, Gemini, Codex
cavemem	Cross-agent persistent memory	why agent forget when agent can remember — compressed SQLite + MCP, local by default
cavekit	Spec-driven autonomous build loop	why agent guess when agent can know — natural language → kits → parallel build → verified

They compose: cavekit orchestrates the build, caveman compresses what the agent says, cavemem compresses what the agent remembers. Install one, some, or all — each stands alone.

Also by Julius Brussee

• Revu — local-first macOS study app with FSRS spaced repetition, decks, exams, and study guides. revu.cards

License

MIT — free like mass mammoth on open plain.