# 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 `
` 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`). ``` 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:]` (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 `.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: . .` 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.` - `` — `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//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

caveman

why use many token when few do trick

Stars Last Commit License

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

--- A [Claude Code](https://docs.anthropic.com/en/docs/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](#文言文-wenyan-mode), [terse commits](#caveman-commit), [one-line code reviews](#caveman-review), and a [compression tool](#caveman-compress) 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](https://arxiv.org/abs/2604.00025)) - **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.
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. ```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`](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: ```toml [features] codex_hooks = true ```
Gemini CLI — full details ```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
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](https://github.com/vercel-labs/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: ``` 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-compress `/caveman:compress ` — 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](caveman-compress/README.md) for details. [Security note](./caveman-compress/SECURITY.md): 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](benchmarks/)): | 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"](https://arxiv.org/abs/2604.00025) 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://api.star-history.com/svg?repos=JuliusBrussee/caveman&type=Date)](https://star-history.com/#JuliusBrussee/caveman&Date) ## Also by Julius Brussee - **[Cavekit](https://github.com/JuliusBrussee/cavekit)** — specification-driven development for Claude Code. Caveman language → specs → parallel builds → working software. - **[Revu](https://github.com/JuliusBrussee/revu-swift)** — local-first macOS study app with FSRS spaced repetition, decks, exams, and study guides. [revu.cards](https://revu.cards) ## License MIT — free like mass mammoth on open plain.