caveman-mcp

Install caveman-mcp

Why

Every token you send costs money and fills context. Long markdown files — CLAUDE.md, memory files, notes, docs — get read on every session. Caveman compresses them in place, preserving all code and structure, cutting prose by 65%.

Same fix. 75% fewer tokens.

Why MCP

Caveman prompts used to require a file in every project. With MCP:

• Register once — works across all projects, all agents

• No file to sync — no copy-pasting prompts into repos

• Tools included — compress any markdown file directly from the agent

• Any client — Claude Code, Cursor, Windsurf, Cline, or any MCP-compatible host

Install

pip install caveman-mcp

Or run without installing:

uvx caveman-mcp

Connect

Claude Code (global — recommended):

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Or per-project via CLI:

claude mcp add caveman-mcp uvx -- caveman-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_settings.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Cline (MCP settings panel → Add Server):

{
  "command": "uvx",
  "args": ["caveman-mcp"]
}

Note: Claude Code CLI and Claude desktop app both support local (stdio) MCP servers. Claude.ai web app only supports remote (HTTP/SSE) connectors.

Without uvx (local clone):

{
  "command": "/path/to/.venv/bin/python",
  "args": ["-m", "caveman_mcp.server"]
}

Prompts

Once connected, activate caveman speak from any agent with /caveman, "talk like caveman", or "caveman mode". Stop with "stop caveman" or "normal mode".

Intensity levels

Compress Tools

Compress any markdown file in three steps — the agent does the work, caveman-mcp handles the I/O and validation.

compress_prepare(filepath)

Reads the file, returns content + compression instructions. The agent compresses the prose, then calls compress_write.

compress_prepare("CLAUDE.md")
→ { filepath, original_content, instructions }

Refuses: sensitive files (~/.ssh/, .env, credentials), existing backups, non-text formats, files > 500 KB.

compress_write(filepath, compressed_content)

Writes compressed content. Auto-creates a .original.md backup on first call. Returns { valid, errors } — validates that all headings, code blocks, and URLs are intact.

compress_restore(filepath)

Restores from .original.md backup. Call if something goes wrong.

Flow:

compress_prepare("CLAUDE.md")       ← read + get instructions
  → agent compresses prose
compress_write("CLAUDE.md", result) ← write + validate
  → { valid: true, errors: [] }

The result:

CLAUDE.md          ← compressed (65% fewer tokens every session)
CLAUDE.original.md ← full backup (edit this, re-compress anytime)

Auto-compress with Claude Code hook

Compress files automatically whenever Claude reads them — no manual invocation needed.

1. Create the hook script (~/bin/caveman-hook):

#!/usr/bin/env python3
"""PostToolUse hook: compress .md files via caveman MCP when auto mode is on."""
import json, os, sys

flag = os.path.expanduser("~/.claude/caveman-auto")
if not os.path.exists(flag):
    sys.exit(0)

data = json.load(sys.stdin)
filepath = data.get("tool_input", {}).get("file_path", "")

if not filepath.endswith(".md"):
    sys.exit(0)

backup = filepath.replace(".md", ".original.md")
if os.path.exists(backup):
    sys.exit(0)

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": (
            f"caveman-auto is ON. Compress {filepath} now using the three-step workflow: "
            "compress_prepare → compress the prose → compress_write. "
            "Do this silently without announcing it."
        )
    }
}))

chmod +x ~/bin/caveman-hook

2. Create the toggle script (~/bin/caveman-toggle):

#!/usr/bin/env python3
import os

flag = os.path.expanduser("~/.claude/caveman-auto")
if os.path.exists(flag):
    os.remove(flag)
    print("caveman: OFF")
else:
    open(flag, "w").close()
    print("caveman: ON")

chmod +x ~/bin/caveman-toggle

3. Register the hook in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/you/bin/caveman-hook",
            "statusMessage": "caveman check..."
          }
        ]
      }
    ]
  }
}

Toggle: run python3 ~/bin/caveman-toggle to turn auto-compress on or off. To use as a bare command, add ~/bin to PATH via ~/.zprofile (not .zshrc):

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zprofile

Files with an existing .original.md backup are skipped automatically.

Attribution

Fork of JuliusBrussee/caveman — MIT licence, copyright © 2026 Julius Brussee. Original prompt design and caveman concept by Julius Brussee. This fork repackages caveman as a single MCP server with file compression tools.

License

MIT