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 Sep 15, 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 · 3.9 KB

Select a file to preview

Overall Score

82/100

Grade

B

Good

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

Safety

90

Quality

78

Clarity

82

Completeness

78

Summary

The caveman-stats skill displays session token usage metrics and cache-read statistics from Claude Code or directs users to native reporting in other hosts (Gemini CLI, etc.). It reads session JSONL logs, formats output without recalculating numbers, and explicitly avoids inferring savings or cost metrics without measured baselines.

Detected Capabilities

file read (JSONL session logs)text formatting and output generationconditional logic based on host environmentflag parsing (--all, --since, --share)

Trigger Keywords

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

view session statstoken usage reportcache metricsmode attributioncaveman stats

Risk Signals

INFO

Reads session JSONL logs from disk

SKILL.md, README.md
INFO

No file writes or modifications performed

SKILL.md, README.md
INFO

No external network requests or API calls

SKILL.md, README.md
INFO

No credential or secret access

SKILL.md, README.md
INFO

Output is formatted text — no code execution

SKILL.md, README.md

Referenced Domains

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

geminicli.com

Use Cases

  • /caveman-stats command in Claude Code to view current session output and cache-read token counts
  • Aggregate usage statistics across multiple sessions using --all or --since 7d flags
  • Compare token attribution by mode (full/caveman) when mode transition logs are available
  • Share session usage with --share flag while maintaining honest reporting of unknown savings
  • Locate and direct users to native usage reports in non-Claude-Code hosts like Gemini CLI

Quality Notes

  • Clear boundary between Claude Code and Gemini CLI workflows — instructions prevent misuse across hosts
  • Explicit documentation of limitations: savings are unknown without measured comparison, historical estimates are deprecated
  • Prevents misleading calculations by instructing the agent to print numbers verbatim without recomputation
  • Good use of flags (--all, --since 7d, --share) to control scope and privacy
  • README provides concrete example output, helping users understand expected format
  • References supporting documentation (HONEST-NUMBERS.md) to justify measurement philosophy
  • Minor: SKILL.md could be clearer about error handling when session log is unavailable or corrupted
Model: claude-haiku-4-5-20251001Analyzed: Sep 15, 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.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

    LATEST
  2. 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
  3. 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...