Optimize Claude Code with Caveman

Install Caveman to compress Claude Code responses by ~65% and save tokens.

Introduction

30 Second Summary

When you're deep in a coding session, the last thing you need is your AI assistant writing a novel for every response. All that filler text wastes time, costs tokens, and buries the actual answer you need.

In this project, you will install and configure Caveman, a Claude Code skill that compresses AI responses by roughly 65%. You will test all four verbosity modes and compress a project memory file to save tokens on every future session.

What You'll Build

A fully configured Claude Code environment where Caveman auto-activates every session and compresses responses while preserving full technical accuracy.

By the end of this project, you'll have:

  • Caveman installed and auto-activating in every Claude Code session.
  • Hands-on experience with all four verbosity levels (lite, full, ultra, wenyan) and an understanding of when to use each.
  • A compressed CLAUDE.md file that saves input tokens on every future session.
  • Secret Mission: Set up Caveman Commit mode and create ultra-brief conventional commit messages.

Are there any prerequisites?

You need an Anthropic account with an active Claude subscription (Pro, Max, Team, or Enterprise) to use Claude Code. You also need a Mac running macOS 13.0 or later.

Install Claude Code and Caveman

Claude Code is a CLI tool that puts Claude directly inside your terminal. It reads your codebase, edits files, and runs commands. Caveman is a skill that plugs into Claude Code and compresses its responses by roughly 65%.

In this step, you will install both tools and confirm they work together. Once Caveman is active, every future Claude Code session starts in compressed mode automatically.

In this step, get ready to:
  • Install Claude Code on your Mac and log in.
  • Install the Caveman skill across your agents.
  • Verify Caveman auto-activates in a new session.
Install Claude Code

Claude Code is Anthropic's AI coding assistant for the terminal. You install it with a single command that downloads the native binary to your Mac.

  • Press Cmd+Space to open Spotlight.
  • Type Terminal and press Enter to open it.
  • Install Claude Code by running this command:
curl -fsSL https://claude.ai/install.sh | bash

What does this command do?

This downloads and runs Anthropic's native installer script. It places the claude binary on your system and sets up auto-updates.

  • After the installer finishes, you should see a success message in your terminal confirming Claude Code is installed.
  • Start your first Claude Code session by running:
claude

On first launch, Claude Code opens a browser window for you to log in. If the browser does not open automatically, press c in the terminal to copy the login URL, then paste it into your browser.

  • Sign in with your Anthropic account (Claude Pro, Max, Team, or Enterprise).
  • Once authenticated, you will see the Claude Code welcome screen in your terminal with session information and available commands.
  • Type exit to close this session. You will start a fresh session after installing Caveman.

Browser not opening?

Press c in the terminal to copy the login URL manually. Paste it into any browser window and complete the sign-in there.

If you see an error about your account type, confirm you have an active Claude Pro, Max, Team, or Enterprise subscription. The free plan does not include Claude Code access.

Help me troubleshoot my Claude Code login

Install the Caveman skill

The Caveman installer requires Node.js version 18 or higher to run. Before installing Caveman, you need to confirm Node is available on your system.

  • Check your Node.js version by running:
node --version

✔️ I see version 18 or higher

Your Node.js version is sufficient. Move on to the Caveman install below.

ⓧ I see a version lower than 18

Your current Node.js is too old for the Caveman installer. Download and install the latest LTS version from the official Node.js website.

  • Visit nodejs.org/en/download and download the macOS installer (.pkg).
  • Run the downloaded .pkg file and follow the prompts to install.
  • Close and reopen Terminal, then run node --version again to confirm you see version 18 or higher.

ⓧ Command not found

Node.js is not installed on your machine. Download and install it from the official website.

  • Visit nodejs.org/en/download and download the macOS installer (.pkg).
  • Run the downloaded .pkg file and follow the prompts to install.
  • Close and reopen Terminal, then run node --version to confirm the install worked.

With Node.js confirmed, you can now install Caveman. The installer script auto-detects which AI coding agents you have installed and adds the Caveman skill to each one.

  • Install Caveman by running this command:
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

What does this command do?

This downloads and runs the Caveman installer from the official GitHub repository. It detects Claude Code on your system and installs the skill so it auto-activates from message one in every session.

  • You should see output confirming that Caveman was installed for Claude Code.

Installer failed or timed out?

Make sure you have an active internet connection. The script downloads files from GitHub.

If you see a permissions error, check that your Terminal has access to create files in your home directory. You do not need sudo for this installer.

Help me fix the Caveman installer

Verify Caveman auto-activates

Caveman writes a flag file for Claude Code so the skill activates automatically at the start of every session. You can confirm this by launching a new session.

  • Start a new Claude Code session by running:
claude
  • Once the session loads, type a simple question like "what is caveman mode?" and press Enter.
  • Look at the response style. If Caveman is active, Claude's response will be noticeably shorter and more direct. No greetings, no filler phrases, no sign-off.

How do I know Caveman is working?

A normal Claude Code response opens with a greeting and uses full sentences with transitions. A Caveman response cuts straight to the technical substance.

If you see a compressed, terse answer without pleasantries, Caveman is active and working.

  • Keep this session open. You will use it in the next step to test different verbosity levels.

Response still looks verbose?

Type /caveman in the session and press Enter to manually activate the skill. Then try your question again.

If manual activation works but auto-activation does not, try exiting and re-running the Caveman installer script. Then start a fresh session.

Help me get Caveman auto-activating

Your tools are installed and Caveman is compressing responses. Next up, you will put all four verbosity levels through their paces to see exactly how much control you have over Claude's output.

Test Caveman Verbosity Levels

You have Caveman installed and auto-activating in Claude Code. Now it is time to experience what that compression actually looks like in practice.

Caveman offers four verbosity levels, each tuned for a different workflow. In this step, you will test every level with the same coding question so you can directly compare how each one changes Claude's communication style.

In this step, get ready to:
  • Test /caveman lite by asking a coding question.
  • Compare /caveman full and /caveman ultra on the same question.
  • Try /caveman wenyan and set full as your working default.
Start a Claude Code session and test lite mode

To compare verbosity levels properly, you need a project folder for Claude Code to work inside. A project context gives Claude something real to reference in its responses.

  • If you still have a Claude Code session open from the last step, exit it by typing exit and pressing Enter.
  • Move to your Desktop by running this command:
cd ~/Desktop
  • Create a project folder and move into it by running these commands:
mkdir caveman-test
cd caveman-test
  • Start a new Claude Code session inside this folder by running:
claude

Claude Code opens and Caveman auto-activates. You should see the Claude Code prompt ready for input.

Why do we need a project folder?

Claude Code is designed to work inside project directories. Starting a session in a dedicated folder means Claude can read, create, and edit files there. This gives you a realistic environment for testing Caveman's compression across different types of responses.

Now you will activate lite mode and ask a coding question to see how Caveman compresses the response.

  • Type the following into your Claude Code session and press Enter:
/caveman lite
  • Now ask Claude a coding question by typing this and pressing Enter:
explain how Python list comprehensions work

Claude responds in lite mode. You should see a noticeably shorter response than what Claude would normally produce. Filler words, greetings, and hedging language are stripped out.

What is lite mode?

Lite mode drops filler words and unnecessary pleasantries while keeping the response mostly natural. It is the gentlest compression level. Responses still feel like complete sentences, just without the padding.

Claude responding normally without compression?

Make sure you typed /caveman lite as a standalone message before asking your question. The slash command must be sent on its own, not combined with the question in the same message.

If Caveman still is not activating, try typing /caveman to trigger the default mode first, then switch to lite.

help me figure out why Caveman isn't compressing Claude's responses

Compare full and ultra modes

You have seen lite mode. Now you will ask the same question under two more verbosity levels so you can see how the compression intensifies.

  • Switch to full mode by typing this into your Claude Code session:
/caveman full
  • Ask the same question again:
explain how Python list comprehensions work

Notice how the response is more compressed than lite. Full mode is the default Caveman level. It cuts deeper into the prose while keeping technical accuracy intact.

  • Now switch to ultra mode by typing:
/caveman ultra
  • Ask the same question one more time:
explain how Python list comprehensions work

Ultra mode produces telegraphic responses. Expect sentence fragments, abbreviated syntax, and maximum information density. This is the most aggressive compression level.

How do these levels compare?

Lite drops filler while keeping natural sentence structure. Full is the balanced default that cuts roughly 65% of output tokens. Ultra goes telegraphic, using fragments and abbreviations for maximum speed.

Use lite when you want readable but efficient answers. Use full for everyday coding work. Use ultra when you just need the raw answer with zero padding.

Responses look the same across levels?

The difference can be subtle on short answers. Try a more complex question like explain how React reconciliation works step by step to see a bigger contrast between levels.

Also confirm each /caveman command was sent as its own message and Claude acknowledged the switch before you asked the question.

help me see the difference between Caveman verbosity levels

Try wenyan and set your working default

The fourth and final verbosity level is wenyan. It compresses responses using classical Chinese linguistic patterns, producing extremely dense output.

  • Switch to wenyan mode by typing:
/caveman wenyan
  • Ask the same coding question:
explain how Python list comprehensions work

You should see an extremely compressed response that uses classical Chinese-inspired brevity. This level is more experimental and best suited for quick lookups where you already understand the topic.

When would I use wenyan?

Wenyan is useful for maximum token savings when you already know the domain and just need a quick reminder. For most coding workflows, full mode gives you the best balance of compression and readability.

  • Switch back to full mode as your working default by typing:
/caveman full

Claude confirms the switch. Full mode is now your active verbosity level for the rest of the project.

Switching modes mid-conversation

You can switch between verbosity levels at any point during a Claude Code session. The new level applies immediately to the next response. You do not need to start a new session to change modes.

You now have hands-on experience with all four Caveman verbosity levels. Next up, you will use Caveman on a real coding task and measure your actual token savings.

Use Caveman on a Real Coding Task

You have tested all four verbosity levels and settled on /caveman full as your working default. Now it is time to put Caveman to work on real coding tasks and measure the results.

In this step, you will ask Claude Code to explain a complex concept, then to debug or refactor code. Both interactions will show how caveman mode strips away filler while preserving every technical detail. You will finish by running /caveman-stats to see exactly how many tokens you saved.

In this step, get ready to:
  • Ask Claude Code to explain a complex concept and observe the compressed response.
  • Ask Claude Code to debug or refactor code and notice the lack of preamble or sign-off.
  • Run /caveman-stats to see session token usage, lifetime savings, and estimated USD impact.
Ask Claude to explain a complex concept

Concept explanations are where verbose AI responses hit hardest. A normal response might spend three paragraphs on context before reaching the substance. Caveman mode delivers the substance immediately.

  • In your Claude Code session (which should still be running in your project folder), type this prompt and press Enter:
explain how React reconciliation works

What should I see?

Claude responds with a compressed explanation. No greeting, no filler phrases like "Great question!" or "I'd be happy to explain." The response jumps straight into the technical content.

You should see short, punchy sentences with key terms preserved exactly. Code examples (if any) remain fully intact. Only the surrounding prose is compressed.

Pick your own topic

You can substitute any moderately complex concept you are curious about. Try "explain Python asyncio event loop" or "explain how Git rebasing works" if those are more relevant to your work.

Ask Claude to debug or refactor code

Debugging and refactoring is where Caveman shines brightest. Normally, Claude wraps every fix in pleasantries and lengthy justifications. In caveman mode, you get the fix and nothing else.

  • Type this prompt into your Claude Code session and press Enter:
refactor this function to be more readable:

def p(d,k):
  r={}
  for i in d:
    if i[k] not in r:
      r[i[k]]=[]
    r[i[k]].append(i)
  return r

What does caveman mode change here?

Without Caveman, Claude might open with "Sure, I'd be happy to help refactor this!" and close with "Let me know if you'd like me to explain any of these changes further!" In caveman mode, both are gone.

You get the refactored code, a brief note on what changed, and nothing else. The signal-to-noise ratio jumps dramatically.

Why does this matter for output tokens?

Caveman only affects output tokens. Thinking and reasoning tokens are untouched. The biggest win is readability and speed, with cost savings as a bonus.

Claude is responding in normal verbose mode?

Caveman auto-activates at the start of each session, but if your session was interrupted or restarted, it may have reset. Type /caveman full to re-enable it, then try your prompt again.

help me figure out why Caveman is not compressing Claude's responses

Run /caveman-stats to measure your savings

You have seen the qualitative difference. Now let's quantify it. The /caveman-stats command reads your Claude Code session logs, counts the tokens saved, and presents a summary.

  • View your token savings report by typing this command in your Claude Code session:
/caveman-stats

What does this report show?

The stats report shows three key pieces of data: your session token usage (how many tokens this session consumed), your lifetime token savings (cumulative savings across all caveman sessions), and an estimated USD impact.

The savings come from output token compression only. Caveman averages a 65% reduction in output tokens across interactions.

You should see a report with session and lifetime statistics. If this is your first session with Caveman, your lifetime savings will match your session savings.

Not seeing any stats?

If the command returns no data, it may mean your session has not generated enough interactions yet. Go back and ask Claude a few more questions with Caveman active, then run /caveman-stats again.

help me get /caveman-stats working in my Claude Code session

You have seen Caveman in action on real tasks and measured the savings. Next up, you will use Caveman to compress your project's CLAUDE.md memory file, saving input tokens on every future session.

Compress Your CLAUDE.md with Caveman

You have seen how Caveman compresses Claude's real-time responses. Now let's apply that same compression to something even more impactful for long-term savings.

Every time you start a Claude Code session, it reads your CLAUDE.md file and loads it into the context window. That file consumes input tokens on every single interaction.

Compressing it into caveman-speak means fewer tokens burned before Claude even starts working on your request.

In this step, get ready to:
  • Create a CLAUDE.md file with project conventions and instructions.
  • Compress it with /caveman:compress to save input tokens.
  • Verify the backup and the compressed output.
Create a CLAUDE.md file with project conventions

A CLAUDE.md file gives Claude Code persistent instructions for your project. It typically contains build commands, coding standards, naming conventions, and architectural decisions.

  • In your text editor, create a new file called CLAUDE.md in the root of your project folder.
  • Paste the following sample project conventions into it:
# Project Conventions

This project is a Python web application built with Flask.

## Build and Run

- Install dependencies: `pip install -r requirements.txt`
- Run the development server: `flask run --debug`
- Run tests: `pytest tests/ -v`

## Coding Standards

- Use type hints on all function signatures.
- Follow PEP 8 for formatting and naming conventions.
- Keep functions under 30 lines. Extract helpers when a function grows beyond this limit.
- Write docstrings for all public functions using Google style format.

## Architecture

- Routes live in `app/routes/` with one file per resource (e.g., `users.py`, `orders.py`).
- Business logic lives in `app/services/` and must not import from `app/routes/`.
- Database models live in `app/models/` using SQLAlchemy declarative base.
- Configuration is loaded from environment variables via `app/config.py`.

## Git Workflow

- Branch naming: `feature/description` or `fix/description`.
- Commit messages follow conventional commits format.
- Always rebase onto main before merging. Never merge commits from main into feature branches.

## Testing

- Every new endpoint needs at least one happy-path test and one error-case test.
- Use fixtures in `tests/conftest.py` for shared setup.
- Mock external API calls. Never hit real endpoints in tests.

What is CLAUDE.md?

Claude Code reads CLAUDE.md at the start of every session and treats it as persistent context. Think of it as a briefing document that tells Claude your project's rules before you even ask your first question.

The more concise and specific your instructions, the more reliably Claude follows them.

  • Save CLAUDE.md.
  • Confirm the file exists by running:
ls CLAUDE.md

You should see CLAUDE.md listed in the output.

Don't see the file?

Make sure you saved the file in the root of your project folder, not inside a subfolder. Run pwd to confirm you are in the correct directory.

help me find where my CLAUDE.md file was saved

Compress the memory file with Caveman

Now that you have a CLAUDE.md full of natural language instructions, Caveman can compress the prose while preserving all technical content. The compress feature only touches natural language files like .md and .txt.

  • In your Claude Code session, run the compress command by typing the following and pressing Enter:
/caveman:compress CLAUDE.md

What does this command do?

The /caveman:compress skill rewrites your CLAUDE.md into caveman-speak. It strips filler words and verbose explanations from the prose while preserving code blocks, inline code, URLs, file paths, commands, technical terms, proper nouns, and version numbers exactly as they were.

Before overwriting, it automatically saves a backup of your original file as CLAUDE.md.original.md. You can always revert if needed.

  • Wait for Claude Code to finish processing. You should see a confirmation message indicating that the file has been compressed and a backup has been saved.

Command not recognized?

Try the alternative trigger: type compress memory file as a regular prompt instead of a slash command. Caveman also responds to natural language triggers.

If neither works, make sure your Caveman skill is still active. Type /caveman to re-activate it, then try the compress command again.

help me get /caveman:compress working in my Claude Code session

Verify the compressed file and backup

The compress command should have produced two files: a compressed CLAUDE.md and a backup of the original at CLAUDE.md.original.md.

  • Confirm the backup exists by running:
ls CLAUDE.md.original.md

You should see CLAUDE.md.original.md listed in the output.

  • Open the compressed CLAUDE.md and compare it to the backup by running:
cat CLAUDE.md
  • Check that all code blocks, inline code references like pip install -r requirements.txt, file paths like app/routes/, and technical terms are preserved exactly.
  • Notice that the prose sections (explanations, descriptions, rationale) have been shortened into terse, direct statements.

How much did it save?

Caveman-compress achieves an average 46% reduction in input tokens across tested memory files. Your results may vary depending on how much prose vs. code your CLAUDE.md contains.

This 46% saving applies every single session, because CLAUDE.md is loaded into the context window at startup. Over hundreds of sessions, those savings compound significantly.

Keep the backup around

The CLAUDE.md.original.md backup is human-readable and makes a great reference if you ever need to update your conventions. Edit the backup, then re-run the compress command to generate a fresh compressed version.

Missing the backup file?

The compress skill should create CLAUDE.md.original.md automatically before overwriting. If you do not see it, the command may not have completed successfully. Re-run /caveman:compress CLAUDE.md and watch for any error messages in the output.

help me figure out why the caveman compress backup file is missing

Your memory file is now optimized for every future session. Next up, the Secret Mission challenges you to put Caveman's commit skills to the test.

Secret mission

Caveman Commits

You've seen how Caveman compresses Claude's responses. Now put it to work on your Git workflow. Use /caveman-commit to generate ultra-brief conventional commit messages that prioritize why over what.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely locally, so there are no ongoing costs. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

  • Claude Code CLI (installed via native installer).
  • Caveman plugin (installed via the installer script).
  • Your project folder on the Desktop (including CLAUDE.md and CLAUDE.md.original.md).

Keep everything running

No action needed. Choose this if you plan to keep using Claude Code with Caveman on future projects.

  • Claude Code stays installed and auto-updates in the background.
  • Caveman continues to auto-activate in every Claude Code session.
  • Your compressed CLAUDE.md stays in place, saving tokens every session.

Pause - I'll come back to this later

Disable Caveman without removing it. This way you can re-enable it later without reinstalling.

  • In any Claude Code session, say "normal mode" to turn off caveman-speak for that session. Caveman stays installed but stops compressing responses until you trigger it again with /caveman.
  • Restore your original memory file by renaming CLAUDE.md.original.md back to CLAUDE.md in your project folder.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow each step below.

  • Uninstall Caveman by running this command in your terminal:
npx -y github:JuliusBrussee/caveman -- --uninstall
  • Remove the Claude Code binary and its data by running:
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
  • Remove Claude Code configuration files by running:
rm -rf ~/.claude
rm -f ~/.claude.json
  • Delete your project folder from the Desktop by running:
rm -rf ~/Desktop/caveman-project
  • If you used Claude Code in other project directories, remove project-specific settings from inside each one by running:
rm -rf .claude
rm -f .mcp.json

Nice Work!

Nice Work!

You now have a fully optimized Claude Code setup with Caveman auto-activating every session. Every future interaction is faster, cheaper, and more direct.

Here's what you learned:

  • Installed Claude Code and the Caveman skill from scratch, with auto-activation configured so caveman-speak kicks in from message one.
  • Tested all four verbosity levels (lite, full, ultra, wenyan) on real coding tasks and saw how each compresses responses while preserving full technical accuracy.
  • Compressed your CLAUDE.md memory file to save ~46% of input tokens every session, and ran /caveman-stats to quantify your lifetime token savings.
  • Secret Mission: Generated ultra-brief conventional commit messages with /caveman-commit, keeping subject lines to 50 characters or fewer.

Ready to quiz yourself?