Caveman for beginners: cut AI fluff, compress 75% of tokens, and get more accurate results

Getting started difficulty | About 10 minutes | You’ll learn the full install-and-config workflow for caveman, understand its four compression modes—Lite / Full / Ultra / Wenyan—and squeeze every last token out of AI output.

Project overview

caveman is an AI coding assistant output-compression skill developed by Julius Brussee, with its GitHub repo at JuliusBrussee/caveman.

Its core idea is simple: make the AI’s replies say only what’s useful. While keeping the technical accuracy unchanged, it compresses the output tokens by about 75%. A 2026 study (arxiv:2604.00025) even found that, with concise constraints applied to large models, accuracy improves by 26 percentage points on certain benchmarks—more words don’t necessarily mean better answers.

caveman isn’t just a joke project. It includes four compression strength levels (Lite / Full / Ultra / Wenyan), plus three sub-skills: caveman-commit (ultra-minimal commit messages), caveman-review (single-line code review), and caveman-compress (memory-file compression). It supports 40+ AI coding assistants such as Claude Code, Codex, Cursor, Windsurf, Cline, Copilot, Gemini CLI, and more.

Target audience

You use AI coding assistants every day, but you often run into: replies that are too wordy, key points that don’t stand out, and you end up having to extract the real value yourself after reading everything. Faster and cheaper is your top priority—you don’t want to waste tokens and time on pointless pleasantries.

Core dependencies and environment

Complete project structure

my-project/
├── CLAUDE.md                    # Written after installing caveman; always active (Claude Code)
├── .caveman/                    # State marker directory (auto-generated)
│   └── .caveman-active          # Current mode: full / lite / ultra / wenyan
├── .cursor/rules/caveman.mdc    # Cursor always-on rule (auto-generated)
├── .windsurf/rules/caveman.md   # Windsurf always-on rule (auto-generated)
├── .clinerules/caveman.md      # Cline rule (auto-generated)
└── .github/copilot-instructions.md  # Copilot rule (auto-generated)

Step-by-step

Step 1 — Install caveman

caveman supports 40+ AI coding assistants. Pick the command for your platform:

Claude Code (recommended)

# Option 1: Plugin marketplace (simplest)
claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

# Option 2: Script install (when you don’t 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

Codex (VS Code + Codex)

# macOS / Linux
# 1. Clone the repo → open it in Codex → /plugins → search "Caveman" → Install

# Windows (requires enabling symbolic links first)
git config --global core.symlinks true
# Then the same as above: clone → VS Code → Codex Settings → Plugins → install Caveman

Gemini CLI

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

Cursor / Windsurf / Cline / Copilot

npx skills add JuliusBrussee/caveman -a cursor
npx skills add JuliusBrussee/caveman -a windsurf
npx skills add JuliusBrussee/caveman -a cline
npx skills add JuliusBrussee/caveman -a github-copilot

Other Agents (opencode / Roo / Goose / Kiro, etc.—40+ total)

npx skills add JuliusBrussee/caveman    # Auto-detect
# Or specify explicitly
npx skills add JuliusBrussee/caveman -a opencode
npx skills add JuliusBrussee/caveman -a roo

Step 2 — Activate caveman mode

After installing, in any conversation, enter one of the following commands to activate:

/caveman          # Default: Full mode
$caveman          # Codex uses $ instead of /

Or trigger it by speaking directly:

talk like caveman
caveman mode
less tokens please

Step 3 — Choose a compression tier

caveman has four compression strength levels. Switch using these commands:

Compared on the same React problem:

🗣️ Normal reply (69 tokens):
"Your React component re-renders because you are 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."

🪶 Lite (39 tokens):
"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 (19 tokens):
"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

🔥 Ultra (15 tokens):
"Inline obj prop → new ref → re-render. useMemo."

📜 Wenyan (11 tokens):
"物出新參照，致重繪。useMemo Wrap之。"

To exit caveman mode:

stop caveman
normal mode

Step 4 — caveman-commit: ultra-minimal commit messages

caveman-commit is a sub-skill specifically for generating commit messages. It follows Conventional Commits, and the subject never exceeds 50 characters:

/caveman-commit

Example outputs:

# Regular Claude commit (too long):
"Added user authentication functionality including JWT token generation and validation,
password hashing with bcrypt, and session management middleware. This improves security
by implementing proper authentication flows."

# caveman-commit result:
"feat(auth): JWT + bcrypt login, session middleware"

Subject format: type(scope): subject—always under 50 characters, with why over what.

Step 5 — caveman-review: single-line code review

caveman-review performs a single-line review of a PR or code snippet. Format is fixed and it doesn’t waste words:

/caveman-review

Paste your diff or code, and it outputs:

L42: 🔴 bug: user null. Add guard.
L58: 🟡 perf: N+1 query. Prefetch in ORM.
L71: 🟢 nit: unused import. Remove.

You no longer need to read a long paragraph of "I think this could be improved" in PR comments— it directly tells you what’s wrong on which line and how to fix it.

Format: L<line-number>: <🔴🟡🟢> <issue-type>: <description>. <suggested-fix>.

Step 6 — caveman-compress: compress project memory files

This is one of caveman’s most practical sub-skills. Your CLAUDE.md is read by the AI every session. If it contains piles of human-friendly but lengthy explanations, you waste tokens re-reading them each time. caveman-compress compresses these memory files into an AI-efficient format, while keeping the original backup for you to edit.

/caveman:compress CLAUDE.md

After running:

CLAUDE.md          ← compressed version (Claude reads this every time)
CLAUDE.original.md ← original backup (you edit this; compression is one-way)

Observed compression results:

Step 7 — Always-On configuration

After installing Claude Code / Gemini CLI, it’s automatically always-on—no extra setup required.

For Cursor / Windsurf / Copilot, etc., using npx skills add requires manually adding one snippet so it stays active. Put your preferred strengths into the Agent’s rule file:

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.
Code/commits/PRs: normal. Off: "stop caveman" / "normal mode".

Where to place each Agent’s file:

Step 8 — Uninstall / restore defaults

# Uninstall Claude Code plugin
claude plugin uninstall caveman

# Uninstall standalone hooks
bash hooks/uninstall.sh           # macOS / Linux
powershell -File hooks\uninstall.ps1  # Windows

# Uninstall npx skills
npx skills remove caveman

# Uninstall Gemini CLI
gemini extensions uninstall caveman

After uninstalling, the .caveman/ state directory and rule files need to be cleaned up manually (if needed).

Troubleshooting FAQ

1. The plugin is installed, but caveman doesn’t auto-activate

Claude Code uses a SessionStart hook for auto-activation. Check that the hook was written correctly:

# Check whether ~/.claude/settings.json includes the SessionStart hook
cat ~/.claude/settings.json | grep -i "SessionStart"

# Or reinstall once
claude plugin uninstall caveman
claude plugin install caveman@caveman

2. Cursor / Windsurf always-on doesn’t work

npx skills add won’t automatically write an always-on rule. Manually add the step-7 snippet to the corresponding rule file. Save it, then reload the Agent.

3. Wenyan mode outputs pure gibberish or question marks

Confirm that both your terminal and editor support UTF-8. On Windows, PowerShell’s default encoding may cause issues:

chcp 65001
$env:LESSCHARSET=utf-8

In VS Code, confirm the character encoding in the status bar is set to UTF-8.

4. caveman-compress compresses code blocks too

It can’t happen—code blocks, URLs, file paths, and commands are skip items and don’t participate in compression. If you see anything abnormal, it’s usually a file-format issue (for example, missing a code block marker like ```). You can manually compare and restore from CLAUDE.original.md.

5. /caveman command has no response

Another skill might be intercepting the slash command. In Claude Code, try triggering it by direct speech: "talk like caveman". If it still doesn’t work, check whether there’s a conflicting skill with the same name.

6. When multiple Agents coexist, caveman fails in one of them

caveman’s configuration files are independent per Agent and don’t affect each other. If it doesn’t work in a specific Agent, check whether that Agent’s rule directory contains any caveman-related files.

Further reading / advanced directions

1. caveman’s three-arm evaluation: how to keep the data honest

Most "compression technique" evaluations compare skill replies vs normal replies—which is unfair, because terseness (conciseness) itself already improves quality. caveman uses a three-arm evaluation: _baseline_ (no system prompt), _terse_ (only "Answer concisely"), and <skill> (caveman’s full rules). The real savings are the difference between skill and terse, not skill and baseline. This methodology is worth borrowing for evaluating any AI assistant.

2. Interpreting real benchmark data

In practice across 10 tasks, average output tokens drop from 1214 to 294—saving 65%. The range goes from 22% (git rebase vs merge; the explanation itself is long) up to 87% (React error boundaries; normal replies are extremely over-expanded). The easier the task is to over-explain, the more caveman saves.

3. Cavekit: a spec-driven development toolchain by the same author

JuliusBrussee/cavekit is a companion project: write specifications in the caveman language → build in parallel with Claude → produce usable software. If you use caveman to optimize output efficiency, cavekit can do something similar on the input side as well.

4. Custom compression tiers

All tier rules are defined in skills/caveman/SKILL.md. You can copy it, then modify the abbreviation dictionary, decide whether to keep the dictionary, or tweak the causality-symbol rules to create your own tiers. For example, add team-specific terminology abbreviations, or specify that certain technical terms must not be replaced.

5. Cross-language applicability of Wenyan compression

The principle of Wenyan mode is: the most concise written language in human history + extremely low character-token density. On English corpora, wenyan-full can still compress about 40–60% because the classical Chinese syntax patterns—"subject omission + verb-object inversion"—remain effective within a single-language context. It’s a good fit when you need extreme compression and are willing to adapt to special syntax patterns.