How to Configure Caveman’s Statusline to Display Lifetime Token Savings

The Caveman tool renders a badge in Claude Code’s statusline by executing src/hooks/caveman-statusline.sh, which reads the .caveman-statusline-suffix file generated by caveman-stats to display your lifetime token savings.

Caveman is an open-source utility by JuliusBrussee/caveman that tracks token usage across Claude Code sessions. By configuring the statusline integration, you can monitor your cumulative savings directly in the Claude interface without interrupting your workflow.

How the Statusline Integration Works

The statusline badge relies on a two-stage pipeline that aggregates session data and renders it through a shell script.

Stats Aggregation via caveman-stats.js

When you run caveman stats, the tool aggregates per-session token usage and writes a pre-rendered suffix string to .caveman-statusline-suffix in your Claude configuration directory. According to the source code in src/hooks/caveman-stats.js (lines 508–515), this logic formats the lifetime savings as a human-readable string like ⛏ 12.4k.

The Statusline Shell Script

The src/hooks/caveman-statusline.sh script (lines 37–50) checks for the existence of the suffix file and appends its contents to the Caveman badge. If the file is missing or empty, the script displays the base badge without savings data. The script header (lines 5–7) documents the expected usage for Claude’s settings.json.

Claude Configuration Binding

Claude Code’s settings.json must invoke the script via the statusLine property. When properly wired, the script executes on every statusline refresh, reading the latest suffix file to update the display in real time.

Step-by-Step Configuration

Follow these steps to enable lifetime token savings in your statusline.

1. Install the Statusline Hook

Ensure Caveman is installed and the statusline script is executable. The installation process in bin/install.js (lines 50–1018) automatically registers the script, but you can verify the path matches your system:

ls -la ~/.caveman/hooks/caveman-statusline.sh

2. Configure Claude’s settings.json

Add the statusline command to your Claude configuration file. Replace the path with the actual location of caveman-statusline.sh on your system:

{
  "statusLine": {
    "type": "command",
    "command": "bash /home/you/.caveman/hooks/caveman-statusline.sh"
  }
}

3. Generate the Savings Suffix

Run the stats command to create the .caveman-statusline-suffix file. Caveman updates this automatically on every caveman stats invocation:

caveman stats

This writes the lifetime savings data to your Claude config directory.

4. Verify the Display

Check that the suffix file contains valid data:

cat "$HOME/.claude/.caveman-statusline-suffix"

Expected output resembles ⛏ 12.4k. If empty, rerun caveman stats after completing a coding session.

Customizing the Savings Display

The savings suffix is enabled by default, but you can control it via environment variables.

Disable Lifetime Savings

Set CAVEMAN_STATUSLINE_SAVINGS to 0 to hide the token count:

export CAVEMAN_STATUSLINE_SAVINGS=0

Force Enable Savings

To explicitly ensure the savings appear (overriding any local defaults), set the variable to 1:

export CAVEMAN_STATUSLINE_SAVINGS=1

Add either export to your ~/.bashrc or ~/.zshrc to persist the setting across sessions.

Troubleshooting File Paths

If the statusline shows [CAVEMAN] without the savings icon, verify these locations:

• Suffix file: $HOME/.claude/.caveman-statusline-suffix must exist and be readable
• Stats module: src/hooks/caveman-stats.js handles the aggregation logic
• Settings registration: bin/lib/settings.js manages the script paths

The bin/install.js script automates the wiring between these components, but manual verification ensures your specific Claude Code configuration directory is correctly targeted.

Summary

• Caveman tracks token usage across Claude Code sessions and calculates lifetime savings.
• The caveman-stats command writes data to .caveman-statusline-suffix in your Claude config directory.
• caveman-statusline.sh reads this file and appends the savings to the statusline badge.
• Configure Claude’s settings.json to execute the statusline script on every refresh.
• Control the display using the CAVEMAN_STATUSLINE_SAVINGS environment variable.

Frequently Asked Questions

Why is my statusline showing only the base badge without token savings?

The .caveman-statusline-suffix file is likely missing or empty. Run caveman stats to generate the file, or check that the CAVEMAN_STATUSLINE_SAVINGS environment variable is not set to 0. The script in src/hooks/caveman-statusline.sh skips the suffix when the file is absent or when the environment variable disables it.

How often does the lifetime token count update?

The count updates every time you execute caveman stats. Caveman does not automatically update the statusline in real-time; it writes the suffix file only when the stats command runs, which the statusline script then reads on its next execution cycle.

Can I customize the format of the savings display?

The format is hardcoded in src/hooks/caveman-stats.js (lines 508–515) to use a pickaxe emoji (⛏) followed by a human-readable number (e.g., 12.4k). To change the format, you would need to modify the source code and reinstall the tool.

Where does Caveman store the lifetime token data?

While the statusline reads from .caveman-statusline-suffix in the Claude config directory, the actual aggregation logic processes per-session data stored by Caveman’s internal tracking system. The caveman-stats command references this data to calculate the cumulative savings figure.

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