skills.rest
tomw200082-collab
tomw200082-collabCOMMUNITY
Explore all skills by this author →
GitHub

caveman-stats

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

Updated May 8, 2026
Search Tags:#claude code#token usage#cost tracking#hook#jsonl#session log#savings estimate
One-click install
npx skills add https://github.com/tomw200082-collab/gt-factory-os-production-brain --skill caveman-stats-tomw200082-collab
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: caveman-stats
Source: https://github.com/tomw200082-collab/gt-factory-os-production-brain/tree/main/.claude/skills/caveman-stats
Command: npx skills add https://github.com/tomw200082-collab/gt-factory-os-production-brain --skill caveman-stats-tomw200082-collab

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It removes guesswork from measuring token savings by reading real input/output token counts directly from the Claude Code session log instead of relying on AI estimation, and it exposes when rule overhead makes the net savings negative. ## 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. - Savings and net accounting: Estimates savings versus a non-caveman baseline, then subtracts per-turn rule overhead (default 1,250 tokens/turn, configurable via CAVEMAN_RULE_OVERHEAD_TOKENS) to show an honest net figure. - Statusline badge support: Writes a lifetime-savings suffix file used by the statusline badge for a glanceable gross-savings summary. - Use Case: After a long coding session, run /caveman-stats to see whether the injected rules actually saved tokens for that workload or cost more than they saved. ## Quick Start Type /caveman-stats in your Claude Code session to see 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 token usage for my current Claude Code session?▼

Run /caveman-stats in the session. The mode-tracker hook reads the JSONL session log on disk and returns actual input and output token counts, so the numbers come from the log rather than model estimation.

How are token savings estimated in caveman-stats?▼

Savings are estimated by comparing actual caveman output tokens against a baseline of estimated tokens without caveman. The estimate only appears when the span is unambiguous, meaning a single benchmarked mode with a known turn count.

Why does caveman-stats show a negative net savings?▼

Net savings subtract the per-turn input cost of injected rules (default 1,250 tokens per turn) from gross savings. On short sessions with terse replies, output savings may not cover that input overhead, so the net goes negative and the output says so directly.

Can I change the rule overhead value used in the net calculation?▼

Yes. Set the CAVEMAN_RULE_OVERHEAD_TOKENS environment variable to your measured per-turn input cost. The default is 1,250 tokens per turn if you have not measured your own setup.

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 accounting including rule overhead, run /caveman-stats.

Related Skills

Explore More Software Engineering Skills→
selfagencyselfagency

caveman-stats

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

Community
Basic
rvdbreemenrvdbreemen
199

caveman-stats

Report measured token usage and savings from Claude Code JSONL session logs.

Community
Basic
ByronWilliamsCPAByronWilliamsCPA

usage-report

Track Claude Code token usage across local JSONL transcripts.

Official
Advanced
Mosaic-agentMosaic-agent
36

caveman-stats

Report real token usage and estimated savings from Claude Code session logs.

Official
Basic