How Caveman Mode Reduces Tokens by 65% While Preserving Technical Accuracy in JuliusBrussee/caveman

Caveman mode reduces token usage by up to 65% through prompt-level rule injection that bans articles and filler words, combined with MCP middleware that compresses tool descriptions before they reach the model, while preserving all code, identifiers, and URLs exactly as written.

Caveman mode is a lightweight terse-communication system implemented in the JuliusBrussee/caveman repository that optimizes Claude Code sessions for token efficiency. This open-source toolset minimizes API costs by stripping unnecessary natural language fluff from both user prompts and assistant responses without altering technical content.

The Two-Front Architecture

Caveman mode operates on two distinct fronts to minimize token consumption while guaranteeing technical precision. The system combines prompt-level rule injection via CLI hooks with prose-field compression through MCP middleware. According to the source code in src/hooks/caveman-mode-tracker.js and src/mcp-servers/caveman-shrink/index.js, this dual approach targets both the model's output generation and the input context window.

Prompt-Level Rule Injection

The first front uses a hook-based system that appends strict communication rules to every user message. When you activate the mode with /caveman, the caveman-mode-tracker.js hook writes your selected mode to ~/.claude/.caveman-active and records the transition in .caveman-mode-log.jsonl.

On every subsequent turn, the hook reads this flag and injects specific instructions via the additionalContext field:

{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"CAVEMAN MODE ACTIVE (full). Drop articles/filler/pleasantries/hedging. Fragments OK. Code/commits/security: write normal."}}

This instruction forces the model to rewrite its response generation logic, eliminating articles, hedging, and verbose phrasing while maintaining exact technical terms. The rule explicitly preserves code blocks, identifiers, URLs, file paths, and security-related content in their original form.

MCP Middleware Compression

The second front operates outside the model through caveman-shrink, an MCP middleware defined in src/mcp-servers/caveman-shrink/index.js. This proxy intercepts responses from upstream MCP servers—particularly tools/list, prompts/list, and resources/list endpoints—and compresses description fields before they enter the context window.

The middleware uses the compress() function from src/mcp-servers/caveman-shrink/compress.js to strip articles and filler words from JSON description fields while keeping identifiers intact. For example, a tool description reading "Read a file from disk" becomes "Read file"—reducing token count without changing the technical meaning.

Quantified Token Savings

The repository includes empirical benchmarks for token reduction. The caveman-stats.js file defines a constant COMPRESSION['full'] = 0.65, indicating that full mode reduces output tokens by approximately 65%.

When you run /caveman-stats, the hook parses the Claude Code transcript, attributes each assistant output token to the active mode, and applies the benchmark ratio. The output displays both token and monetary savings:

$ /caveman-stats
🪨 Saved 650 output tokens (~$0.0098) across 1 turns this session — caveman.sh

Implementation Examples

Enabling Caveman Mode

Activate the mode using the CLI command within Claude Code:

# Activate default full mode

/caveman

# Activate specific variants

/caveman lite
/caveman ultra
/caveman wenyan

# Disable the mode

/caveman off

Available modes include full, lite, ultra, wenyan, and off, each applying different compression levels while maintaining the core rule: technical content remains untouched.

Configuring the MCP Proxy

To compress tool catalogs before they reach the model, configure the MCP server to use caveman-shrink as a proxy:

{
  "mcpServers": {
    "fs-shrunk": {
      "command": "npx",
      "args": [
        "caveman-shrink",
        "npx", "@modelcontextprotocol/server-filesystem", "/my/project"
      ]
    }
  }
}

This configuration spawns the upstream filesystem server through the compression middleware, ensuring all tool descriptions are minimized before entering the context.

Viewing Compression Statistics

Track your savings with the stats command:

# Full breakdown

/caveman-stats

# Short format for sharing

/caveman-stats --share

Summary

• Caveman mode reduces Claude Code token usage by injecting strict communication rules that eliminate articles, filler words, and hedging while preserving code and technical identifiers.
• The system uses two mechanisms: prompt-level rule injection via caveman-mode-tracker.js and MCP middleware compression via caveman-shrink/index.js.
• Empirical benchmarks in caveman-stats.js show full mode achieves approximately 65% reduction in output tokens.
• All technical content—including code snippets, URLs, file paths, and security-related text—remains verbatim and unaltered.
• Activation occurs via /caveman commands, with modes persisted to ~/.claude/.caveman-active and transitions logged to .caveman-mode-log.jsonl.

Frequently Asked Questions

How does caveman mode handle technical terms and code snippets?

Caveman mode explicitly preserves all technical content. According to the injection rules in src/hooks/caveman-mode-tracker.js, the instruction string includes the clause "Code/commits/security: write normal," which forces the model to leave code blocks, identifiers, URLs, and file paths completely untouched. The compression algorithm in src/mcp-servers/caveman-shrink/compress.js specifically skips any content that matches technical patterns, ensuring downstream parsing never breaks.

What is the difference between the full, lite, and ultra modes?

The repository supports multiple compression levels: full, lite, ultra, and wenyan. While the analysis focuses on full mode with its 65% token reduction benchmark, each variant applies different rulesets for how aggressively to strip articles and filler words. The mode is written to ~/.claude/.caveman-active and parsed by the hook system, allowing you to tune the verbosity based on your specific context window constraints.

Can I use caveman mode with existing MCP servers?

Yes, through the caveman-shrink middleware. You wrap existing MCP server commands with npx caveman-shrink, which spawns the upstream server and intercepts its responses. As implemented in src/mcp-servers/caveman-shrink/index.js, this proxy automatically compresses description fields in tools/list and other catalog responses before they reach Claude, reducing input tokens without modifying the underlying server.

How accurate is the 65% token savings claim?

The 65% figure comes from the COMPRESSION constant defined in src/hooks/caveman-stats.js (COMPRESSION['full'] = 0.65). This represents an empirical benchmark used to estimate savings when the /caveman-stats command attributes output tokens to the active mode. The actual percentage may vary based on the verbosity of your typical interactions, but the metric provides a reliable baseline for calculating cost savings across sessions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}