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

> Discover how caveman mode in JuliusBrussee/caveman cuts tokens by 65%. Learn about prompt rules and middleware that preserve accuracy while reducing costs.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-07-06

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js) and [`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```json
{"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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
$ /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:

```bash

# 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:

```jsonc
{
  "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:

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js) and MCP middleware compression via [`caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-shrink/index.js).
- **Empirical benchmarks** in [`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.