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

> Easily check session token usage statistics with Caveman. Learn how the built-in caveman-stats hook displays detailed token numbers and estimated savings for your Claude Code sessions.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js) file implements the core aggregation logic, while [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

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

```

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

### Running the Stats Hook

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

```

**Example output:**

```text
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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```text
/caveman-stats

```

The [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/tests/test_caveman_stats.js) validates both successful parsing and graceful degradation scenarios.

---

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js) | Core implementation: parsing, aggregation, savings estimation |
| [`tests/test_caveman_stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/tests/test_caveman_stats.js) | Test suite demonstrating usage scenarios and output validation |
| [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) | Config helpers for mode flag reading |
| [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-stats.js). Other modes may use different factors or none at all. Check your active mode with `readFlag('mode')` from [`caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/tests/test_caveman_stats.js) includes malformed input scenarios to verify this resilience.