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

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), which registers the slash command with Claude Code. When executed, the agent runs the Node hook at src/hooks/caveman-stats.js.

The script accepts three CLI arguments parsed at the top of the file (lines 44‑52):

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

Once located, parseSession walks each line of the transcript (lines 78‑106) 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).

For historical attribution, readModeLog reads the mode transition log (.caveman-mode-log.jsonl) (lines 55‑70). 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).

Calculating Token Savings

The benchmark-derived compression ratios are stored in the COMPRESSION constant at the top of the file (lines 19‑20), 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).

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).

Shareable One-Liner

formatShare returns a concise, human-readable summary suitable for social media (lines 30‑41). Example output:

🪨 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).

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).

Usage Examples

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

/caveman-stats

Generate a tweet-ready summary:

/caveman-stats --share

View lifetime totals across all sessions:

/caveman-stats --all

Filter to the last 7 days only:

/caveman-stats --since 7d

Summary

• The /caveman-stats command is defined in commands/caveman-stats.md and implemented in 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.

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