How to use the Caveman Stats Reporter agent skill

What does the caveman-stats skill make the agent do?

The skill reports recorded usage for the current Claude Code session, or points you to the host's native usage report if you are using a different tool. In Claude Code, a companion hook script generates the report, and the agent prints it unchanged. The agent is told not to calculate or add numbers itself.

The report shows recorded output and cache-read tokens, response counts, and mode attribution where available. The skill is built to avoid overstating results: it does not estimate how many tokens Caveman saved, because the transcript has no measured comparison without Caveman.

• Shows recorded output tokens and cache-read tokens
• Shows response counts for the session
• Shows which Caveman mode was active, where that is recorded
• Reports savings as unknown rather than estimating them

Install the caveman-stats skill

Download the ZIP file from this page. Then choose one of the two methods below.

For a personal install that works in all your projects, unzip the file into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

What you need before the report works

The hook-based report requires Claude Code and the Caveman plugin installed with its src/hooks scripts. The report depends on the two hook scripts in that folder: caveman-mode-tracker.js, which runs the stats logic, and caveman-stats.js, which generates the report.

The skill runs scripts and does not use the network, according to its listing. Without the Caveman plugin and its hook scripts, the hook-based report is not available.

• Claude Code
• The Caveman plugin, installed with its src/hooks scripts
• Scripts run locally; the listing states the skill does not use the network

How to trigger the skill with a request

Type /caveman-stats in Claude Code to trigger the skill. The hook runs the report and passes it to the agent, which prints it verbatim inside a fenced code block.

Other tools use different commands. In Gemini CLI, the skill tells you to use /stats model for current session token usage or /stats session for session statistics. Those are Gemini's own built-in commands, so run them directly in Gemini CLI.

• Claude Code: /caveman-stats
• Gemini CLI: use /stats model or /stats session directly

Read the report and its flags

The --all and --since 7d options aggregate the latest recorded output count for each session. The --share option reports observed usage with savings still marked as unknown.

Older history rows may contain estimated savings fields named est_saved_*. The skill ignores those fields. The original rows stay on disk, but they are not used in the report. The statusline shows the active mode and no longer shows the retired savings badge.

Memory-file pairs, meaning original and current versions of a memory file, are reported by their measured byte sizes. A size difference does not establish token or billing savings. For the reasoning behind these numbers, see docs/HONEST-NUMBERS.md in the Caveman project.

• --all: aggregates the latest recorded output count per session
• --since 7d: limits aggregation to the last 7 days
• --share: reports observed usage with savings unknown
• Historical est_saved_* fields are ignored
• Memory-file size differences are not token or billing savings

Examples of what the report tells you

A typical check is to run /caveman-stats at the end of a working session to see how many output and cache-read tokens were recorded and which Caveman mode was active. Running it across several sessions shows how often each mode was in use.

The report does not tell you how much money or how many tokens Caveman saved. If you need that figure, the source says there is no measured comparison without Caveman to base it on.

• Check recorded output and cache-read tokens for the current session
• See which Caveman modes were active across recent sessions with --since 7d
• Compare memory-file byte sizes before and after changes, understanding these are not billing figures