skills.rest
th-efool
th-efoolCOMMUNITY
Explore all skills by this author →
GitHub

caveman-stats

Reports actual session token usage and estimated savings from the Claude Code session log.

1|Updated Aug 8, 2026
Search Tags:#claude code#hooks#token usage#cost tracking#jsonl#session log#savings estimate
One-click install
npx skills add https://github.com/th-efool/SKILLS --skill caveman-stats-th-efool
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: caveman-stats
Source: https://github.com/th-efool/SKILLS/tree/main/caveman-stats
Command: npx skills add https://github.com/th-efool/SKILLS --skill caveman-stats-th-efool

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It removes guesswork from measuring token savings by reading the real Claude Code session log instead of letting the model estimate its own usage, and it exposes when terse-output sessions actually cost more input tokens than they save. ## Core Features & Use Cases - Real token receipts: Reads the JSONL session log on disk to report actual input and output token counts for the current session. - Honest net accounting: Computes estimated rule overhead (default 1,250 input tokens per turn, configurable via CAVEMAN_RULE_OVERHEAD_TOKENS) and subtracts it from gross savings, plainly stating when the net is negative. - Statusline badge support: Writes a lifetime-savings suffix file so a statusline can display a glanceable gross-savings figure. - Use Case: After running a long session in caveman mode, invoke /caveman-stats to see whether the output-token savings actually outweighed the per-turn input cost of the injected rules for that workload. ## Quick Start Ask the assistant to run /caveman-stats to show the current session's real token usage and net savings.

Frequently Asked Questions about caveman-stats

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

FAQPage Schema
How do I check actual token usage in a Claude Code session?▼

Run /caveman-stats to read the current session's JSONL log on disk and report real input and output token counts. The numbers come from the log file, not from model estimation, so they reflect actual billed usage.

How are token savings calculated without AI estimation?▼

Savings are computed by comparing actual output tokens from the session log against an estimated non-caveman baseline. The hook formats and injects the result directly, so the model never computes or guesses the figures.

Why can token savings go negative in short sessions?▼

The injected rules cost roughly 1,250 input tokens per turn, and short sessions with terse replies may not save enough output tokens to cover that overhead. The Est. net line reports this negative result plainly instead of hiding it behind gross savings.

Can I change the rule overhead estimate per turn?▼

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, multiplied by the session turn count.

Does the statusline badge show net or gross savings?▼

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

Related Skills

Explore More Software Engineering Skills→
marketiv-idmarketiv-id

caveman-stats

Reports actual session token usage and savings from the Claude Code session log.

Official
Basic
bittlinkmbittlinkm

caveman-stats

Reports actual session token usage and estimated savings from the Claude Code session log.

Community
Intermediate
tkoguttkogut
1

caveman-stats

Reports actual session token usage and savings from Claude Code JSONL session logs.

Community
Intermediate
SaturateSaturate

stats

Compute Claude Code usage totals, per-tool counts, and session counts from JSONL logs.

Community
Intermediate