caveman-stats

Use it when: you want to see how many tokens your Claude Code session has used, and in which Caveman mode
It does: prints a usage report from Caveman's hooks, unchanged: output and cache-read tokens, response counts and the mode behind them
Reports: only measured usage; it doesn't estimate savings, since nothing measured the same work without Caveman
Needs: Claude Code with the Caveman plugin's hooks; in Gemini CLI it points you to /stats instead

Skill 5 of 12 in the Caveman bundle · Before it: caveman-compress · After it: caveman-help

Only works inside its bundle: Prints the token report of hooks that only the Caveman plugin installs, in Claude Code. Install Caveman instead.

TLDR

Caveman is a plugin and skill set that makes agents reply tersely to save tokens. When you run /caveman-stats, a hook installed by the plugin builds a usage report, and the agent prints it as is in a code block, without recomputing or rounding anything. The report shows output and cache-read tokens, response counts and which Caveman mode was active, and it can also total past sessions. It never estimates tokens, percentages or dollars saved, because there's no measured run of the same work without Caveman to compare against. Outside Claude Code it can't read live usage: in Gemini CLI it sends you to /stats model or /stats session, and elsewhere it uses the host's own report or says usage is unavailable.

Summarizes the skill at bad48a0.

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

skills.sh page · Source on GitHub · All skills from juliusbrussee/caveman

Installs: 313,086 on skills.sh, Sep 21, 2026
Repo stars: 106,976 juliusbrussee/caveman
First seen: Apr 30, 2026 on skills.sh

Weekly installs

13.8K

-7% over 8 weeks · week to Sep 21

Weekly values

Week to	Installs
Aug 3	14,834
Aug 10	15,408
Aug 17	10,189
Aug 24	9,476
Aug 31	9,666
Sep 7	11,825
Sep 14	13,003
Sep 21	13,817

Category	category:output-style category:software-engineering Change how the agent replies: shorter, clearer, fewer tokens. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:command A one-shot action you invoke by name, such as turning the conversation into a PRD.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:claude-code Uses Claude Code features such as hooks or background agents.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	token-saving

SKILL.md

From juliusbrussee/caveman at bad48a0. Checked daily, last changed Oct 20, 2026.

Frontmatter

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.