Caveman

Caveman is a Claude Code plugin that changes how the agent writes, not what it knows. It drops filler, pleasantries, hedging and — at the stronger levels — articles and full sentences, while keeping every technical term, code block, command, and error string exact. Its author measures the reduction at about 65% of output tokens against an unprompted baseline.

• Source: JuliusBrussee/caveman
• Install guide: INSTALL.md
• Docs: docs/README.md

Why it was installed

Output tokens cost several times input tokens on the larger models, and a meaningful share of what an agent writes back is ceremony: "Great, let me…" preambles, restating context the reader already has, narrating each tool call before making it. Caveman removes that at the prompt level, with no proxy and no change to routing. It is the one tool in this set with zero infrastructure.

Installation

Caveman offers a one-line installer (curl … | bash) that touches every AI agent on the machine, and a native Claude Code plugin path. The plugin path was used, deliberately.

claude plugin marketplace add JuliusBrussee/caveman

claude plugin install caveman@caveman

Two reasons over the script:

1. Piping a remote script into a shell runs it unread. The plugin path is first-party Claude Code tooling.
2. The installer "wires Claude Code hooks and statusline" by writing into ~/.claude/settings.json. That file already carries a PreToolUse hook and a PostCompact hook for a read-deduplication scheme. A plugin's hooks live in the plugin manifest and are composed at load time; they do not merge into settings.json. After install, the only changes to that file were an enabledPlugins entry and an extraKnownMarketplaces entry. The hooks block was byte-identical.

Verify:

claude plugin list

❯ caveman@caveman
  Scope: user
  Status: ✔ enabled

Cleaning up the predecessor

An older caveman existed on this machine as a symlink in ~/.claude/skills/ pointing into a third-party skills collection. That upstream removed its copy, leaving the symlink dangling; the skill silently disappeared from the available list. The symlink was deleted before installing the plugin. If a caveman skill ever appears alongside the plugin's, one of them is stale.

What the plugin ships

Considerably more than a persona file:

• Two hooks. SessionStart resolves the session's mode and injects the ruleset as hidden context. UserPromptSubmit tracks mode changes made mid-session.
• Twenty-one skills, including caveman-compress, caveman-review, safe-refactor, surgical-patch, verify-and-stop, and investigate-first.
• Three subagent presets (cavecrew-investigator, cavecrew-builder, cavecrew-reviewer) that return compressed output. These are subagents; the rule on this machine about asking before spawning them still applies.
• An opt-in MCP middleware, caveman-shrink, not enabled here.

Intensity levels

From the plugin's own mode table:

The plugin's own example, one question at three levels:

lite — "Your component re-renders because you create a new object reference each render. 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."

Two rules in the ruleset are worth knowing because they run against intuition. Caveman forbids inventing abbreviations (cfg, impl, req) and forbids arrows (X → Y): the tokenizer splits impl the same as implementation, and → is its own token, so neither saves anything and both cost the reader. It also never drops not, never, no, only, or except — a flipped meaning is worse than any token saved.

Configuring the default

Mode is resolved once per session, in this order, first match wins:

1. CAVEMAN_DEFAULT_MODE environment variable
2. A repo-local .caveman/config.json or .caveman.json, found by walking up from the working directory
3. The user config at ~/.config/caveman/config.json (or $XDG_CONFIG_HOME/caveman/config.json)
4. The built-in default: full

The plugin therefore activates at full in every new session unless told otherwise. This machine sets lite in the user config:

mkdir -p ~/.config/caveman && printf '{\n  "defaultMode": "lite"\n}\n' > ~/.config/caveman/config.json

The config file was chosen over a shell export because it does not depend on which shell launches the hook. Verify the plugin resolves it:

node -e "const c=require('$HOME/.claude/plugins/cache/caveman/caveman/'+require('fs').readdirSync(process.env.HOME+'/.claude/plugins/cache/caveman/caveman')[0]+'/src/hooks/caveman-config.js'); console.log(c.getDefaultMode(process.cwd()))"

Within a session, switch at any time:

/caveman lite
/caveman full
/caveman off

Or say "stop caveman" or "normal mode". A switch lasts for the session; the default applies again on the next one.

Why lite, and the conflict it avoids

This machine also runs the learning and explanatory output-style plugins, which mandate educational commentary and structured insight blocks. Those styles are verbose by design. Caveman at full explicitly bans decorative tables and emoji, and prefers fragments; at ultra it strips conjunctions. Run together, whichever ruleset loads last dominates, unpredictably.

lite cuts the ceremony — the "Sure! I'd be happy to help" openers, the hedging, the tool-call narration — while leaving grammatical prose intact, so the teaching styles still read normally. It is the one level that coexists with them.

Where caveman does not apply

The ruleset carries its own boundaries, and they matter for a content repository:

• Anything persisted outside the chat is normal prose. Code, comments, commit messages, documentation, issue and PR text, memory files. This lesson was written under caveman lite and reads as ordinary English for exactly that reason.
• Auto-clarity. Caveman drops out for security warnings, irreversible-action confirmations, multi-step sequences where fragment order could mislead, and whenever the user asks for clarification. It resumes afterwards.
• The user's language is preserved. Compression applies to style, never to the language written in.

Statusline

The activation hook nudges for a statusline entry so the current mode shows in the status bar. This is cosmetic and was not set up. The /caveman-setup skill handles it if wanted.

Do and do not

Do

• Set the default in ~/.config/caveman/config.json; it survives shell changes.
• Use /caveman off for a session where the output-style commentary is the point.
• Expect commits, docs, and code from a caveman session to read normally — that is the contract, not a lapse.

Do not

• Do not run the curl | bash installer on top of the plugin; it writes hooks into settings.json beside ones already there.
• Do not assume full is a preference someone chose; it is the built-in default and activates on every session until overridden.
• Do not enable caveman-shrink or the cavecrew subagents without the usual subagent conversation.

Troubleshooting