# How to Use the /caveman-stats Command to See Token Savings in Caveman

> Discover token savings with the /caveman-stats command in Claude Code. Track output tokens, cache reads, and estimate savings to optimize your usage. Learn more!

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

---

**Run `/caveman-stats` inside Claude Code to display your current session's output tokens, cache-read tokens, and estimated savings, or add `--share` for a tweet-ready summary and `--all` for lifetime totals.**

The `/caveman-stats` command is part of the Caveman skill for Claude Code and provides real-time visibility into how much memory compression is saving you in API costs. This slash command parses your session transcripts to calculate token savings and can display both per-session metrics and aggregated lifetime statistics.

## Where the Command Is Defined

The `/caveman-stats` slash command is declared in [[`commands/caveman-stats.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-stats.md)](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-stats.md) and configured in [[`commands/caveman-stats.toml`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-stats.toml)](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-stats.toml). When invoked, it executes the Node script at [[`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js)](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js), which contains the core implementation for parsing sessions, attributing tokens, and formatting output.

## How the Token Savings Calculation Works

The stats hook analyzes your Claude Code session transcript to compute savings based on a benchmark-derived compression ratio.

### Parsing the Session Transcript

The `findRecentSession` function (lines 55-75) searches the `$HOME/.claude` directory for the most recent `.jsonl` transcript if no session file is provided. Then `parseSession` (lines 78-106) walks each line of the transcript, extracting `output_tokens`, `cache_read_input_tokens`, model names, and timestamps for every assistant message.

### Detecting the Current Caveman Mode

The current mode flag is stored in `.caveman-active` inside the Claude config directory. The `readFlag` function imported from [[`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js)](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) reads this flag (line 76) to determine which compression mode is active.

### Per-Mode Token Attribution

Because sessions can switch modes mid-conversation, the hook uses `readModeLog` (lines 55-70) to read the mode transition log (`.caveman-mode-log.jsonl`). The `attributeByMode` function (lines 86-130) matches each message timestamp against this log to produce a `byMode` map of tokens per mode, plus any "unknown" tokens that cannot be safely attributed.

### Estimating Saved Tokens

The benchmark-derived compression ratios are stored in the `COMPRESSION` constant (lines 19-20), currently set to `0.65` for `'full'` mode. The `deriveSavings` function (lines 41-51) applies this ratio to each mode's token total to compute the estimated tokens saved and, if a model price is known, the corresponding USD savings.

## Command-Line Options

The script parses CLI arguments at lines 44-52 to customize the output format and time range.

### --share for Quick Summaries

The `--share` flag prints a single-line, tweet-ready summary via the `formatShare` function (lines 30-41). This outputs a concise string showing tokens saved and estimated cost, perfect for social media sharing.

### --all for Lifetime Statistics

The `--all` flag loads `.caveman-history.jsonl` and aggregates totals across all sessions using `aggregateHistory` (lines 62-84). This shows your cumulative savings since you started using Caveman.

### --since for Time-Windowed Reports

Use `--since <duration>` (e.g., `--since 7d`) to limit aggregation to a specific time window. This filters the history file before running the aggregation, showing only recent activity.

## Formatting and Output

The `formatStats` function (lines 44-100) builds a multi-line report showing:
- Total turns in the session
- Output tokens and cache-read tokens
- Per-mode breakdown when mode changes occurred
- Estimated tokens saved and USD savings

Example output from a standard invocation:

```text
Caveman Stats
──────────────────────────────────
Turns:    27
──────────────────────────────────
Output tokens:         15 200
Cache-read tokens:     3 400
──────────────────────────────────
Est. tokens saved:     9 800
Est. saved (USD):      ~$0.15
──────────────────────────────────

```

## Persisting Statistics Across Sessions

After each successful run, the hook appends a JSON line to `.caveman-history.jsonl` and updates `.caveman-statusline-suffix` (lines 92-108). This allows shells to display a short "saved tokens" indicator in your prompt, providing persistent visibility into your cumulative savings.

## Usage Examples

Run the command inside Claude Code to see current session statistics:

```bash
/caveman-stats

```

Generate a shareable one-liner:

```bash
/caveman-stats --share

```

Output:

```

🪨 Saved 9 800 output tokens (~$0.15) across 27 turns this session — caveman.sh

```

View lifetime totals across all sessions:

```bash
/caveman-stats --all

```

View statistics for the last 7 days only:

```bash
/caveman-stats --since 7d

```

## Summary

- **`/caveman-stats`** displays your current session's token usage and estimated savings using a 0.65 compression ratio defined in [`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js).
- The command parses `.jsonl` transcripts from `$HOME/.claude` and attributes tokens to specific modes using the `.caveman-mode-log.jsonl` file.
- Add **`--share`** for a tweet-ready summary, **`--all`** for lifetime aggregation, or **`--since <duration>`** for time-windowed reports.
- Statistics are persisted to `.caveman-history.jsonl` and a status-line suffix is written to `.caveman-statusline-suffix` for shell integration.

## Frequently Asked Questions

### How does Caveman calculate the token savings percentage?

The `deriveSavings` function in [`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js) uses a hardcoded `COMPRESSION` constant of `0.65` (65%), meaning Caveman estimates you save 65% of output tokens when the full mode is active. This ratio is applied to your total output tokens to calculate the estimated savings.

### Can I see token savings for a specific time period instead of the current session?

Yes. Use the `--since` flag with a duration specification like `7d` for 7 days or `24h` for 24 hours. This filters the `.caveman-history.jsonl` file before aggregation, showing only statistics from that time window rather than the current session or full lifetime.

### Where does Caveman store my historical token usage data?

Historical data is stored in `.caveman-history.jsonl` inside your Claude config directory (`$HOME/.claude`). Each session appends a JSON line containing the session snapshot, which the `--all` flag reads to compute lifetime totals. The hook also updates `.caveman-statusline-suffix` for shell integration.

### Why does the output show "unknown" tokens sometimes?

When the `attributeByMode` function cannot match a message timestamp to a specific mode entry in `.caveman-mode-log.jsonl`, it categorizes those tokens as "unknown." This typically happens if the mode log is missing or if messages occurred outside logged mode transitions. The hook uses the current flag mtime or whole-session heuristics as fallback attribution methods.