ContextSpectre: The 'Reasoning Hygiene' Tool for Claude Code

What It Does

ContextSpectre is a command-line tool that directly reads the local JSONL session files generated by Claude Code (both the CLI and Mac app). It's not a simple cleanup utility you run when your context is full. The creator describes it as a "reasoning hygiene layer"—a tool you should open at every major decision boundary in your coding session.

Its core purpose is to give you visibility and control over what fills your 165K-token context window. Claude Code automatically compacts (summarizes and discards) older context when you approach this limit. The problem is that compaction is a blunt instrument: you lose specificity, and after multiple compactions, Claude is working from "a summary of a summary of a summary." Not all context ages equally. Exploratory reasoning—temporary, unstable thoughts—becomes "reasoning contamination" once a decision is made. This old "scaffolding" can bias future responses.

A single long session can cost hundreds of dollars, with most of that cost coming from cache reads—re-processing the same context on every turn. A debugging detour that eventually gets compacted away still cost you real money.

Visibility: See What's Filling Your Context (and What It Costs)

ContextSpectre provides a dashboard of metrics that Claude Code itself doesn't show:

• Context Meter & Compaction History: See how close you are to the limit and a timeline of past compactions.
• Session Cost Attribution: Uses actual API usage data to show your spend.
• Vector Health Score (A-F): A "signal-to-noise" grade for your session's context. The example shows a session improving from Signal F to Signal A after cleaning.
• Ghost Context Detection: Flags stale compaction summaries that reference files you've since modified.
• Per-Model Cost Breakdown: Separates costs for Opus, Sonnet, and Haiku with correct pricing.
• Decision Economics: New metrics like Cost Per Decision (CPD), Turns To Convergence (TTC), and Context Drift Rate (CDR).

You can run it in --watch mode, which polls session files every 5-30 seconds and alerts you to compactions.

Cleanup: Strip the Scaffolding, Keep the Decisions

This is where you save money. ContextSpectre offers 9 cleanup operations across 7 safety tiers. The most powerful command is clean --all.

The provided example is striking: a real $1,072 session with 7,701 messages (46.8 MB) had a Signal F grade with 159K "cleanable" tokens. One clean --all later: Signal A, only 3K cleanable tokens, and 1.5 million tokens stripped. The creator notes: "Same decisions, no scaffolding."

You can run a continuous sweep with clean --active --all --watch. There's also an expert hygiene mode that can auto-clean the safest tiers (1-3) when context pressure is detected. Crucially, all cleanup operations create a mandatory backup for a one-key undo.

How to Install and Use It Now

1. Install: It's a Rust tool. Clone the repo and build it with cargo build --release.
2. Find Your Sessions: Claude Code stores sessions in ~/.config/claude-code/sessions/ (Linux/macOS) or %APPDATA%\claude-code\sessions (Windows). Point ContextSpectre to this directory.
3. Basic Scan: Run contextspectre in your terminal to see an active sessions dashboard.
4. Analyze a Session: Use contextspectre session <session_id> to drill into a specific session's details, compaction history, and cost breakdown.
5. Clean a Session: First, analyze. Then, use contextspectre clean <session_id> --all to perform a broad cleanup. Start with --tier 1 or --tier 2 for safer, more conservative removal.

When To Use It

Integrate ContextSpectre into your workflow at natural breaks:

• After solving a complex bug and before moving to the next feature.
• When switching architectural context (e.g., from backend API work to frontend UI).
• At the end of a focused coding pomodoro to review context health.
• When you see the 'Compacting context...' message—run ContextSpectre to see what was just summarized and what stale material might still be lurking.

The tool's value is in proactive "hygiene," not just emergency cleanup when the context is full. By regularly removing the temporary reasoning scaffolding, you keep your session's signal high, reduce costs from re-processing noise, and help Claude stay on-vector for the task at hand.