# How to Track Token Savings with the `/caveman-stats` Command

> Learn how to track token savings with the /caveman-stats command. This tool analyzes Claude Code transcripts to estimate savings using compression ratios and flexible reporting flags. Optimize your Claude usage today.

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

---

**The `/caveman-stats` command parses Claude Code session transcripts to calculate estimated token savings using benchmark-derived compression ratios, supporting flags like `--share`, `--all`, and `--since` for flexible reporting.**

The Caveman skill for Claude Code provides built-in analytics to quantify exactly how many tokens you save by using context-compression modes. When you invoke the command, the system examines your session history, attributes token usage to specific Caveman modes, and applies real compression benchmarks to generate dollar-cost savings estimates.

## Invoking the `/caveman-stats` Command

The command definition lives 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), which registers the slash command with Claude Code. When executed, the agent runs the Node hook at **[`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js)**.

The script accepts three CLI arguments parsed at the top of the file ([lines 44‑52](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L44-L52)):

- **`--share`** – Generates a single-line, tweet-ready summary.
- **`--all`** – Aggregates lifetime statistics across all sessions.
- **`--since <duration>`** – Limits aggregation to a time window (e.g., `7d`).

If you run the command without arguments inside an active chat, it analyzes the current session only.

## Parsing Session Transcripts

To locate data, the hook first searches your Claude config directory (`$HOME/.claude`) for the most recent `.jsonl` transcript using **`findRecentSession`** ([lines 55‑75](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L55-L75)).

Once located, **`parseSession`** walks each line of the transcript ([lines 78‑106](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L78-L106)) and extracts:
- `output_tokens`
- `cache_read_input_tokens`
- Model name
- Timestamps for each assistant message

This raw data provides the foundation for all subsequent savings calculations.

## Attributing Tokens by Caveman Mode

Because users can switch Caveman modes mid-conversation, the system attributes token counts to the mode active at the time each message was generated.

The current mode flag is stored in `.caveman-active` inside the Claude config directory. The hook imports **`readFlag`** from `caveman-config` to read this state ([line 76](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L76)).

For historical attribution, **`readModeLog`** reads the mode transition log (`.caveman-mode-log.jsonl`) ([lines 55‑70](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L55-L70)). Then **`attributeByMode`** matches each message timestamp against this log, falling back to file-modification-time heuristics when necessary, to produce a `byMode` breakdown of tokens per mode ([lines 86‑130](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L86-L130)).

## Calculating Token Savings

The benchmark-derived compression ratios are stored in the **`COMPRESSION`** constant at the top of the file ([lines 19‑20](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L19-L20)), currently set to `0.65` for the `'full'` mode.

**`deriveSavings`** applies this ratio to each mode’s token total to compute estimated tokens saved. If a model price is known in the configuration, it also calculates the corresponding USD savings ([lines 41‑51](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L41-L51)).

## Formatting Output Options

The hook provides three distinct output formats depending on your needs.

### Full Session Statistics

**`formatStats`** builds a multi-line report showing turns, output tokens, cache-read tokens, per-mode breakdowns, and memory-compression savings ([lines 44‑100](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L44-L100)).

### Shareable One-Liner

**`formatShare`** returns a concise, human-readable summary suitable for social media ([lines 30‑41](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L30-L41)). Example output:

```text
🪨 Saved 12,500 output tokens (~$0.19) across 27 turns this session — caveman.sh

```

### Lifetime Aggregations

When using `--all` or `--since`, the hook loads `.caveman-history.jsonl`, deduplicates to keep only the latest snapshot per session, and aggregates totals via **`aggregateHistory`** ([lines 62‑84](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L62-L84)).

## Persisting Statistics to Disk

After each successful run, the hook appends a JSON line to **`.caveman-history.jsonl`** for lifetime tracking. It also updates **`.caveman-statusline-suffix`** in your Claude config directory with a short saved-tokens indicator, enabling shell prompts to display real-time savings ([lines 92‑108](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js#L92-L108)).

## Usage Examples

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

```bash
/caveman-stats

```

Generate a tweet-ready summary:

```bash
/caveman-stats --share

```

View lifetime totals across all sessions:

```bash
/caveman-stats --all

```

Filter to the last 7 days only:

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

```

## Summary

- The **`/caveman-stats`** command is defined in [`commands/caveman-stats.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-stats.md) and implemented in [`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js).
- It parses `.jsonl` session transcripts to extract `output_tokens` and `cache_read_input_tokens`.
- Token attribution uses **`attributeByMode`** to handle mid-conversation mode switches via `.caveman-mode-log.jsonl`.
- Savings calculations apply a **`COMPRESSION`** ratio of `0.65` to estimate token and cost reductions.
- Results can be formatted as detailed reports (`formatStats`), shareable lines (`formatShare`), or lifetime aggregates (`aggregateHistory`).
- Statistics persist to `.caveman-history.jsonl` and update `.caveman-statusline-suffix` for shell integration.

## Frequently Asked Questions

### Where does the `/caveman-stats` command get its token data?

The command reads Claude Code session transcripts stored as `.jsonl` files in `$HOME/.claude`. The **`parseSession`** function extracts token counts from each assistant message entry, including `output_tokens` and `cache_read_input_tokens`, along with timestamps and model identifiers.

### How accurate are the dollar-cost savings estimates?

The USD estimates are approximate based on the **`COMPRESSION`** ratio (currently `0.65` for full mode) and known model pricing. The calculation happens in **`deriveSavings`**, which multiplies saved tokens by the per-token cost for the specific model used. Actual billing may vary based on caching behavior and API pricing tiers.

### Can I track savings across multiple sessions?

Yes. Use the **`--all`** flag to aggregate statistics from `.caveman-history.jsonl`, which stores snapshots from every previous invocation. For time-limited views, combine this with **`--since`** (e.g., `--since 7d`) to filter the aggregation window, handled by the **`aggregateHistory`** function.

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

When **`attributeByMode`** cannot match a message timestamp to a specific mode entry in `.caveman-mode-log.jsonl`, it categorizes those tokens as "unknown." This typically occurs if the mode log was cleared or if messages predate the logging mechanism. The system falls back to the current flag state or session heuristics to minimize unclassified tokens.