mcpField
C
caveman-stats

caveman-stats

github.com/juliusbrusseeDevelopment115.8k360.7k installsUpdated 4d ago
Repository

About caveman-stats

caveman-stats reports recorded output and cache-read token usage for Caveman sessions, triggered by /caveman-stats in Claude Code. It does not estimate savings and points to native usage commands in other hosts.

Key features

  1. 01Shows recorded output and cache-read token counts
  2. 02Aggregates usage with --all and --since 7d options
  3. 03Provides a shareable usage report with --share
  4. 04Prints report verbatim without recalculating figures

Use cases

  1. 01Reviewing Caveman usage history in Claude Code
  2. 02Finding the Gemini CLI command for current session usage
  3. 03Summarizing output usage across sessions over a time range

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/juliusbrussee/caveman --skill caveman-stats

After installing, type/caveman-statsin Claude Code to confirm it loaded.

Bundled filesREADME.md

Details

From the project README

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.

Comments

Markdown supported