Repository: JuliusBrussee/caveman

Stars: 36296

CLAUDE.md

CLAUDE.md — caveman

README is a product artifact

README = product front door. Non-technical people read it to decide if caveman worth install. Treat like UI copy.

Rules for any README change:

- Readable by non-AI-agent users. If you write "SessionStart hook injects system context," invisible to most — translate it.
- Keep Before/After examples first. That the pitch.
- Install table always complete + accurate. One broken install command costs real user.
- What You Get table must sync with actual code. Feature ships or removed → update table.
- Preserve voice. Caveman speak in README on purpose. "Brain still big." "Cost go down forever." "One rock. That it." — intentional brand. Don't normalize.
- Benchmark numbers from real runs in benchmarks/ and evals/. Never invent or round. Re-run if doubt.
- Adding new agent to install table → add detail block in <details> section below.
- Readability check before any README commit: would non-programmer understand + install within 60 seconds?

---

Project overview

Caveman makes AI coding agents respond in compressed caveman-style prose — cuts ~65-75% output tokens, full technical accuracy. Ships as Claude Code plugin, Codex plugin, Gemini CLI extension, agent rule files for Cursor, Windsurf, Cline, Copilot, 40+ others via npx skills.

---

File structure and what owns what

Single source of truth files — edit only these

| File | What it controls |
|------|-----------------|
| skills/caveman/SKILL.md | Caveman behavior: intensity levels, rules, wenyan mode, auto-clarity, persistence. Only file to edit for behavior changes. |
| rules/caveman-activate.md | Always-on auto-activation rule body. CI injects into Cursor, Windsurf, Cline, Copilot rule files. Edit here, not agent-specific copies. |
| skills/caveman-commit/SKILL.md | Caveman commit message behavior. Fully independent skill. |
| skills/caveman-review/SKILL.md | Caveman code review behavior. Fully independent skill. |
| skills/caveman-help/SKILL.md | Quick-reference card. One-shot display, not a persistent mode. |
| caveman-compress/SKILL.md | Compress sub-skill behavior. |

Auto-generated / auto-synced — do not edit directly

Overwritten by CI on push to main when sources change. Edits here lost.

| File | Synced from |
|------|-------------|
| caveman/SKILL.md | skills/caveman/SKILL.md |
| plugins/caveman/skills/caveman/SKILL.md | skills/caveman/SKILL.md |
| .cursor/skills/caveman/SKILL.md | skills/caveman/SKILL.md |
| .windsurf/skills/caveman/SKILL.md | skills/caveman/SKILL.md |
| caveman.skill | ZIP of skills/caveman/ directory |
| .clinerules/caveman.md | rules/caveman-activate.md |
| .github/copilot-instructions.md | rules/caveman-activate.md |
| .cursor/rules/caveman.mdc | rules/caveman-activate.md + Cursor frontmatter |
| .windsurf/rules/caveman.md | rules/caveman-activate.md + Windsurf frontmatter |

---

CI sync workflow

.github/workflows/sync-skill.yml triggers on main push when skills/caveman/SKILL.md or rules/caveman-activate.md changes.

What it does:
1. Copies skills/caveman/SKILL.md to all agent-specific SKILL.md locations
2. Rebuilds caveman.skill as a ZIP of skills/caveman/
3. Rebuilds all agent rule files from rules/caveman-activate.md, prepending agent-specific frontmatter (Cursor needs alwaysApply: true, Windsurf needs trigger: always_on)
4. Commits and pushes with [skip ci] to avoid loops

CI bot commits as github-actions[bot]. After PR merge, wait for workflow before declaring release complete.

---

Hook system (Claude Code)

Three hooks in hooks/ plus a caveman-config.js shared module and a package.json CommonJS marker. Communicate via flag file at $CLAUDE_CONFIG_DIR/.caveman-active (falls back to ~/.claude/.caveman-active).

text

SessionStart hook ──writes "full"──▶ $CLAUDE_CONFIG_DIR/.caveman-active ◀──writes mode── UserPromptSubmit hook
                                                       │
                                                    reads
                                                       ▼
                                              caveman-statusline.sh
                                            [CAVEMAN] / [CAVEMAN:ULTRA] / ...

hooks/package.json pins the directory to {"type": "commonjs"} so the .js hooks resolve as CJS even when an ancestor package.json (e.g. ~/.claude/package.json from another plugin) declares "type": "module". Without this, require() blows up with ReferenceError: require is not defined in ES module scope.

All hooks honor CLAUDE_CONFIG_DIR for non-default Claude Code config locations.

`hooks/caveman-config.js` — shared module

Exports:
- getDefaultMode() — resolves default mode from CAVEMAN_DEFAULT_MODE env var, then $XDG_CONFIG_HOME/caveman/config.json / ~/.config/caveman/config.json / %APPDATA%\caveman\config.json, then 'full'
- safeWriteFlag(flagPath, content) — symlink-safe flag write. Refuses if flag target or its immediate parent is a symlink. Opens with O_NOFOLLOW where supported. Atomic temp + rename. Creates with 0600. Protects against local attackers replacing the predictable flag path with a symlink to clobber files writable by the user. Used by both write hooks. Silent-fails on all filesystem errors.

`hooks/caveman-activate.js` — SessionStart hook

Runs once per Claude Code session start. Three things:
1. Writes the active mode to $CLAUDE_CONFIG_DIR/.caveman-active via safeWriteFlag (creates if missing)
2. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
3. Checks settings.json for statusline config; if missing, appends nudge to offer setup on first interaction

Silent-fails on all filesystem errors — never blocks session start.

`hooks/caveman-mode-tracker.js` — UserPromptSubmit hook

Reads JSON from stdin. Three responsibilities:

1. Slash-command activation. If prompt starts with /caveman, writes mode to flag file via safeWriteFlag:
- /caveman → configured default (see caveman-config.js, defaults to full)
- /caveman lite → lite
- /caveman ultra → ultra
- /caveman wenyan or /caveman wenyan-full → wenyan
- /caveman wenyan-lite → wenyan-lite
- /caveman wenyan-ultra → wenyan-ultra
- /caveman-commit → commit
- /caveman-review → review
- /caveman-compress → compress

2. Natural-language activation/deactivation. Matches phrases like "activate caveman", "turn on caveman mode", "talk like caveman" and writes the configured default mode. Matches "stop caveman", "disable caveman", "normal mode", "deactivate caveman" etc. and deletes the flag file. README promises these triggers, the hook enforces them.

3. Per-turn reinforcement. When flag is set to a non-independent mode (i.e. not commit/review/compress), emits a small hookSpecificOutput JSON reminder so the model keeps caveman style after other plugins inject competing instructions mid-conversation. The full ruleset still comes from SessionStart — this is just an attention anchor.

`hooks/caveman-statusline.sh` — Statusline badge

Reads flag file at $CLAUDE_CONFIG_DIR/.caveman-active. Outputs colored badge string for Claude Code statusline:
- full or empty → [CAVEMAN] (orange)
- anything else → [CAVEMAN:<MODE_UPPERCASED>] (orange)

Configured in settings.json under statusLine.command. PowerShell counterpart at hooks/caveman-statusline.ps1 for Windows.

Hook installation

Plugin install — hooks wired automatically by plugin system.

Standalone install — hooks/install.sh (macOS/Linux) or hooks/install.ps1 (Windows) copies hook files into ~/.claude/hooks/ and patches ~/.claude/settings.json to register SessionStart and UserPromptSubmit hooks plus statusline.

Uninstall — hooks/uninstall.sh / hooks/uninstall.ps1 removes hook files and patches settings.json.

---

Skill system

Skills = Markdown files with YAML frontmatter consumed by Claude Code's skill/plugin system and by npx skills for other agents.

Intensity levels

Defined in skills/caveman/SKILL.md. Six levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Persists until changed or session ends.

Auto-clarity rule

Caveman drops to normal prose for: security warnings, irreversible action confirmations, multi-step sequences where fragment ambiguity risks misread, user confused or repeating question. Resumes after. Defined in skill — preserve in any SKILL.md edit.

caveman-compress

Sub-skill in caveman-compress/SKILL.md. Takes file path, compresses prose to caveman style, writes to original path, saves backup at <filename>.original.md. Validates headings, code blocks, URLs, file paths, commands preserved. Retries up to 2 times on failure with targeted patches only. Requires Python 3.10+.

caveman-commit / caveman-review

Independent skills in skills/caveman-commit/SKILL.md and skills/caveman-review/SKILL.md. Both have own description and name frontmatter so they load independently. caveman-commit: Conventional Commits, ≤50 char subject. caveman-review: one-line comments in L<line>: <severity> <problem>. <fix>. format.

---

Agent distribution

How caveman reaches each agent type:

| Agent | Mechanism | Auto-activates? |
|-------|-----------|----------------|
| Claude Code | Plugin (hooks + skills) or standalone hooks | Yes — SessionStart hook injects rules |
| Codex | Plugin in plugins/caveman/ plus repo .codex/hooks.json and .codex/config.toml | Yes on macOS/Linux — SessionStart hook |
| Gemini CLI | Extension with GEMINI.md context file | Yes — context file loads every session |
| Cursor | .cursor/rules/caveman.mdc with alwaysApply: true | Yes — always-on rule |
| Windsurf | .windsurf/rules/caveman.md with trigger: always_on | Yes — always-on rule |
| Cline | .clinerules/caveman.md (auto-discovered) | Yes — Cline injects all .clinerules files |
| Copilot | .github/copilot-instructions.md + AGENTS.md | Yes — repo-wide instructions |
| Others | npx skills add JuliusBrussee/caveman | No — user must say /caveman each session |

For agents without hook systems, minimal always-on snippet lives in README under "Want it always on?" — keep current with rules/caveman-activate.md.

---

Evals

evals/ has three-arm harness:
- __baseline__ — no system prompt
- __terse__ — Answer concisely.
- <skill> — Answer concisely.\n\n{SKILL.md}

Honest delta = skill vs terse, not skill vs baseline. Baseline comparison conflates skill with generic terseness — that cheating. Harness designed to prevent this.

llm_run.py calls claude -p --system-prompt ... per (prompt, arm), saves to evals/snapshots/results.json. measure.py reads snapshot offline with tiktoken (OpenAI BPE — approximates Claude tokenizer, ratios meaningful, absolute numbers approximate).

Add skill: drop skills/<name>/SKILL.md. Harness auto-discovers. Add prompt: append line to evals/prompts/en.txt.

Snapshots committed to git. CI reads without API calls. Only regenerate when SKILL.md or prompts change.

---

Benchmarks

benchmarks/ runs real prompts through Claude API (not Claude Code CLI), records raw token counts. Results committed as JSON in benchmarks/results/. Benchmark table in README generated from results — update when regenerating.

To reproduce: uv run python benchmarks/run.py (needs ANTHROPIC_API_KEY in .env.local).

---

Key rules for agents working here

- Edit skills/caveman/SKILL.md for behavior changes. Never edit synced copies.
- Edit rules/caveman-activate.md for auto-activation rule changes. Never edit agent-specific rule copies.
- README most important file for user-facing impact. Optimize for non-technical readers. Preserve caveman voice.
- Benchmark and eval numbers must be real. Never fabricate or estimate.
- CI workflow commits back to main after merge. Account for when checking branch state.
- Hook files must silent-fail on all filesystem errors. Never let hook crash block session start.
- Any new flag file write must go through safeWriteFlag() in caveman-config.js. Direct fs.writeFileSync on predictable user-owned paths reopens the symlink-clobber attack surface.
- Hooks must respect CLAUDE_CONFIG_DIR env var, not hardcode ~/.claude. Same for install.sh / install.ps1 / statusline scripts.

README.md

<h1 align="center">caveman</h1>

<p align="center">
<strong>why use many token when few do trick</strong>
</p>

<p align="center">
<a href="#before--after">Before/After</a> •
<a href="#install">Install</a> •
<a href="#intensity-levels">Levels</a> •
<a href="#caveman-skills">Skills</a> •
<a href="#benchmarks">Benchmarks</a> •
<a href="#evals">Evals</a>
</p>

---

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

</td>
<td width="50%">

🪨 Caveman Claude (19 tokens)

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

</td>
</tr>
<tr>
<td>

🗣️ 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."

</td>
<td>

🪨 Caveman Claude

"Bug in auth middleware. Token expiry check use < not <=. Fix:"

</td>
</tr>
</table>

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

</td>
<td width="25%">

#### 🪨 Full

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

</td>
<td width="25%">

#### 🔥 Ultra

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

</td>
<td width="25%">

#### 📜 文言文

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

</td>
</tr>
</table>

Same answer. You pick how many word.

text

┌─────────────────────────────────────┐
│  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

Pick your agent. One command. Done.

| Agent | Install |
|-------|---------|
| Claude Code | claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman |
| Codex | Clone 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 |

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.

<details>
<summary><strong>Claude Code — full details</strong></summary>

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.

bash

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

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

bash

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

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

</details>

<details>
<summary><strong>Codex — full details</strong></summary>

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:

toml

[features]
codex_hooks = true

</details>

<details>
<summary><strong>Gemini CLI — full details</strong></summary>

bash

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

</details>

<details>
<summary><strong>Cursor / Windsurf / Cline / Copilot — full details</strong></summary>

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.

</details>

<details>
<summary><strong>Any other agent (opencode, Roo, Amp, Goose, Kiro, and 40+ more)</strong></summary>

npx skills supports 40+ agents:

bash

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:

text

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 |

</details>

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

text

/caveman:compress CLAUDE.md

text

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.

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.

bash

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

![Star History Chart](https://star-history.com/#JuliusBrussee/caveman&Date)

Also by Julius Brussee

- Cavekit — specification-driven development for Claude Code. Caveman language → specs → parallel builds → working software.
- 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.

Repository: JuliusBrussee/caveman

Stars: 36296

CLAUDE.md Copy Chapter

CLAUDE.md — caveman

README is a product artifact Copy Chapter

Project overview Copy Chapter

File structure and what owns what Copy Chapter

Single source of truth files — edit only these Copy Section

Auto-generated / auto-synced — do not edit directly Copy Section

CI sync workflow Copy Chapter

Hook system (Claude Code) Copy Chapter

hooks/caveman-config.js — shared module hooks/caveman-config.js — shared module')" title="Copy section prompt for LLMs"> Copy Section

hooks/caveman-activate.js — SessionStart hook hooks/caveman-activate.js — SessionStart hook')" title="Copy section prompt for LLMs"> Copy Section

hooks/caveman-mode-tracker.js — UserPromptSubmit hook hooks/caveman-mode-tracker.js — UserPromptSubmit hook')" title="Copy section prompt for LLMs"> Copy Section

hooks/caveman-statusline.sh — Statusline badge hooks/caveman-statusline.sh — Statusline badge')" title="Copy section prompt for LLMs"> Copy Section

Hook installation Copy Section

Skill system Copy Chapter

Intensity levels Copy Section

Auto-clarity rule Copy Section

caveman-compress Copy Section

caveman-commit / caveman-review Copy Section

Agent distribution Copy Chapter

Evals Copy Chapter

Benchmarks Copy Chapter

Key rules for agents working here Copy Chapter

README.md Copy Chapter

Before / After Copy Chapter

🗣️ Normal Claude (69 tokens) Copy Section

🪨 Caveman Claude (19 tokens) Copy Section

🗣️ Normal Claude Copy Section

🪨 Caveman Claude Copy Section

Install Copy Chapter

What You Get Copy Section

macOS / Linux / WSL

Windows (PowerShell)

... and many more

Usage Copy Chapter

Intensity Levels Copy Section

文言文 (Wenyan) Mode Copy Section

Caveman Skills Copy Chapter

caveman-commit Copy Section

caveman-review Copy Section

caveman-help Copy Section

caveman-compress Copy Section

Benchmarks Copy Chapter

Evals Copy Chapter

Run the eval (needs claude CLI)

Read results (no API key, runs offline)

Star This Repo Copy Chapter

Also by Julius Brussee Copy Chapter

License Copy Chapter

CLAUDE.md

README is a product artifact

Project overview

File structure and what owns what

Single source of truth files — edit only these

Auto-generated / auto-synced — do not edit directly

CI sync workflow

Hook system (Claude Code)

`hooks/caveman-config.js` — shared module

`hooks/caveman-activate.js` — SessionStart hook

`hooks/caveman-mode-tracker.js` — UserPromptSubmit hook

`hooks/caveman-statusline.sh` — Statusline badge

Hook installation

Skill system

Intensity levels

Auto-clarity rule

caveman-compress

caveman-commit / caveman-review

Agent distribution

Evals

Benchmarks

Key rules for agents working here

README.md

Before / After

🗣️ Normal Claude (69 tokens)

🪨 Caveman Claude (19 tokens)

🗣️ Normal Claude

🪨 Caveman Claude

Install

What You Get

Usage

Intensity Levels

文言文 (Wenyan) Mode

Caveman Skills

caveman-commit

caveman-review

caveman-help

caveman-compress

Benchmarks

Evals

Star This Repo

Also by Julius Brussee

License