PluginBench
Skill
Pass
Audit score 90

caveman-stats

juliusbrussee/caveman

Display Claude Code session token usage and cache-read metrics with mode attribution.

SourceView on skills.sh

What is caveman-stats?

Shows recorded output and cache-read token usage for the current Claude Code session, plus mode attribution. Use this to review token consumption and cache performance within your coding session. Trigger with /caveman-stats.

  • Display recorded output and cache-read token counts for the current session
  • Show response counts and mode attribution where available
  • Aggregate usage across multiple sessions with --all or --since flags
  • Report observed usage with --share for sharing metrics
  • Access native usage reports in Gemini CLI via /stats model or /stats session

How to install caveman-stats

npx skills add https://github.com/juliusbrussee/caveman --skill caveman-stats
Claude Code
Cursor
Windsurf
Cline

How to use caveman-stats

  1. 1.Trigger the command with /caveman-stats in Claude Code
  2. 2.Review the displayed report showing output tokens, cache-read tokens, and response counts
  3. 3.Use --all flag to aggregate usage across all recorded sessions
  4. 4.Use --since 7d to aggregate usage from the last 7 days
  5. 5.Use --share to report metrics for sharing with others

Use cases

Good for
  • Review token consumption after a Claude Code coding session
  • Check cache-read performance to understand prompt caching effectiveness
  • Aggregate token usage across multiple sessions for billing or performance analysis
  • Share session metrics with team members using --share flag
  • Compare token usage between different coding modes
Who it's for
  • Claude Code users monitoring token usage
  • Developers tracking cache performance in coding sessions
  • Teams analyzing aggregate token consumption
  • Users optimizing prompt caching strategies

caveman-stats FAQ

What tokens does caveman-stats measure?

It shows recorded output tokens and cache-read tokens for the current session, plus response counts and mode attribution where available.

Can I see historical savings or cost reductions?

No. The report does not infer saved tokens, percentages, or dollars. File-size differences do not establish provider token or billing savings. See docs/HONEST-NUMBERS.md for details.

How do I use this in Gemini CLI instead of Claude Code?

In Gemini CLI, use /stats model for current session token usage or /stats session for session statistics. Gemini custom commands cannot invoke built-in commands or read live metrics.

What do the --all and --since flags do?

--all aggregates the latest recorded output count per session across all sessions. --since 7d aggregates usage from the last 7 days.

Does this show memory file savings?

Original and current memory-file pairs are reported by byte size, but file-size differences do not establish provider token or billing savings.

Full instructions (SKILL.md)

Source of truth, from juliusbrussee/caveman.


name: caveman-stats description: > 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.

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.