Catalog
JuliusBrussee/caveman-stats

JuliusBrussee

caveman-stats

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.

NewUpdated Oct 8, 2026

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.

Files2
2 files · 13.8 KB

Select a file to preview

Overall Score

81/100

Grade

B

Good

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

90

Quality

80

Clarity

85

Completeness

72

Summary

Caveman-stats is a Claude Code skill that displays token usage and cache-read metrics from the current session, along with mode attribution where available. It reads from session logs (JSONL format) and relays pre-computed metrics through a hook-supplied report, explicitly avoiding recalculation or inference of savings. For Gemini CLI, it directs users to native `/stats` commands.

Detected Capabilities

file read (session logs in JSONL format)report generation and formattingtime-based filtering (--since 7d)output relay without computation

Trigger Keywords

Phrases that agents use to match this skill to user intent.

view token usagecheck cache read tokenssession statisticsmode attributioncaveman stats

Referenced Domains

External domains referenced in skill content, detected by static analysis.

geminicli.comwww.apache.org

Use Cases

  • view current session token usage and breakdown
  • check cache-read token consumption
  • review mode attribution across responses
  • aggregate usage across multiple sessions with --all or --since flags
  • share session usage report (--share flag)
  • locate native usage reports in Gemini CLI or other hosts

Quality Notes

  • Clear, well-documented scope: skill explicitly avoids inference, recalculation, or estimation of savings; this boundary is stated multiple times (no guessing on token outcomes)
  • Strong cross-host guidance: detailed fallback behavior for Gemini CLI and other environments where hook infrastructure is unavailable
  • Honest measurement philosophy: references external documentation (HONEST-NUMBERS.md) and acknowledges measurement limits; repeated emphasis that savings are unknown without external comparison
  • Good use case coverage: includes examples of all four invocation patterns (/caveman-stats, --all, --since 7d, --share)
  • Output example provided: shows expected format and reinforces that numbers are observed, not computed
  • Well-defined limitation: tool cannot aggregate Claude transcripts as Gemini usage; cannot read live metrics from other hosts
  • Minor weakness: no documented error handling (e.g., missing session log, corrupted JSONL, no mode-transition data); README hints at 'missing mode attribution stays unknown' but doesn't explain recovery behavior
Model: claude-haiku-4-5-20251001Analyzed: Oct 8, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

  1. v3.1

    Content updated

    ✦ AIDocumentation updates to README.md and expanded LICENSE.

    2026-10-08

    LATEST
  2. v3.0

    Contract changed: description

    ✦ AIShifts from blocking hook that displays savings estimates to non-blocking context injection; removes estimated savings calculations and expands to multi-host usage reports.

    triggering2026-09-15

    View This Version
  3. v2.0

    Contract changed: description

    ✦ AISkill description simplified: removes implementation details about session log reading and mode-tracker hook injection.

    triggering2026-09-09

    View This Version
  4. v1.0

    2026-08-17

    View This VersionInitial version

Use JuliusBrussee/caveman-stats in your dev environment

Command Palette

Search for a command to run...