ClaudeMinotaur

A token usage and cost monitor for Claude Code sessions. Parses ~/.claude/projects/ session logs to show which tools are burning the most budget — and what to do about it.

Who needs this?

ClaudeMinotaur is useful if any of the following apply to your project:

• You use Claude Code daily and want to understand where your Anthropic bill is coming from
• You work across multiple projects and want to isolate which codebase is the most expensive to develop with AI assistance
• Your sessions feel slow or expensive but you can't tell whether it's file reads, shell commands, or code generation driving the cost
• You're planning a model migration (e.g. Sonnet → Opus) and want a cost projection before committing
• You want concrete optimization rules — not vague advice, but specific commands and file paths identified from your own session history

It reads your local ~/.claude/ logs and works entirely offline. No data leaves your machine.

Quick start

Prerequisites: Node.js 18+, Claude Code installed and used at least once.

# 1. Clone and install
git clone https://github.com/alxmss/ClaudeMinotaur.git
cd ClaudeMinotaur
npm install

# 2. Verify access to your session logs
node --import tsx/esm src/cli.ts init

# 3. See your cost breakdown (last 5 sessions)
node --import tsx/esm src/cli.ts gain

# 4. Get a prioritized action checklist
node --import tsx/esm src/cli.ts optimize

That's it. No API keys, no config files, no sign-up.

Commands

minotaur init

Verify that ClaudeMinotaur can access your Claude Code session logs.

node --import tsx/esm src/cli.ts init

Output: log directory path, total session count, project count.

minotaur gain

Rank every tool by its attributed token cost across recent sessions.

node --import tsx/esm src/cli.ts gain [options]

| Flag | Default | Description | |------|---------|-------------| | -l, --last <n> | 5 | Number of recent sessions to analyze | | -p, --project <name> | (all) | Filter by project name (substring match) | | -m, --model <id> | sonnet-3-5 | Pricing model for cost calculation | | --debug-linkage | off | Print each tool's output size linked to next-turn input cost |

Available models: sonnet-3-5 · haiku-3-5 · haiku-3 · opus-3

Examples:

# Last 5 sessions across all projects
node --import tsx/esm src/cli.ts gain

# Isolate one project, last 10 sessions
node --import tsx/esm src/cli.ts gain --last 10 --project MyProject

# What would this cost on Opus?
node --import tsx/esm src/cli.ts gain --model opus-3

# See exactly which file reads are driving next-turn costs
node --import tsx/esm src/cli.ts gain --debug-linkage --project MyProject

How cost is attributed: Each assistant turn's token cost is split equally across all tools invoked in that turn. This is the most honest model possible — the API does not expose per-tool token counts.

minotaur optimize

Run a deep diagnostic scan and generate a prioritized action checklist.

node --import tsx/esm src/cli.ts optimize [options]

Same flags as gain (--last, --project, --model). No --debug-linkage.

What it detects:

| Category | Trigger | Recommendation | |----------|---------|----------------| | Behavioral | Write calls > 20% of total turns | Switch to Edit for existing files — saves ~40% cache-write cost | | Structural | Any Bash output > 5KB | Use rtk, --stat, grep, or head to bound output | | Environmental | Top 3 most-read file paths | Add to .claudeignore or split into smaller modules |

Each diagnostic shows an estimated annual savings extrapolated from the analyzed session data.

Example:

node --import tsx/esm src/cli.ts optimize --last 5 --project MyProject

Cost Attribution Model

Token costs are attributed per assistant turn. When a turn fires multiple tools in parallel, the turn's total tokens are divided equally across those tools. This produces a "guilt by association" metric — good for identifying heavy-handed workflows, not for per-call micro-accounting.

Linkage: The --debug-linkage flag enables a second-pass analysis that joins tool_use IDs to tool_result content in the subsequent user turn. This reveals which specific file reads or command outputs are responsible for next-turn input cost spikes.

Pricing Reference

| Model | Input | Output | Cache Write | Cache Read | |-------|-------|--------|-------------|------------| | Claude 3.5 Sonnet (sonnet-3-5) | $3.00/MTok | $15.00/MTok | $3.75/MTok | $0.30/MTok | | Claude 3.5 Haiku (haiku-3-5) | $0.80/MTok | $4.00/MTok | $1.00/MTok | $0.08/MTok | | Claude 3 Haiku (haiku-3) | $0.25/MTok | $1.25/MTok | $0.30/MTok | $0.03/MTok | | Claude 3 Opus (opus-3) | $15.00/MTok | $75.00/MTok | $18.75/MTok | $1.50/MTok |

Use --model opus-3 to project worst-case costs before migrating a project to a more capable model.