skills.rest
bittlinkm
bittlinkmCOMMUNITY
Explore all skills by this author →
GitHub

caveman-stats

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It answers whether terse-output mode actually saves tokens by reading real numbers from the session log instead of letting the model estimate, and it exposes when rule overhead makes the net savings negative. ## Core Features & Use Cases - Real token accounting: Reads input/output token counts directly from the JSONL session log on disk, with no AI estimation. - Net savings analysis: Computes estimated rule overhead (default 1,250 input tokens per turn, configurable via CAVEMAN_RULE_OVERHEAD_TOKENS) and reports net savings, flagging net-negative sessions plainly. - Statusline badge support: Writes a lifetime-savings suffix file consumed by the statusline badge for a glanceable gross-savings figure. - Use Case: After a long coding session, run /caveman-stats to see whether the injected rules cost more input tokens than the terse outputs saved, and decide whether to disable the mode for that workload. ## 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 intercepts the command, reads the JSONL session log on disk, and returns formatted input/output token counts plus estimated savings without any model estimation.

How are token savings estimated without AI estimation?▼

The hook reads actual input and output token counts from the session log and compares output against a benchmarked baseline for the active mode. The model never computes the numbers; the hook returns them as a blocked-decision reason.

What does the Est. net line mean in caveman-stats output?▼

Est. net is gross savings minus estimated rule overhead, which defaults to 1,250 input tokens per turn. When negative, the injected rules cost more than the output savings, and the output says so directly and suggests disabling the mode.

Can I change the rule overhead estimate per turn?▼

Yes, set the CAVEMAN_RULE_OVERHEAD_TOKENS environment variable to your measured per-turn input cost. The default is 1,250 tokens per turn, applied only when the turn count and mode attribution are unambiguous.

Why does the statusline badge differ from /caveman-stats output?▼

The badge shows a lifetime gross-savings figure intended as a glanceable summary, not a full accounting. Run /caveman-stats for the net picture that subtracts rule overhead from savings.

Related Skills

Explore More Software Engineering Skills→
tkoguttkogut
1

caveman-stats

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

Community
Intermediate
LsogodLsogod

token-report

Analyze compaction-debugger logs to quantify token savings per session.

Community
Intermediate
tankygranny05tankygranny05
2

token-cost-computation

Calculate token usage totals and estimated costs from Codex CLI and Claude Code SSE JSONL logs.

Community
Intermediate
TykodeTykode

vercel-cli

Deploy, manage, and develop Vercel projects from the command line.

Official
Intermediate