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

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) and configured in [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), 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) 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:

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:

/caveman-stats

Generate a shareable one-liner:

/caveman-stats --share

Output:

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

View lifetime totals across all sessions:

/caveman-stats --all

View statistics for the last 7 days only:

/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.
• 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 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.

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