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

> Learn how to configure Caveman statusline to display your lifetime token savings. Enhance Claude Code's statusline by enabling the savings badge with a simple setup.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-08

---

**The Caveman tool renders a badge in Claude Code’s statusline by executing [`src/hooks/caveman-statusline.sh`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json).

### Claude Configuration Binding

Claude Code’s [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 50–1018) automatically registers the script, but you can verify the path matches your system:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh) on your system:

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

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

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

```bash
export CAVEMAN_STATUSLINE_SAVINGS=0

```

### Force Enable Savings

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

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js) handles the aggregation logic
- **Settings registration**: [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js) manages the script paths

The [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh)** reads this file and appends the savings to the statusline badge.
- Configure Claude’s **[`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.