How to Check Session Token Usage Statistics with Caveman: A Complete Guide

Caveman provides a built-in caveman-stats hook that reads your active Claude Code session log and prints detailed token-usage numbers together with an estimated savings figure.

The Caveman plugin for Claude Code includes native tooling to audit how many tokens your sessions consume and how much the compression features save you. This guide walks through both command-line and interactive methods to retrieve these statistics, referencing the actual implementation in JuliusBrussee/caveman.

---

Overview of the Token Statistics System

Caveman's statistics system operates on Claude Code's native .jsonl session transcripts. The src/hooks/caveman-stats.js file implements the core aggregation logic, while src/hooks/caveman-mode-tracker.js handles the interactive prompt integration.

What Gets Measured

The statistics hook computes four primary metrics:

• Turns – the number of assistant messages processed
• Output tokens – summed from usage.output_tokens in the transcript
• Cache-read tokens – summed from usage.cache_read_input_tokens
• Estimated savings – projected tokens and cost that Caveman's compression prevented

---

Method 1: Command-Line Session Token Statistics

For manual inspection of any saved session, run caveman-stats.js directly with a path to your transcript file.

Locating Your Session File

The hook expects a .jsonl transcript. By default, Claude Code writes these to:

<CLAUDE_CONFIG_DIR>/projects/<project-name>/session.s.jsonl

You can override this with the --session-file flag.

Running the Stats Hook

node src/hooks/caveman-stats.js --session-file ~/.claude/projects/my-project/session.s.jsonl

Example output:

Turns:               2
Output tokens:       150
Cache-read tokens:   250
Est. without caveman: 1,000
Est. tokens saved:   650 (~65% of output)
Est. saved (USD):    ~$0.0097

How the Parsing Works

In src/hooks/caveman-stats.js, the parseSession function (lines 68-80) handles the heavy lifting:

• Reads the .jsonl file line-by-line
• Aggregates output_tokens and cache_read_input_tokens
• De-duplicates multi-block API responses using requestId + message.id pairs to ensure each response counts only once

---

Method 2: Interactive Session Token Statistics with /caveman-stats

While using Claude Code, type the prompt directly:

/caveman-stats

The caveman-mode-tracker.js hook intercepts this command, locates the current session file automatically, and injects the statistics into your conversation as additional context.

What You See

Caveman Stats
Turns: 2
Output tokens: 100
Cache-read tokens: 250
Est. without caveman: 1,000
Est. tokens saved: 650 (~65% of output)
Est. saved (USD): ~$0.0097

This method requires zero path configuration—the mode tracker derives the transcript location from the active Claude Code environment.

---

Understanding the Savings Calculation

The Caveman token statistics include an estimated savings figure based on your compression mode.

Compression Factors

Mode	Compression Factor	Applied In
full	0.65	COMPRESSION = { 'full': 0.65 } in caveman-stats.js

The script multiplies your actual output tokens by the inverse of this factor to project usage without Caveman. In full mode, this assumes you would have used approximately 54% more tokens (1/0.65 ≈ 1.54).

USD Cost Estimation

Lines 100-124 of caveman-stats.js define MODEL_OUTPUT_PRICE_PER_M, a lookup table for Claude model pricing. When your session uses a recognized model, the hook converts saved tokens into an approximate dollar value using current per-million-token rates.

---

Error Handling and Dependencies

The statistics hook has two hard dependencies:

1. caveman-config.js – provides readFlag, appendFlag, and mode detection utilities
2. Valid session transcript – must be readable .jsonl with proper Claude Code format

If src/hooks/caveman-stats.js cannot locate the config module, it exits with a clear error message directing you to reinstall the plugin (lines 56-63). The test suite in tests/test_caveman_stats.js validates both successful parsing and graceful degradation scenarios.

---

Key Source Files Reference

File	Purpose
src/hooks/caveman-stats.js	Core implementation: parsing, aggregation, savings estimation
tests/test_caveman_stats.js	Test suite demonstrating usage scenarios and output validation
src/hooks/caveman-config.js	Config helpers for mode flag reading
src/hooks/caveman-mode-tracker.js	Interactive prompt handler for /caveman-stats

All paths are relative to the repository root in JuliusBrussee/caveman.

---

Summary

• Use node src/hooks/caveman-stats.js --session-file <path> for command-line inspection of any archived session
• Type /caveman-stats during Claude Code use for automatic statistics injection
• The parseSession function de-duplicates multi-block responses and aggregates usage.output_tokens plus usage.cache_read_input_tokens
• Savings estimates apply a 0.65 compression factor for full mode and convert to USD using model-specific pricing tables
• All functionality depends on caveman-config.js; missing configurations trigger explicit reinstall instructions

---

Frequently Asked Questions

What file format does Caveman expect for session statistics?

Caveman requires Claude Code's native .jsonl transcript format. Each line must be a valid JSON object containing usage.output_tokens, usage.cache_read_input_tokens, and identifiers for request/message de-duplication. The parseSession function in src/hooks/caveman-stats.js validates this structure during parsing.

Why do my statistics show different savings percentages?

The savings percentage varies by Caveman mode. Only full mode applies the 0.65 compression factor defined in caveman-stats.js. Other modes may use different factors or none at all. Check your active mode with readFlag('mode') from caveman-config.js if results seem unexpected.

Can I run statistics on a session from a different machine?

Yes. Transfer the .jsonl transcript file and run node src/hooks/caveman-stats.js --session-file <path> on any system with Node.js and the Caveman repository. The script is self-contained for parsing; only interactive /caveman-stats requires an active Claude Code environment.

What happens if my session file is corrupted?

The parseSession function handles malformed lines gracefully by skipping them and continuing aggregation. However, missing required fields (output_tokens, cache_read_input_tokens) will reduce accuracy. The test suite in tests/test_caveman_stats.js includes malformed input scenarios to verify this resilience.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}