# Caveman Stats

> Use when the user invokes /caveman-stats or asks for caveman token-usage stats. Shows real token usage and estimated savings for the current session, read directly from the Claude Code session log — no AI estimation. Output is injected by the `caveman-mode-tracker` hook (vendored alongside this skill), which intercepts the slash command and returns the formatted stats as a blocked-decision reason.

- Skill: `danmestas/caveman-stats` (Agent Skill)
- Install (CLI): `npx skillmds@latest add danmestas/caveman-stats`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danmestas/caveman-stats/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: [object Object]
- Author: danmestas (https://skillmd.com/u/danmestas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danmestas/caveman-stats

---


# Caveman Stats

This skill is delivered by the `hooks/caveman-mode-tracker` hook, which intercepts `/caveman-stats` on `UserPromptSubmit` and runs the bundled `caveman-stats.js` against the active Claude Code session transcript. The hook returns `decision: "block"` with the formatted stats as the reason — the user sees real token counts and estimated savings immediately, and the model never has to compute or estimate anything.

Numbers come from the JSONL session log on disk:

- `output_tokens` and `cache_read_input_tokens` summed across every assistant turn.
- Estimated savings derived from the mean per-task ratio recorded in `caveman-stats.js` (`COMPRESSION` table — currently only `full` mode has benchmark data; other modes report no estimate).
- Lifetime aggregation across sessions via `/caveman-stats --all` or `/caveman-stats --since 7d`, backed by `~/.claude/.caveman-history.jsonl`.

If the hook isn't registered in the active settings, the slash command falls through to the model — surface that fact and point the user at the wardrobe `hooks/caveman-mode-tracker` component (or the upstream installer at https://github.com/JuliusBrussee/caveman).