caveman-stats Skill for Claude: See Your Session Token Usage

caveman-stats shows how many output and cache-read tokens your Claude Code session used, split by caveman mode.

Installs: 364.9K; on skills.sh
Stars: 116.7K; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

caveman-stats runs when you type /caveman-stats in Claude Code. A hook in the caveman package reads the session log on disk and Claude prints the generated report as it is. You can add --all, --since 7d or --share.

The report shows recorded output and cache-read tokens, response counts and mode attribution. It does not show tokens saved: SKILL.md says savings are unknown because there is no matching session without caveman to compare. The skill alone is not enough, because the report comes from a hook script, so install the full caveman package.

Good for

Claude Code users who want to see real token counts for a session
People testing caveman who want honest numbers, not estimates

Install caveman-stats

Claude Code

Copy this prompt.

Install the caveman-stats skill in Claude Code. Run this command:

/plugin marketplace add JuliusBrussee/caveman
/plugin install caveman@caveman

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Use the plugin, not the single skill folder. SKILL.md says /caveman-stats is served by hook scripts (caveman-mode-tracker.js and caveman-stats.js) that live in the caveman package. The installer needs Node.js 22.13 or newer.

From the project README. Source.

What's in the skill

When it loads

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.

Key facts

Author: JuliusBrussee (repo owner)
License: Apache-2.0
Installs on skills.sh: 364,926 as of 2026-11-02
GitHub stars: 116,702 for the whole juliusbrussee/caveman repo
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
What is inside: 2 files: SKILL.md and README.md; the report script lives in the caveman package, not in this folder
Needs: Claude Code and the caveman hooks (src/hooks/caveman-mode-tracker.js and caveman-stats.js from the caveman package)
Last commit to the repo: 2026-11-01

What it includes

Current session: output tokens, cache reads, responses
The caveman mode-tracker hook runs a stats script and hands the report to Claude to print verbatim in a code block. Claude does not recompute the numbers.
Try: “/caveman-stats”
Runs code · /caveman-stats
Adds up the latest count from every recorded session
Aggregates the latest recorded output count per session.
Runs code · /caveman-stats --all
Limits the totals to a recent window
Same as --all, for sessions in the last 7 days.
Runs code · /caveman-stats --since 7d
A shareable summary of observed usage
Reports observed usage with savings marked unknown.
Runs code · /caveman-stats --share
A SessionEnd hook records each session on exit
Per the bundled README, every Claude Code session writes a snapshot when it ends so --all and --since cover all sessions.
Runs code · Session snapshot
Gemini CLI points to /stats; others say usage is unavailable
In Gemini CLI it tells you to use /stats model or /stats session. In other hosts it uses a native report if one exists.
Read · Other hosts

From the official docs

Permissions

Low risk

It installs hooks that run a script and write a snapshot file at the end of every session. Check the hook files in the caveman package if you manage Claude Code settings carefully.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Hooks run on every session
Per the bundled README, a SessionEnd hook runs the stats script silently and writes a snapshot. You can see them in your Claude Code hook settings.
It reads your session transcripts
The report is built from the session log on disk. Nothing in SKILL.md says it is sent anywhere.

Technical details

Scopes	A hook runs a Node script on /caveman-stats Reads the Claude Code session log on disk A SessionEnd hook writes a usage snapshot when a session ends

Questions

What does caveman-stats do?

It shows token usage for your current Claude Code session: output tokens, cache-read tokens, response counts and which caveman mode was active. The numbers come from the session log, not from Claude's estimate.

How do I install caveman-stats?

Use the install box at the top of this page and pick the full caveman package. SKILL.md says the report is produced by hook scripts in that package, which the single skill folder does not contain.

Does it show how many tokens caveman saved?

No. SKILL.md says savings are unknown, because the transcript has no matching session without caveman. It also says not to infer saved tokens, percentages or dollars from the counts.

Does it work outside Claude Code?

Only the Claude Code report is generated by the hook. In Gemini CLI the skill points you to /stats model or /stats session. In other tools it says usage is unavailable unless a native report exists.

Does it send my session data anywhere?

SKILL.md describes a local script reading the session log on disk. It does not say anything is sent out. Read the hook scripts in the repo if that matters for your setup.

Is caveman-stats safe?

It reads your session log and writes a snapshot at the end of each session, through hooks the caveman package installs. On skills.sh the audits read Gen Agent Trust Hub pass, Socket pass and Snyk pass.

Information

updated Nov 2, 2026

Repository: juliusbrussee/caveman
Folder: skills/caveman-stats

juliusbrussee/caveman skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

caveman README · github.com
caveman-stats SKILL.md · github.com
caveman-stats SKILL.md · github.com
caveman-stats README · github.com
skills.sh listing and audits · skills.sh