README.md
# caveman-stats
Recorded session usage. Savings stay unknown without a measured comparison.
## What it does
Reads the current Claude Code session log and reports output tokens, cache-read input tokens, and response counts. When a mode-transition log is available, it separates output by the mode active for each response. Missing mode attribution stays unknown. Numbers come from the JSONL session log on disk — the model itself does not compute or estimate them. Output is injected by the `caveman-mode-tracker` hook, which intercepts `/caveman-stats`, runs the stats script, and hands the formatted block back as `additionalContext` with an instruction to print it verbatim.
The transcript does not contain the same session without Caveman, so the report cannot calculate tokens saved, a reduction percentage, dollars saved, rule overhead, or a net result. Earlier releases applied a fixed ratio without a committed reviewed benchmark. Those estimates no longer appear in session reports, lifetime totals, shared summaries, or the statusline.
In Claude Code, every session also writes a snapshot when it ends (a `SessionEnd` hook runs the same script with `--record`, silently), so `--all` and `--since` count every session, not only the ones where you ran `/caveman-stats`.
Recorded history stays on disk. New snapshots contain observed usage and mode attribution; historical estimated-savings fields are ignored. Original/current memory-file pairs show byte-size differences separately, without treating them as provider savings.
## How to invoke
```
/caveman-stats
/caveman-stats --all
/caveman-stats --since 7d
/caveman-stats --share
```
Claude Code's hook runs `src/hooks/caveman-stats.js` and tells the model to relay the generated report verbatim. The model does not estimate the numbers.
## Example output
An illustrative transcript with one response and 1,000 output tokens produces:
```
Turns: 1
──────────────────────────────────
Output tokens: 1,000
Cache-read tokens: 2,400
──────────────────────────────────
Mode: full (current mode; no transition log)
Savings: unknown — no measured comparison for this session.
```
## See also
- [`SKILL.md`](./SKILL.md) — hook contract
- [Honest Numbers](../../docs/HONEST-NUMBERS.md) — measurement limits
- [Caveman README](../../README.md) — repo overview
Gemini CLI uses its native `/stats model` or `/stats session` report. The Caveman
command points there; it cannot access Gemini's live metrics or aggregate Claude
transcripts as Gemini usage. [Gemini command reference](https://geminicli.com/docs/reference/commands/).
SKILL.md
---
name: caveman-stats
description: >
Show recorded output and cache-read token usage and mode attribution for
the current Claude Code session, or locate the host's native usage report.
Trigger: /caveman-stats.
---
In Claude Code, `src/hooks/caveman-mode-tracker.js` resolves `src/hooks/caveman-stats.js` next to itself and runs it on `/caveman-stats`. The hook does not block the prompt: it supplies the report through `hookSpecificOutput.additionalContext` with an instruction to print it verbatim inside a fenced code block. Do exactly that, and do not calculate, recompute or re-round the numbers yourself.
In Gemini CLI, direct the user to `/stats model` for current session token usage or `/stats session` for session statistics. Gemini custom commands are prompts; they cannot invoke the built-in command or read its live session metrics. Never read Claude Code transcripts as Gemini usage. In other hosts, use a native usage report if one is available; otherwise say that current session usage is unavailable. The Claude reader and its lifetime history apply only to Claude Code. Savings remain unknown in every host without a measured comparison.
The report shows recorded output and cache-read tokens, response counts, and mode attribution where available. Savings are unknown: the transcript has no measured comparison without Caveman. Do not infer saved tokens, percentages, dollars, rule overhead, or a net result from output counts or the current mode.
`--all` and `--since 7d` aggregate the latest recorded output count per session. `--share` reports observed usage with savings unknown. Historical `est_saved_*` fields are ignored; their original history rows remain on disk. The statusline shows the active mode without the retired savings badge.
Original/current memory-file pairs are reported by their measured byte sizes. Those file-size differences do not establish provider token or billing savings. See `docs/HONEST-NUMBERS.md`.