Caveman Stats
Run /caveman-stats to see real session token input, output, and estimated caveman savings from the Claude Code JSONL log without asking the model to guess.
Overview
Caveman-stats is an agent skill most often used in Operate (also Build while coding) that shows real session token usage and estimated caveman savings from the Claude Code log via a hook.
Install
npx skills add https://github.com/juliusbrussee/caveman --skill caveman-statsWhat is this skill?
- Invoked via /caveman-stats; caveman-mode-tracker hook blocks and injects formatted stats—model does not compute numbers
- Reports turn count, actual input/output tokens, baseline estimate, and saved tokens with ~65% savings in the documented
- Reads Claude Code session JSONL directly—no AI estimation of usage
- Writes lifetime-savings suffix consumed by the statusline badge (e.g. ⛏ 12.4k)
- Example session: 47 turns; ~65% token savings in documented sample output
- Lifetime savings suffix powers statusline ⛏ badge
Adoption & trust: 90.6k installs on skills.sh; 70k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You cannot tell whether caveman compression is actually saving context because the model would just speculate about token usage.
Who is it for?
Builders already using caveman modes who want one-slash-command receipts during long Claude Code sessions.
Skip if: Teams without the caveman hook stack installed or anyone who needs org-wide billing dashboards instead of per-session log stats.
When should I use this skill?
User runs /caveman-stats or asks for real session token usage and caveman savings without AI estimation.
What do I get? / Deliverables
You get hook-injected session and lifetime token receipts from the JSONL log, including baseline comparison and savings, without burning turns on manual calculation.
- Formatted session token and savings report
- Updated lifetime-savings suffix for statusline
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Token receipts belong where builders watch session health and cost while agents run in production-like daily use. Hooks read the on-disk session log and inject formatted stats—classic observability for an agent coding session.
Where it fits
Mid-incident fix, run /caveman-stats to see whether output tokens stayed bounded after many tool calls.
After a delegation-heavy feature afternoon, check measured savings versus baseline before starting another cavecrew chain.
Compare session efficiency across weeks using lifetime badge suffix files as a rough personal productivity signal.
How it compares
Session-local hook receipts from disk logs, not a SaaS analytics dashboard or model-estimated token guesses in chat.
Common Questions / FAQ
Who is caveman-stats for?
Caveman-stats is for solo developers running caveman-enabled Claude Code who want factual token and savings numbers for the current session and cumulative statusline badge.
When should I use caveman-stats?
Use it in Operate when monitoring session cost and context pressure, and during Build checkpoints when you want to confirm compression after a burst of subagent delegations; invoke with /caveman-stats anytime.
Is caveman-stats safe to install?
Check the Security Audits panel on this page for audit results; the skill reads your local Claude Code session log via project hooks—review hook code and log paths like any filesystem-touching automation.
SKILL.md
READMESKILL.md - Caveman Stats
This skill is delivered by `hooks/caveman-stats.js` (read by `hooks/caveman-mode-tracker.js` on `/caveman-stats`). The model does not need to do anything when this skill fires — the hook returns `decision: "block"` with the formatted stats as the reason. The user sees the numbers immediately. # caveman-stats Real session token receipts. No AI estimation. ## What it does Reads the current Claude Code session log directly and reports actual input/output token usage plus estimated savings versus a non-caveman baseline. 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` and returns the formatted stats as a blocked-decision reason. Each run also writes a lifetime-savings suffix file used by the statusline badge (`⛏ 12.4k`). ## How to invoke ``` /caveman-stats ``` ## Example output ``` Session: 47 turns Input: 12,304 tokens Output: 3,891 tokens (caveman) Baseline: 11,247 tokens (estimated without caveman) Saved: 7,356 tokens (~65%) ``` ## See also - [`SKILL.md`](./SKILL.md) — hook contract and mechanics - [Caveman README](../../README.md) — repo overview