clauditor

The problem

Every turn in a Claude Code session re-sends your entire conversation history to the API. A fresh session sends ~20k tokens per turn. A 200-turn session sends ~200k per turn. Same work, 10x more quota.

Turn    1: ██ 20k tokens
Turn   50: ██████████ 100k tokens
Turn  200: ████████████████████ 200k tokens
Turn  500: ██████████████████████████████████████████ 400k tokens

This is why your session limit gets hit in 20 minutes. Not because of a bug — because sessions grow linearly and nobody tells you to start fresh.

The solution

clauditor monitors your session size and blocks Claude when you're wasting quota, saving your progress so you can start fresh without losing context.

╔══════════════════════════════════════════════════════════════╗
║  clauditor: Session using 9x more quota than necessary      ║
╚══════════════════════════════════════════════════════════════╝

This session is burning 9x more quota per turn (170k vs ~20k tokens/turn).
Your progress has been saved and won't be lost.

Run `claude` to start a fresh session at ~20k tokens/turn instead of 170k.
In the new session, just say "continue where I left off".

When you type "continue" in the new session, clauditor shows your saved sessions and tells you exactly what to type:

╔══════════════════════════════════════════════════════════════╗
║  clauditor: 2 recent sessions found                        ║
╚══════════════════════════════════════════════════════════════╝

  1. (5m ago) Notion backfill — populating database with User Email
     → read ~/.clauditor/sessions/.../1234.md and continue where I left off

  2. (30m ago) feat/variable-agent — migrating from ResponsesApi
     → read ~/.clauditor/sessions/.../5678.md and continue where I left off

Copy one of the → lines above, or type something else to start fresh.

Install

npm install -g @iyadhk/clauditor
clauditor install

That's it. Two commands. clauditor registers hooks into Claude Code and runs in the background. No dashboard needed. No config needed.

Also works with npx (no global install):

npx @iyadhk/clauditor install

Hooks are registered to run via npx automatically.

Requires Node.js 20+.

Supported platforms: Claude Code CLI, VS Code extension, JetBrains extension. Does not work with Claude Code on the web (claude.ai/code).

Known limitation: The "continue" prompt block works reliably in the CLI. In the VS Code extension, the UserPromptSubmit hook may not fire consistently — context is still injected via SessionStart but Claude may not always announce it. This is a Claude Code bug, not a clauditor issue.

How it works

clauditor registers 6 hooks into Claude Code:

UserPromptSubmit — blocks before tokens are wasted

Before Claude processes your prompt, clauditor checks two things:

1. Waste factor — if the session is burning too much quota, it blocks with exit code 2.
2. "Continue" detection — if you type "continue", "resume", "pick up where I left off", etc., it blocks with your saved session choices and copyable prompts.

Waste factor = current tokens/turn ÷ baseline tokens/turn

  1x = efficient (fresh session)
  5x = growing
 10x = blocked — start fresh

PostToolUse — blocks during autonomous work

When Claude is working autonomously (editing files, running commands), there's no user prompt to intercept. The PostToolUse hook catches this — after each tool call, it checks the waste factor and blocks if too high.

Uses exit code 2, which Claude Code treats as a blocking error. Claude acknowledges it, writes a handoff summary, and stops.

Also detects: cache degradation, token spikes, resume anomalies, edit thrashing, and buggy Claude Code versions (2.1.69-2.1.89 have a known cache bug that burns 10-20x tokens).

PreCompact — saves context before compaction

Fires at the exact moment before Claude Code compacts your context. Saves session state as a fallback in case PostCompact doesn't fire.

PostCompact — captures Claude's own session summary

Fires after compaction. Receives compact_summary — Claude's own LLM-generated summary of the session, created while it still had full context. This is dramatically richer than mechanical extraction because Claude knows the reasoning, blockers, and plan.

SessionStart — injects previous session context

When you start a new session, clauditor reads saved handoff files for this project and injects them into Claude's context. If multiple sessions exist (last 24h), Claude presents the choice.

Stop — blocks infinite loops

When Claude repeats the same tool call 3+ times with identical input and output, the Stop hook blocks it.

Real data

From a real user's Claude Code usage over 7 days:

  TURNS  BASE   NOW   WASTE  TOKENS
  ──────────────────────────────────────────────────────────
    317   21k  417k  20.1x    73M  ████████████████████
    576   28k  401k  14.5x   116M  ███████████████
    172   23k  249k    11x    25M  ███████████
    164   26k  220k   8.6x    21M  █████████
    230   28k  218k   7.8x    31M  ████████
    ...
  ──────────────────────────────────────────────────────────
  37 sessions · 418M tokens total
  15 sessions burned 5x+ more quota than necessary

  clauditor impact
  With rotation on all sessions: 157M tokens instead of 418M
  Potential savings: 261M tokens (62% less quota)

Dashboard (optional)

clauditor watch

── clauditor ──  4 sessions + 3 subagents (last 12h)

 LAST 7 DAYS
 37 sessions · 15 burned 5x+ quota
 Worst: api/service (317 turns, 20.1x waste — 21k→417k/turn)
 With rotation: 157M tokens instead of 418M (62% savings)

 api-service (feat/variable-agent)  opus-4-6 · 239 turns

 Waste factor: 8x  BLOCKED — start a fresh session
 ██████████████████████████████
 Started at 20k/turn → now 153k/turn (8x more quota per turn)

 Cache: 98%  Turns: 239  ~$64 API est.

Peak vs off-peak analysis

clauditor time

Shows token costs by hour of day to detect if peak hours burn more quota:

  Token Usage by Hour — last 7 days
  ──────────────────────────────────────────────────────────
  10:00    98k/turn   304 turns  cache  92%  ███████████
  14:00   124k/turn   289 turns  cache  96%  ██████████████
  18:00   164k/turn   275 turns  cache  98%  ██████████████████
  ──────────────────────────────────────────────────────────
  Peak (9am-5pm):    114k avg tokens/turn
  Off-peak:          154k avg tokens/turn

All commands

| Command | Description | |---|---| | clauditor | Show quota report (default) | | clauditor install | Register hooks into Claude Code (one-time) | | clauditor uninstall | Remove hooks | | clauditor watch | Live dashboard showing waste factor | | clauditor report | Quota usage report with waste bars | | clauditor share | Copy-pasteable summary for social media | | clauditor time | Token usage by hour of day (peak vs off-peak) | | clauditor sessions | See where your tokens went | | clauditor status | Quick health check (no TUI) | | clauditor impact | Lifetime stats | | clauditor activity | Recent actions log | | clauditor stats | Historical usage analysis | | clauditor doctor | Scan for cache bugs | | clauditor calibrate | Auto-calibrate rotation threshold | | clauditor suggest-skill | Find repeating workflows |

Audit-only mode (no hooks)

Don't want clauditor to block or modify your sessions? Skip clauditor install and use it as a read-only analytics tool:

npm install -g @iyadhk/clauditor
clauditor report      # see waste across all sessions
clauditor time        # peak vs off-peak token analysis
clauditor sessions    # per-session breakdown
clauditor doctor      # scan for cache bugs
clauditor share       # copy-pasteable summary

These commands read your session JSONL files directly. No hooks registered, no session modifications, no side effects.

Works alongside other tools

clauditor operates at the session boundary layer — it monitors waste and rotates sessions. Other tools work at different layers and are fully compatible:

| Tool | Layer | What it does | Conflicts? | |---|---|---|---| | Headroom | API proxy | Compresses tool output tokens (~34% savings per turn) | No — works at HTTP level | | MemStack | Persistent memory | SQLite + vector DB for cross-session knowledge | No — uses skills + rules | | Claude Workspace Optimizer | Static workspace | Audits CLAUDE.md and memory files for bloat | No — runs before sessions |

You can run all of them together. clauditor handles when to rotate; the others optimize what happens within a session.

Configuration

Everything works out of the box. One config file at ~/.clauditor/config.json:

{
  "rotation": {
    "enabled": true,
    "threshold": 100000,
    "minTurns": 30
  },
  "notifications": {
    "desktop": true
  }
}

| Setting | Default | Description | |---|---|---| | rotation.enabled | true | Enable/disable session rotation | | rotation.threshold | 100000 | T