caveman--caveman-stats

Reports actual session token usage and estimated savings read from the JSONL session log.

Updated Dec 3, 2025
One-click install
npx skills add https://github.com/hhenrichsen/dots --skill caveman-caveman-stats-hhenrichsen
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: caveman--caveman-stats
Source: https://github.com/hhenrichsen/dots/tree/main/dot_skills/caveman/caveman-stats
Command: npx skills add https://github.com/hhenrichsen/dots --skill caveman-caveman-stats-hhenrichsen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Token-saving prompt styles are hard to evaluate because the model cannot measure its own usage. This Skill reads the current Claude Code session log directly and reports real input/output token counts plus estimated savings versus a non-caveman baseline, so you can see whether the mode actually pays for itself. ## Core Features & Use Cases - Real token receipts: Parses the on-disk JSONL session log for actual input and output token counts instead of model estimates. - Honest net accounting: Shows estimated rule overhead (default 1,250 input tokens per turn, configurable via CAVEMAN_RULE_OVERHEAD_TOKENS) and a net figure that plainly flags net-negative sessions. - Statusline badge support: Writes a lifetime-savings suffix file consumed by the statusline badge for a glanceable gross-savings summary. - Use Case: After a long coding session, run the stats command to learn that terse replies made the mode net-negative, and decide to disable it for that workload. ## Quick Start Type /caveman-stats in the current session to see real token usage, estimated savings, rule overhead, and net cost.

Frequently Asked Questions about caveman--caveman-stats

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check token usage for my current Claude Code session?▼

Run /caveman-stats in the active session. The caveman-mode-tracker hook intercepts the command, reads the JSONL session log on disk, and returns formatted input/output token counts plus estimated savings as a blocked-decision reason.

How are the token savings numbers calculated?▼

Savings compare actual caveman output tokens against an estimated non-caveman baseline, both derived from the session log rather than model guesses. Net savings subtract estimated rule overhead, defaulting to 1,250 input tokens per turn.

Can I change the assumed per-turn rule overhead?▼

Yes, set the CAVEMAN_RULE_OVERHEAD_TOKENS environment variable to your own measured per-turn input cost. The default is 1,250 tokens per turn, used only when the savings figure has an unambiguous turn count.

Why does the net savings line sometimes show a negative number?▼

Short sessions with terse replies can cost more in injected rule input tokens than they save in output tokens. The output states this plainly and suggests turning the mode off for that workload instead of hiding it behind gross savings.

Does the statusline badge show net or gross savings?▼

The badge shows gross lifetime savings as a glanceable summary, written to a suffix file on each run. Run /caveman-stats for the full net picture including rule overhead.