DEV Community

Cover image for Caveman mode for Claude Code: fewer output tokens, same facts
Ahmad Dogar
Ahmad Dogar

Posted on Originally published at mahmadmanzoor.com

Caveman mode for Claude Code: fewer output tokens, same facts

Claude Code is polite. Ask why a component re-renders and you get a paragraph that restates your question, explains the cause, suggests a fix and offers more help. In a terminal, at the end of a long day, I want the fix and the reason. Nothing else.

Caveman is a Claude Code plugin (and a skill for many other agents) that does exactly that. Its tagline is "why many token when few do trick". Under the joke is a careful set of writing rules. This post covers what it is, how to install it, the modes, what its own repository measures, and the cases where I turn it off.

Everything below comes from the plugin files installed on my machine (version 3.1.0) and the public repository. Where I quote a number, it is the repository’s number, and I say so.

JuliusBrussee/caveman: The caveman repository: the skill, the Claude Code plugin, the optional proxy CLI, and the benchmarks behind its numbers. Apache-2.0.

What it actually changes

The core is one skill file. It tells the model to answer first and then give the reason and the next step, to drop greetings, hedging and recaps, and to use short words. Articles like "a" and "the" are optional. Words that carry meaning are not: the rules say never to drop not, never, no, only or except, and to keep numbers and units exact.

The rule I like most is "payload verbatim". Code blocks, commands, file paths, API names and error messages are copied character for character. Only the prose around them gets shorter. The README shows the same React answer three ways:

Bar chart of one React fix written four ways: normal agent 63 tokens, /caveman 20 tokens, /ultracave 14 tokens, /megacave 13 tokens

One answer, four voices. Example and token counts from the caveman README (tiktoken o200k).

normal reply

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.
Enter fullscreen mode Exit fullscreen mode

/caveman reply

New object ref each render, so React re-renders. Wrap the prop in `useMemo`.
Enter fullscreen mode Exit fullscreen mode

The facts are the same: a new reference each render, React sees a change, useMemo fixes it. What is gone is the ceremony. The skill also says caveman is "a voice, not broken grammar". There is no "me think" and no caveman prefix, and if the terse version is not actually shorter, plain wins.

Why fewer output tokens matter

Two boxes: what the agent reads (system prompt, tools, files, logs, conversation), which the skill does not shrink, and what the agent says (prose in replies, code and commands exact), which /caveman shortens; the rules ride along as extra input on every call

The skill works on the second box only.

There are three reasons, and they are not equally strong.

Cost. Output tokens are billed, and on most model price lists they cost several times more per token than input. The skill file puts it simply: every output token is billed and read, so filler costs twice.

Speed. A model writes its answer one token at a time. A shorter answer finishes sooner. In an agent session with many turns, that adds up to less waiting.

Reading. This is the one I feel most. I read every reply in a terminal. An answer that starts with the cause, not with "Great question", saves my attention, which is the scarcer resource.

The important limit: the skill only shortens what the agent says. It does nothing to what the agent reads, which in a coding session is usually much bigger: the system prompt, tool definitions, files, test output and the conversation. The repository’s own Honest Numbers page lists the skill’s input reduction as 0%. For input, the project has a separate, optional proxy CLI, which I cover near the end.

Install it in Claude Code

  1. Add the marketplace and install the plugin

This is the Claude Code route from the README and INSTALL.md. The plugin starts caveman automatically in every session.

   claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman
Enter fullscreen mode Exit fullscreen mode
  1. Or do the same from inside a session

The public README lists the slash-command form too.

   /plugin marketplace add JuliusBrussee/caveman
   /plugin install caveman@caveman
Enter fullscreen mode Exit fullscreen mode
  1. Restart and check the flag file

Hooks are read once at session start. INSTALL.md says the active mode is mirrored in a small flag file.

   cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"
   # expected output: caveman
Enter fullscreen mode Exit fullscreen mode
  1. Update with the full name

The plugin and its marketplace are both called caveman, so the short name fails with "Plugin caveman not found". Use plugin@marketplace.

   claude plugin update caveman@caveman
Enter fullscreen mode Exit fullscreen mode

If you only want the skill, without hooks, npx skills add JuliusBrussee/caveman -g installs it for Claude Code and other agents. Then type /caveman to start it. One version note: my machine runs 3.1.0, while the public README now pins its install scripts to v4.0.1. The plugin commands above are the same in both.

Modes and levels

Three modes: /caveman is the default voice, /ultracave is fragments with each fact once, /megacave is Classical Chinese; old level names lite and full map to caveman, ultra to ultracave, wenyan-* to megacave

Version 3.1 has three modes. Older level names still resolve.

There are three modes. /caveman is the default voice described above. /ultracave (alias /caveman ultra) strips grammar further: fragments, one word when one word is enough, each fact stated once. /megacave (alias /caveman wenyan) answers in Classical Chinese, with technical terms left in their original script; its own skill file says the token savings are small and noisy and must never be claimed.

Older releases talked about levels: lite, full, ultra and wenyan. The 3.1 config code still accepts those names and maps lite and full to caveman, ultra to ultracave, and any wenyan variant to megacave. A mode sticks for the whole session until you change it.

  • /caveman status reports the current mode and changes nothing.
  • /caveman off, "stop caveman" or "normal mode" switches it off.
  • /caveman-help prints the reference card.

You can also change what a new session starts in. The help card lists an environment variable, which wins, and a user config file. Setting the default to manual means sessions start off and /caveman turns it on, which is how I would roll it out to a team that has not asked for it.

terminal

# highest priority
export CAVEMAN_DEFAULT_MODE=ultracave
Enter fullscreen mode Exit fullscreen mode

~/.config/caveman/config.json

{ "defaultMode": "manual" }
Enter fullscreen mode Exit fullscreen mode

How the plugin wires itself in

The plugin is small. Its manifest registers two hooks, and a third script runs when you ask for stats.

SessionStart runs caveman-activate.js, which adds the active mode’s rules to the session; UserPromptSubmit runs caveman-mode-tracker.js, which spots /caveman ultra or off and saves the mode per session; /caveman-stats runs caveman-stats.js, which prints recorded usage from the session log

Two hooks and a stats script. Each Claude Code window keeps its own mode.

Each window keeps its own mode in a file under .caveman-sessions/ in your Claude config folder, so two sessions can run different modes. /caveman-stats reads the session log and prints the tokens actually recorded. It reports savings as unknown, because a session has no measured twin without caveman to compare against. I like that honesty more than a made-up percentage.

The plugin also ships helpers I use more than I expected: /caveman-commit for one-line Conventional Commit messages, /caveman-review for one-line review findings, and /caveman-compress <file> for shrinking memory files like CLAUDE.md while keeping headings, code blocks and paths. The repository reports about 46% smaller files across five fixtures for that last one.

What the numbers say, and what they do not

Output tokens over ten developer questions: no instruction 6,983, Answer concisely 4,334, /caveman 4,119, /ultracave 2,693

The repository’s own eval on claude-opus-5-5. Ten questions, one run, output length only.

The README’s eval asks ten developer questions on claude-opus-5-5. With no instruction, the answers totalled 6,983 output tokens. With "Answer concisely." they totalled 4,334. /caveman gave 4,119 and /ultracave gave 2,693. The repository makes the point itself: new models already know how to be concise, so that one line is the fair baseline. Against it, the Honest Numbers page reports caveman 3% shorter, ultracave 35% and megacave 9% at the median, from ten questions in a single run, measuring length only.

The README also cites outside work: a JetBrains A/B over 86 coding tasks that found 8.5% fewer output tokens and no measurable quality loss, an Adobe Research paper reporting 1.4 to 2.4 times lower cost for caveman-style output across eight models, and an Elastic adaptation with 63.6% fewer response tokens. Those are their numbers, in their setups. The honest summary for plain /caveman on a modern model is: a little shorter than asking for concise answers, and noticeably easier to scan.

When terse output hurts

Caveman has a cost side, and the project documents it better than most tools do.

  • The rules are extra input on every call. The 3.1 README estimates about 1,000 input tokens per call and the current one about 1,160; the Honest Numbers page says the real cost depends on caching and was not measured. In short coding Q&A, one user measured a net loss (issue #145).
  • Per-request billing gets nothing. If your plan charges per request rather than per token, as GitHub Copilot premium requests do, a shorter answer costs the same.
  • Learning needs full sentences. When I am new to a codebase or a library, I want the explanation, not the verdict. Fragments assume you already share the context.
  • Two readings of one fragment. "Migration drop column backup first" can be read two ways. The skill’s own fix is "Back up first. Then run migration: it drops the column." Ambiguity is worth more tokens than it costs.

Cases where caveman writes in full sentences: security warnings, irreversible actions, steps where order matters, a confused user, and anything persisted such as code, commits, docs and PRs

Built-in exceptions. After them, it goes back to terse replies.

To its credit, the skill switches to plain prose by itself for the riskiest cases: security warnings, irreversible actions, step sequences that a fragment could scramble, a user who seems confused, and anything written outside the chat, such as code comments, commits, docs and pull requests. Those exceptions are the reason I trust it enough to leave on.

A note on the proxy

The bigger savings the README advertises come from a separate tool: the @caveman-ai/cli proxy, which compresses what the agent reads, such as logs, JSON and test output. It is a different trade-off. INSTALL.md says that routing Claude Code through it sets ANTHROPIC_BASE_URL in your settings, which makes Claude Code Remote Control unavailable while routing is on, and the README says the CLI sends usage statistics by default (caveman telemetry off or DO_NOT_TRACK=1 turns that off). Read both before you install it. The skill alone runs locally and sends nothing.

How I use it

I keep /caveman on for routine coding sessions, switch to /ultracave for quick yes-or-no checks, and say "normal mode" when I am learning something or need a careful explanation for someone else. If you try it, run the same task with and without it and compare your provider’s usage page. That is the test the project itself recommends, and it is the only number that counts for your workload.


Originally published on my site. More posts and projects at mahmadmanzoor.com.

Top comments (19)

Collapse
 
qisuancloud profile image
Alex Chen •

The fair comparison here is not output tokens alone, but the full session bill: with roughly 1,160 input tokens added per call, short replies can still lose on brief exchanges. That suggests measuring savings per task, not per reply, especially when cached context already dominates the input. For routine fixes the scannability gain alone may justify it, but for debugging an unfamiliar failure I would want the fuller reasoning the terse mode deliberately removes.

Collapse
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Agreed, per task is the fair way to measure it, since the added input can eat the saving on short exchanges. For debugging an unfamiliar failure I'd turn it off too.

Collapse
 
qisuancloud profile image
Alex Chen •

Exactly — the per-task framing is what makes the comparison honest. Per exchange flatters the mode, because a short exchange hides the input overhead; per task you see the whole ledger, input included, and that's where short exchanges go underwater.

The boundary I'd draw on the debugging side is familiarity, not severity. For a failure I've seen before, terse output is fine — I already have the mental model, I just need the diff. For an unfamiliar failure, the reasoning trace and the surrounding context are the debugging material itself, so the mode goes off. The interesting middle case is a failure that's new but small: there I'd want terse output with full error context kept, rather than all-or-nothing.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Familiarity is a better line than severity, I agree. For the new but small case, keeping errors and commands verbatim while trimming the prose is close to how the mode already behaves.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Agreed — familiarity is the cleaner test, because severity alone doesn't tell you what the reader still needs. A severe error I've seen before is mostly a lookup; a small unfamiliar one can still hide the real cause.

One way to make that line operable is to ask whether I've seen this exact error-and-command combination before. If yes, trim the prose and keep the error and command verbatim — that's all I need to act. If no, keep the full context around it, even if the failure looks small, because that context is what lets me diagnose it instead of guessing.

The check I'd use is whether first-attempt fixes get better or worse after trimming, and whether retries go up. If the trimmed version still fixes familiar cases on the first try without extra rounds, the line is in the right place; if retries climb on the unfamiliar ones, we've trimmed too far.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Asking whether I've seen that exact error and command together is a cleaner test than how bad the failure looks. Watching retries after trimming is a good check too, since more retries on the unfamiliar ones would show I trimmed too far.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Exactly — and the retry check gets much sharper if you log it per command instead of in aggregate. I'd record three fields per run: whether that exact error-plus-command pair was seen before, the trim level applied, and whether a retry followed. Then the signal you're describing shows up as a number: retry rate on unfamiliar pairs versus familiar ones at the same trim level. In my own runs, a gap of even 10 to 15 points at the same trim level was enough to tell me the trim was eating the context that mattered, not the fluff. One refinement on the familiarity test itself: "seen together" is worth splitting into an exact pair match versus the same error with a different command. The second case still benefits from keeping the command verbatim, since the error text alone rarely carries the flags and paths the fix depends on.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Splitting the exact pair from the same error with a different command makes sense, since the flags and paths are usually what the fix depends on. Logging it per command is a fair way to turn the trim question into a number.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Exactly — the command is part of the identity, not metadata. Same error text, different flags, and the fix changes completely, so the pair (error signature, exact command) is the right key.

What I'd log per pair: times seen, times trimmed, retries after trim, and whether the retry changed the fix. The trim question then becomes a number: only auto-trim a pair after, say, 3 clean trims with zero extra retries, and any pair that ever needed an untrim keeps its full text for the next 10 occurrences. One refinement: canonicalize the command before keying it — strip timestamps and temp paths, keep flags and real paths — otherwise every run looks like a new pair and the ledger never fills.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Good call on cleaning up the command first. If timestamps and temp paths stay in, every run looks new and the counts never build up.

Thread Thread
 
qisuancloud profile image
Alex Chen • • Edited

Exactly — the cleanup is what makes the key stable. What I strip before hashing the command: timestamps (any date string or epoch), temp paths (/tmp/… and /var/folders/… become the placeholder tmp), PIDs and random suffixes (uuids, hash fragments), and absolute home paths (become the placeholder home). What I keep: the binary, the subcommand, flags in canonical order, and the first line of stderr plus the exit code — those are the parts that actually change the fix.

One guard against over-stripping: after normalizing, check the collision rate. If two commands that needed different fixes collapse into one key, the rule was too aggressive and that token class goes back. The payoff is concrete: before cleanup, the same failing tsc --noEmit run produced 40+ distinct keys in a week; after, it was one key with a count of 40 — and that count is what finally justified fixing the underlying flake instead of re-trimming the output every time.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Checking the collision rate after normalizing is a good guard, since an over-eager rule hides exactly the difference the fix depends on. Going from 40 keys to one key with a count of 40 shows why the cleanup is worth doing.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Agreed on the ratio — an absolute count hides the scale, and 1% is a good starting line, though I would treat it as a guess to calibrate, not a fixed bar. The calibration that matters is what fraction of the merged pairs are actually the same failure mode: I would hand-check a sample of 20 merged buckets after each strip change and record how many were safe merges. If fewer than 18 of 20 are safe, the strip is too aggressive even when the overall rate sits under 1%, because the rate averages away the bad buckets. Two more details I would add. First, log the colliding pairs themselves, not just the count — the pair list is what tells you whether to split a bucket by one distinguishing token, like a flag or a path, instead of loosening the strip globally. Second, run the collision check in CI on the command corpus, not by hand: a strip-rule change that nobody re-checks is the exact way a cache key silently changes and a stale hit slips through.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Hand-checking a sample of merged buckets makes sense, since a low overall rate can still hide one bad bucket. Keeping the colliding pairs themselves is the useful part too, that list shows which token needs to come back.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Exactly — the overall rate is a summary that hides the one bucket where the merge went wrong, so the sample check has to be per bucket, not per run. What I do in practice: after each strip-rule change, pull the 20 largest merged buckets (by distinct command count, not by raw hits) and hand-check each pair in the bucket — if two commands in the same bucket would take a different fix, the strip went too far and that token comes back into the command. The collision-pair log is the audit trail for that decision: each entry records the two commands, the token that was stripped, and whether the merge was judged safe. When a pair is judged unsafe, the token goes on a keep-list, the strip rule is re-run, and the collision check re-runs in CI — so the fix for one bad bucket is verified against every other bucket before it ships, not just the one that was hand-checked.

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

Re-running the collision check in CI after a token goes on the keep-list is the step I'd have skipped, and it's the one that stops a fix for one bucket from quietly breaking another. Ranking buckets by distinct commands instead of raw hits makes sense too.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Thanks, that is exactly the failure mode I was worried about. A keep-list change looks harmless in isolation, because it only adds one token back, but it can silently change which stripped forms still collide, so fixing one bucket can quietly break another. That is why I would not leave the rerun to memory or to a manual step.

In practice I would keep the keep-list as a versioned file in the repo, so every addition or removal is a reviewed diff with a reason attached. The CI job would then read that diff, work out which buckets touch the changed tokens, and rerun the collision check only for those buckets, rather than running the full set every time. Each run would log the colliding pairs it found, together with the keep-list version and the strip rules in force, so a later failure can be traced back to the exact change that introduced it. The full check can still run on a schedule, but the per-change check is what catches the quiet cross-bucket break early.

On ranking, I agree with your point, with one caveat. Raw hits let a single high-frequency command dominate a bucket, so a bucket can look bad simply because one command is used a lot. Distinct commands spread the weight more evenly and make it easier to see when a strip rule is hurting a whole family of commands rather than one repeated case. The problem is comparability: a small bucket will naturally have fewer distinct commands, so its ratio can look either clean or alarming on very little evidence. I would therefore keep collisions divided by total distinct commands as the headline ratio, keep the 1 percent figure as a starting guess rather than a hard pass mark, and only rank buckets that clear a minimum sample size, for example at least 20 distinct commands in the bucket. Buckets below that threshold would be listed separately as too small to rank, and investigated by hand rather than sorted into the main list. That way the ranking shows where the strip rules are doing real damage, without letting a tiny sample jump to the top or hide at the bottom.

Does that threshold feel reasonable to you, or would you set the minimum higher for the noisier buckets?

Thread Thread
 
ahmad_dogar_7d098f5e48f72 profile image
Ahmad Dogar •

20 distinct commands seems like a fair floor to start with. I'd only raise it for the noisier buckets once the small ones show how often they turn out to be real problems.

Thread Thread
 
qisuancloud profile image
Alex Chen •

Agreed — 20 is a floor, not a ceiling, and the noisy bucket is exactly where a fixed floor lies to you. The way I'd make the raise rule concrete: let the small buckets set the calibration first. Review the first 20 distinct commands in the quiet buckets and record the share of collisions that turn out to be real problems. If that share stays under, say, 5%, the floor holds at 20. For a bucket whose sampled collisions show more than a quarter real, raise its floor to 40 and re-sample before trusting any merge there — the cost of 20 extra manual checks is small next to a bad merge silently collapsing two different failure modes into one bucket.

One guard on the sampling itself: don't take the first 20 distinct commands in arrival order. A single incident burst can fill the sample with near-duplicates. Spread the 20 across the window — earliest, middle, latest — so the sample sees the bucket's full shape. And record the per-bucket real-problem rate next to the floor in the same log, so the next person to touch the strip rules can see why the noisy bucket's floor is 40 and the quiet one's is 20, instead of inheriting a magic number.