Caveman Stats
- 217k installs
- 93.6k repo stars
- Updated July 26, 2026
- juliusbrussee/caveman
caveman-stats is a Claude Code hook tool that displays real token usage and caveman-compression savings read from session logs.
About
caveman-stats is a hook-delivered tool that displays real token usage and compression savings for the current session. The stats read directly from Claude Code session logs, showing actual token spent and estimated savings from compressed subagent output. Developers use caveman-stats when tracking context budget across long multi-turn sessions to confirm compression effectiveness.
- Real token usage and savings tracking from session logs, not AI estimation
- Hook-delivered output that displays immediately without model computation
- Shows cumulative token impact of caveman-compressed subagent delegations
Caveman Stats by the numbers
- 217,008 all-time installs (skills.sh)
- +17,940 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #24 of 3,301 Productivity & Planning skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
caveman-stats capabilities & compatibility
- Capabilities
- token tracking · session monitoring
npx skills add https://github.com/juliusbrussee/caveman --skill caveman-statsAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 217k |
|---|---|
| repo stars | ★ 93.6k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 26, 2026 |
| Repository | juliusbrussee/caveman ↗ |
How do you see real agent token usage per session?
Track real token usage and compression savings across long development sessions
Who is it for?
Long development sessions where context management is critical and compression savings need verification
Skip if: Short conversations where token budget is abundant or AI-estimated savings are sufficient
When should I use this skill?
Mid-session to check actual token spend and verify caveman subagent compression is effective
What you get
Formatted session token receipts, estimated Caveman savings, and hook-injected usage summary.
- session token receipts
- Caveman savings estimate
By the numbers
- Caveman output compresses ~60% vs vanilla agents
Files
This skill is delivered by hooks/caveman-stats.js (read by hooks/caveman-mode-tracker.js on /caveman-stats). The model does not need to do anything when this skill fires — the hook returns decision: "block" with the formatted stats as the reason. The user sees the numbers immediately.
caveman-stats
Real session token receipts. No AI estimation.
What it does
Reads the current Claude Code session log directly and reports actual input/output token usage plus estimated savings versus a non-caveman baseline. Numbers come from the JSONL session log on disk — the model itself does not compute or estimate them. Output is injected by the caveman-mode-tracker hook, which intercepts /caveman-stats and returns the formatted stats as a blocked-decision reason.
Each run also writes a lifetime-savings suffix file used by the statusline badge (⛏ 12.4k).
How to invoke
/caveman-statsExample output
Session: 47 turns
Input: 12,304 tokens
Output: 3,891 tokens (caveman)
Baseline: 11,247 tokens (estimated without caveman)
Saved: 7,356 tokens (~65%)See also
- `SKILL.md` — hook contract and mechanics
- Caveman README — repo overview
Related skills
Grill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.645k185kGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.547k185k
Lark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.466kLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).466kLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.466kLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.465kHow it compares
Choose caveman-stats for log-derived Claude Code receipts; use general analytics when hook-based session telemetry is unavailable.
FAQ
Does caveman-stats use AI to estimate tokens?
caveman-stats reads the Claude Code session log directly via hooks/caveman-stats.js. The model does not compute numbers—the hook injects formatted receipts with decision block.
How is caveman-stats triggered?
caveman-stats fires on the /caveman-stats command. The caveman-mode-tracker.js hook reads session data and returns formatted token usage and estimated Caveman savings immediately.
Is Caveman Stats safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.