caveman-stats

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

Updated Mar 30, 2026
One-click install
npx skills add https://github.com/TrayMachi/dotfiles --skill caveman-stats-traymachi
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: caveman-stats
Source: https://github.com/TrayMachi/dotfiles/tree/main/agents/skills/caveman-stats
Command: npx skills add https://github.com/TrayMachi/dotfiles --skill caveman-stats-traymachi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Token usage numbers are often estimated by the model itself, which is unreliable. This Skill reads the real JSONL session log on disk to report actual input/output token counts and estimated savings versus a non-caveman baseline, eliminating guesswork. ## Core Features & Use Cases - Real Token Receipts: Parses the Claude Code session log directly so input and output token counts come from disk, not AI estimation. - Savings Baseline: Computes estimated savings versus a non-caveman baseline and reports a percentage saved. - Statusline Integration: Writes a lifetime-savings suffix file consumed by the statusline badge (e.g., ⛏ 12.4k). - Use Case: After a long coding session, run /caveman-stats to see exactly how many tokens were used and how many were saved compared to a standard session. ## Quick Start Type /caveman-stats in your Claude Code session to display the current session's real token usage and 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 in a Claude Code session?

Run /caveman-stats during the 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.

How are token savings calculated without AI estimation?

The hook parses the session log directly to count actual input and output tokens, then compares output against an estimated non-caveman baseline. The model itself never computes the numbers.

Does caveman-stats require the model to run any code?

No. The hook returns decision: "block" with the formatted stats as the reason, so the user sees the numbers immediately without the model performing any computation.

What is the statusline badge file written by caveman-stats?

Each run writes a lifetime-savings suffix file that the statusline badge reads to display cumulative savings, for example `⛏ 12.4k`.

Why does /caveman-stats show different numbers than the model reports?

Model-reported figures are estimates, while caveman-stats reads the actual JSONL session log on disk. The log-based numbers are the authoritative token counts for the session.