clauditor

clauditor is an open-source CLI tool built by Iyadh Khalfallah that prevents Claude Code from burning through API quota by monitoring session token growth and automatically blocking sessions when they become wasteful. It registers hooks directly into Claude Code and runs in the background with no dashboard or configuration required to get started. The project is published under the MIT License and is available via npm or Homebrew.

What It Is

clauditor addresses a structural problem in how Claude Code works: every turn in a session re-sends the entire conversation history to the API. A fresh session costs roughly 20k tokens per turn, but a 200-turn session can cost 200k tokens per turn for the same work — a 10x waste factor. clauditor sits at the session boundary layer, tracking this growth in real time and blocking Claude before quota is exhausted, while saving enough context for the next session to pick up seamlessly.

How the Hook Architecture Works

clauditor registers 7 hooks into Claude Code to cover every scenario where tokens can be wasted:

• UserPromptSubmit — checks waste factor and "continue" intent before Claude processes any prompt; blocks with exit code 2 if the session is too expensive
• PostToolUse — catches autonomous work (file edits, commands) where there is no user prompt to intercept; also detects cache degradation, token spikes, and edit thrashing
• PreCompact / PostCompact — saves session state before compaction and merges Claude's LLM-generated summary with mechanically extracted data (files, commits, commands) after
• SessionStart — injects saved handoff files from previous sessions into Claude's context at the start of a new session
• PreToolUse — queries a local error index for known command failures and injects fixes as non-blocking context before Claude runs a command
• Stop — detects and blocks infinite loops when Claude repeats the same tool call 3+ times with identical input and output

Context Preservation Design

When clauditor blocks a session, it instructs Claude to write a structured handoff covering task, completed work, in-progress items, failed approaches, dependencies, decisions, user preferences, and blockers. This is combined with mechanically extracted data from the JSONL transcript — files modified and read, git commits verbatim, key commands and results — to give the next session the most complete possible starting point. The README cites the Size-Fidelity Paradox (arxiv.org/abs/2602.09789) as motivation for combining both LLM-generated summaries and deterministic extraction, since LLM summaries alone can suffer from knowledge overwriting and semantic drift.

Project Memory and Team Sync

clauditor builds a per-project knowledge base that records failed commands and their fixes with a confidence score that decays over a 45-day half-life. Errors are labeled confirmed, observed, inferred, or stale so Claude knows how much to trust each entry. A file tracker identifies "hot files" (5+ edits across 3+ sessions) and injects history when Claude touches them. An optional team hub (in beta) allows shared knowledge across developers: errors auto-promote from developer-scoped to team-scoped when multiple developers report the same issue.

Supported Platforms and Limitations

clauditor works with the Claude Code CLI, VS Code extension, and JetBrains extension. It does not work with Claude Code on the web (claude.ai/code), and sessions do not sync across machines. The README notes a known Claude Code bug where the UserPromptSubmit hook may not fire consistently in the VS Code extension — context is still injected via SessionStart but the "continue" prompt block is most reliable in the CLI. clauditor also detects Claude Code versions 2.1.69–2.1.89, which have a confirmed prompt caching bug causing 10–20x token consumption.

Update: v1.30.0

The latest release is v1.30.0, published in April 2026. The GitHub repository shows 428 stars and 42 forks as of the last update, with 56 published npm versions indicating active iteration. The project requires Node.js 20+ and is installable in two commands via Homebrew or npm.