caveman-stats

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

Updated Feb 24, 2026
One-click install
npx skills add https://github.com/marketiv-id/marketiv-web --skill caveman-stats-marketiv-id
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: caveman-stats
Source: https://github.com/marketiv-id/marketiv-web/tree/main/.qwen/skills/caveman-stats
Command: npx skills add https://github.com/marketiv-id/marketiv-web --skill caveman-stats-marketiv-id

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It removes guesswork from tracking AI token consumption by reading real usage numbers directly from the session log instead of relying on model self-estimates. ## Core Features & Use Cases - Real Token Receipts: Reads input and output token counts directly from the JSONL session log on disk. - Savings Estimation: Compares actual output tokens against an estimated non-caveman baseline to show percentage saved. - Statusline Integration: Writes a lifetime-savings suffix file consumed by the statusline badge. - Use Case: After a long working session, run the command to see exactly how many tokens were used and how many were saved compared to a standard baseline. ## Quick Start Ask the assistant to show the current session token usage and savings by invoking the /caveman-stats command.

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 in a Claude Code session?

Run the /caveman-stats command during the session. The mode-tracker hook reads the JSONL session log on disk and returns actual input and output token counts plus estimated savings versus a baseline.

How are token savings calculated without AI estimation?

Savings are computed by the hook script, not the model. It reads real token counts from the session log and compares output tokens against an estimated non-caveman baseline to derive the saved amount and percentage.

Does the model compute the token statistics itself?

No. The hook returns decision block with the formatted stats as the reason, so the numbers come entirely from the session log file. The model takes no action when the skill fires.

Where does the statusline savings badge get its data?

Each run writes a lifetime-savings suffix file that the statusline badge reads to display cumulative savings, such as a compact formatted token count next to the badge icon.

Why are the reported numbers different from what the model estimated?

Model self-estimates of token counts are unreliable. This skill bypasses estimation entirely by parsing the actual JSONL session log, so the figures reflect true recorded usage.