Caveman Stats

JuliusBrussee/caveman/skills/caveman-stats

by JuliusBrussee2e08b9177c07bb7249a8a2d1a6758e5db281d002No license110K starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated today

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.

Instructions onlyData & Analytics
AI-generated overview

Reports recorded output and cache-read token usage and mode attribution for the current Claude Code session.

What it does
This skill surfaces recorded output and cache-read token usage, response counts, and mode attribution for the current Claude Code session, or points the user to the host's native usage report. In Claude Code a hook supplies the report, which is printed verbatim in a fenced code block; in Gemini CLI the user is directed to /stats model or /stats session. It also supports aggregation flags such as --all and --since 7d and a --share mode, and reports original/current memory-file pairs by measured byte sizes. It explicitly states that savings are unknown and refuses to infer saved tokens, percentages, dollars, or net results.
When to use it
Use it when you want to see recorded token usage and mode attribution for the current Claude Code session, or when you need to find the host's native usage report. It is also relevant when aggregating recorded output counts across sessions or checking memory-file size differences. It is not meant for estimating savings, since no measured comparison exists.
Requirements
Runs in Claude Code, where it depends on the hook files src/hooks/caveman-mode-tracker.js and src/hooks/caveman-stats.js, or in Gemini CLI, where it only directs the user to built-in /stats commands. No scripts ship with the skill; it is instructions only. The Claude reader and its lifetime history apply only to Claude Code.

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.

Source and attribution

Source:JuliusBrussee/cavemaninskills/caveman-statsat commit2e08b91

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Caveman Stats · skills/caveman-stats Agent Skill | SourceWeft