caveman/README.md

caveman

why use many token when few do trick

Before/After • Install • What You Get • Benchmarks • Full install guide

---

A Claude Code skill/plugin (also Codex, Gemini, Cursor, Windsurf, Cline, Copilot, 30+ more) that makes agent talk like caveman — cuts ~75% of output tokens, keeps full technical accuracy. Brain still big. Mouth small.

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.

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

Pick your level of grunt — lite (drop filler), full (default caveman), ultra (telegraphic), or wenyan (classical Chinese, even shorter). One command switch. Cost go down forever.

Install

One line. Detect every agent. Install for each.

# 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

Detects 30+ agents, runs each one's native install, skips what you not have. Safe to re-run.

Manual install, top agents:

Agent	Command
Claude Code	claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman
Codex	npx skills add JuliusBrussee/caveman -a codex
Gemini CLI	gemini extensions install https://github.com/JuliusBrussee/caveman
opencode	npx -y github:JuliusBrussee/caveman -- --only opencode
Cursor	npx skills add JuliusBrussee/caveman -a cursor
Windsurf	npx skills add JuliusBrussee/caveman -a windsurf
Cline	npx skills add JuliusBrussee/caveman -a cline

See INSTALL.md for 25+ more agents (Copilot, Continue, Roo, Augment, Goose, Junie, Trae, Warp, Tabnine, Mistral, Qwen, Devin, Droid, Replit, Antigravity, …) and all installer flags.

Trigger it:

• /caveman (or Codex $caveman)
• "talk like caveman" / "caveman mode" / "less tokens please"
• Stop with: "stop caveman" / "normal mode"

What You Get

Skill	What
/caveman [lite|full|ultra|wenyan]	Compress every reply. Levels stick until session end.
/caveman-commit	Conventional Commit messages, ≤50 char subject. Why over what.
/caveman-review	One-line PR comments: L42: 🔴 bug: user null. Add guard.
/caveman-stats	Real session token usage + lifetime savings + USD. Tweetable line via --share.
/caveman:compress <file>	Rewrite memory file (e.g. CLAUDE.md) into caveman-speak. Cuts ~46% input tokens every session. Code/URLs/paths byte-preserved.
caveman-shrink	MCP middleware. Wraps any MCP server, compresses tool descriptions. npm.
cavecrew-*	Caveman subagents (investigator/builder/reviewer). ~60% fewer tokens than vanilla, main context lasts longer.

Statusline badge — Claude Code shows [CAVEMAN] ⛏ 12.4k (lifetime tokens saved). Updates every /caveman-stats run. Set CAVEMAN_STATUSLINE_SAVINGS=0 to silence.

Auto-activate every session: Claude Code, Codex, Gemini (built-in). Cursor / Windsurf / Cline / Copilot get always-on rule files via --with-init. Other agents trigger with /caveman per session. Full feature matrix in INSTALL.md.

Benchmarks

Real token counts from the Claude API. Average 65% output reduction across 10 prompts (range 22-87%).

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%

Raw data and reproduction script: benchmarks/. Three-arm eval harness (baseline / terse / skill) lives in evals/ — caveman compared against Answer concisely. not against verbose default, so the delta is honest.

caveman-compress receipts (real memory files):

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%

Important

Caveman only affects output tokens — thinking/reasoning tokens untouched. Caveman no make brain smaller. Caveman make mouth smaller. Biggest win is readability and speed, cost savings 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 points on certain benchmarks. Verbose not always better. Sometimes less word = more correct.

How It Work

1. Install drop skill file in agent.
2. Skill tell agent: drop filler, keep substance, use fragments.
3. For Claude Code, hook also write tiny flag file each session — agent see flag, talk caveman from message one. No need say /caveman.
4. Stats command read Claude Code session log, count tokens saved, write number to statusline.
5. Caveman-compress sub-skill rewrite memory files (CLAUDE.md, project notes) so each session start with smaller context. Save tokens forever, not just one reply.

Maintainer detail (hook architecture, file ownership, CI sync) live in CLAUDE.md.

Want It Always On?

For agents without hook system (Cursor, Windsurf, Cline, Copilot, etc.), drop a rule file:

# In your repo root
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/src/rules/caveman-activate.md \
  > .cursor/rules/caveman.mdc   # or .windsurf/rules/, .clinerules/, .github/copilot-instructions.md

Or run install.sh --with-init and we drop them in for you. Full list of rule-file targets in INSTALL.md.

Caveman Ecosystem

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

Repo	What
caveman (you here)	Output compression — why use many token when few do trick
cavemem	Cross-agent memory — why agent forget when agent can remember
cavekit	Spec-driven build loop — why agent guess when agent can know

Compose: cavekit drive build, caveman compress what agent say, cavemem compress what agent remember. One rock. Two rock. Three rock. That it.

Links

• INSTALL.md — full install matrix, all flags, per-agent detail
• CONTRIBUTING.md — how to send patch
• CLAUDE.md — maintainer guide (file ownership, hook architecture, CI)
• docs/ — extra guides (Windows install, etc.)
• Issues — bug, feature, weird behavior

Star This Repo

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

Also by Julius Brussee

• Revu — local-first macOS study app with FSRS spaced repetition. revu.cards

License

MIT — free like mass mammoth on open plain.