caveman-stats

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

Updated Mar 11, 2026

Search Tags:#Claude Code #token usage #log parsing #LLM operations #session telemetry #savings estimation

Ready to run

npx skills add https://github.com/selfagency/agentsy --skill caveman-stats-selfagency

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: caveman-stats
Source: https://github.com/selfagency/agentsy/tree/main/.agents/skills/caveman-stats
Command: npx skills add https://github.com/selfagency/agentsy --skill caveman-stats-selfagency

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Caveman-style workflows need trustworthy accounting of input/output tokens and real savings, but AI estimates can be inaccurate or misleading.

Core Features & Use Cases

Real token receipts from session logs: Reads Claude Code’s JSONL session log on disk to report actual input and output token counts.
Estimated savings versus a baseline: Computes savings relative to a non-caveman baseline using the recorded token receipts (no token estimation by the model).
Instant results via /caveman-stats hook: Injects formatted stats as a blocked-decision reason when the mode-tracker intercepts the request.

Quick Start

Ask your agent for the stats by sending: /caveman-stats.

Frequently Asked Questions about caveman-stats

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I check real Claude Code token usage from session logs?▼

You can check real token usage by triggering the /caveman-stats command during an interactive agent session, which reads the on-disk JSONL session log to report actual input and output token counts.

How are token savings estimated without AI computation?▼

Token savings are calculated by comparing recorded token receipts from the JSONL session log against a non-caveman baseline, completely avoiding any model-side token computation or estimation.

Do I need a specific hook to intercept token stats requests?▼

Yes, using this Skill requires a mode-tracker hook to intercept the /caveman-stats request and return a blocked decision containing the formatted stats as the reason.

Why use JSONL log parsing for LLM operations telemetry instead of model estimates?▼

JSONL log parsing is used for LLM operations telemetry because AI-generated token estimates can be inaccurate or misleading, whereas reading the on-disk session log provides trustworthy accounting of actual token usage.

Can I get session telemetry during interactive agent workflows?▼

Yes, this Skill applies during interactive agent sessions to provide accurate input and output token receipts along with savings estimation versus a non-caveman baseline for the current workflow.

What limitations exist when parsing token usage from Claude Code logs?▼

A key limitation is that the Skill requires a mode-tracker hook to intercept requests, and it entirely avoids model-side token computation, relying exclusively on the on-disk JSONL session log for accurate reporting.