Reasoning hygiene layer for Claude Code. Not a cleanup utility - a tool you open at every decision boundary, not just when context is full. See what fills your context, what it costs, cut what no longer matters, and carry forward what does.
A real session: 14,311 lines, 36.6 MB, 15 compactions, $291 spent. Signal F - 5.9M noise tokens drowning the actual conversation. One clean --all later: 4,728 lines, 16.9 MB, Signal A (97.9%), 2.7K noise remaining. Same decisions, same code, no scaffolding.
Claude Code conversations grow until automatic compaction triggers at ~165K tokens. Compaction summarizes and discards older context - you lose specificity, decisions blur, and reasoning drifts. After 10+ compactions, Claude is working from a summary of a summary of a summary. Not all context ages equally: exploratory reasoning (temporary, unstable) becomes reasoning contamination once a decision is made - old scaffolding biasing future responses off-vector.
A single long session can cost hundreds of dollars. Most of that is cache reads - re-processing the same context every turn. A debugging detour that gets compacted away still cost real money. Across sessions, the re-explanation tax compounds: re-stating the same architecture, re-reading the same files, re-stating the same constraints because prior sessions are inaccessible.
ContextSpectre reads Claude Code's local JSONL session files - from both Claude Code CLI and Claude for Mac - and gives you visibility and control over what fills your context window.
Visibility
- Context meter with compaction history and turn estimates
- Session cost attribution from actual API usage data
- Vector health score (A-F signal-to-noise grade)
- Compaction archaeology and epoch timeline
- Scope drift detection with dollar-cost quantification
- Ghost context detection (stale compaction summaries referencing modified files)
- Per-model cost breakdown (Opus/Sonnet/Haiku) with correct per-model pricing
- Cost velocity ($/hour) and configurable cost alert thresholds
- Active sessions dashboard with signal grade, cost, and cleanable tokens
- Status line telemetry with mtime-based caching (<2ms repeat calls)
- Watch mode with smart mtime-based polling (5s/30s cooldown), compaction alerts, and color transitions
- Session analytics log with snapshots, filtering, and CSV/JSON export
- Decision economics: Cost Per Decision (CPD), Turns To Convergence (TTC), Context Drift Rate (CDR)
Cleanup
- 9 cleanup operations across 7 safety tiers
- Batch cleanup (
clean --all) with smart continuous sweep (clean --active --all --watch) - Expert hygiene mode: opt-in auto-clean of safe tiers (1-3) on context pressure
- Live session cleanup with mtime-based race detection
- Predictive cleanup with turn-gain estimates
- Savings attribution with lifetime tracking and projected gains
- Tombstone mode (
--tombstone) for Mac-friendly cleanup that preserves scroll-back continuity - Mandatory backup with one-key undo
Navigation
- Session browser with responsive columns, client type indicators (CLI/Mac), sort cycling, and 3 width breakpoints
- Tabbed detail view (Overview, Messages, Cleanup, Ghost panels)
- Vim-style navigation (G, gg, Ctrl+d/u/f/b, Space, H/M/L) across all panels
- In-panel search (
/) with match cycling (n/N) and highlight - Help overlay (
?) with per-panel keybinding reference - Message browser with type/cost/preview per entry
- Session content search across user text, tool use, and tool results
- Conversation branches by compaction boundaries
- Reasoning phase markers (exploratory/decision/operational)
- Keep markers and commit points for intent labeling
Surgery
- Selective deletion with impact prediction
- Split surgery (extract ranges to portable markdown)
- Amputation for context deadlock recovery
- Chain repair for parentUuid integrity
- CWD-based session targeting
- Federated project identity (project aliases across directories)
Cross-session
- Project reasoning graph with structural edges
- Decision conflict detection across sessions
- Continuity index (re-explanation tax measurement)
- Project memory synthesis from session history
- CLAUDE.md sync from distilled decisions
See also: VectorPad - pre-flight vector control panel (TUI). Planned: cleanup cadence, budget protection, reasoning entropy score, decision lineage. See Roadmap.
- Not a conversation analyzer. It does not interpret semantics or judge your prompts.
- Not a Claude Code plugin. It reads local files independently - no API, no integration required.
- Not a general JSONL editor. It understands Claude Code's specific schema and nothing else.
- Not a monitoring daemon. It is a point-in-time tool you run when you need visibility.
- Not multi-vendor. It works with Claude Code's local session format (CLI and Mac). ChatGPT is server-side - there is nothing to edit.
- Not an AI summarizer. It extracts existing content. It does not generate new summaries.
- Not a cost optimizer. It exposes the hidden economics of reasoning. You decide what to do about it.
- Not a runtime hook. It does not modify Claude, intercept API calls, or alter model behavior. It reads your local session files - your data, your history.
Principiis obsta - resist the beginnings.
Keep conclusions, remove scaffolding. Exploratory reasoning is valuable while exploring. After a decision is made, it becomes dead weight that biases future responses. ContextSpectre lets you collapse exploration into decisions - that's not history editing, it's reasoning hygiene.
Mirrors, not oracles. The tool presents evidence and lets you decide. It does not auto-trim, does not guess what matters, and does not modify files without your explicit confirmation and a backup.
Structural detection over semantic guessing. Every analysis uses observable facts - token counts, file paths, compaction boundaries, parentUuid chains, usage fields. No ML, no heuristics that guess meaning, no probabilistic classification. When the tool doesn't know, it says so.
See Workflow Patterns for usage philosophy and the explore-execute-collapse cycle.
# Homebrew
brew install ppiankov/tap/contextspectre
# From source
git clone https://github.com/ppiankov/contextspectre.git
cd contextspectre && make build# One-screen session summary (auto-detects from current directory)
contextspectre summary --cwd
# See your active sessions with signal grades and cost
contextspectre active
# Quick-clean the most recent session (one command, no session ID needed)
contextspectre quick-clean
# Live cleanup on an active session (safe between Claude's turns)
contextspectre quick-clean --live
# Launch the TUI (browse all sessions, drill into details)
contextspectre
# Show detailed context stats
contextspectre stats <session-id>
# Run all cleanup operations
contextspectre clean <session-id> --all
# JSON output for scripting
contextspectre sessions --format json60-second demo: Run
contextspectreto open the TUI. Pick your largest session. Pressato select all noise. Read the impact prediction. Pressdto clean. Done.
See CLI & TUI Reference for the full command list, keybindings, and cleanup tiers.
| Term | Definition |
|---|---|
| Compaction | Auto-compression at ~165K tokens. You lose specificity. |
| Compaction epoch | Period between two compactions. Unit of reasoning history. |
| Context deadlock | Too large to continue, too large to compact. See recovery. |
| Signal / Noise | Signal = productive reasoning. Noise = progress, stale reads, tangents. |
| Reasoning contamination | Old scaffolding persisting in context, biasing future responses. |
| Vector health score | A-F grade. A = >95% signal. F = <20% signal. |
| Snowball effect | Dead tokens compound — re-read on every turn. 50K stripped early avoids millions of re-reads. |
Full glossary: Concepts & Glossary
| Phase | Status | Summary |
|---|---|---|
| 1. Entropy control | Complete | Noise removal, live cleanup, batch operations |
| 2. Reasoning economics | Complete | Cost attribution, epoch timeline, compaction archaeology |
| 3. Reasoning navigation | Complete | Scope drift, branches, phases, keep markers, vector health, ghost context |
| 4. Operational control | In progress | Federated project identity ✓, session search ✓, watch mode ✓, smart watch ✓, cost alerts ✓, savings attribution ✓, per-model cost ✓, TUI responsive columns ✓, TUI tabbed detail ✓, vim navigation + search ✓, active dashboard ✓, status line telemetry ✓, expert hygiene ✓, session analytics ✓, decision economics (CPD/TTC/CDR) ✓, onboarding polish ✓, input purity score ✓, session integrity guard ✓, Vector Control panel ✓, cleanup cadence, budget protection, session timeline |
| 5. Reasoning memory | In progress | Project reasoning graph ✓, conflict detection ✓, project memory synthesis ✓, CLAUDE.md sync ✓, decision lineage ✓, reasoning entropy |
| 6. Reasoning metrics | In progress | Repo token budget ✓, reasoning half-life ✓, reasoning efficiency map ✓, flight recorder ✓, reasoning diff ✓, throughput metrics ✓ |
| 7. Security | In progress | Vector injection detection ✓, cross-project bond ✓, signal-first status line ✓ |
- Token estimates are approximate. The 4 chars/token heuristic is close but not exact. Actual BPE tokenization varies by content.
- Cost estimates use published pricing. Dollar figures are calculated from API pricing tables, not from actual Anthropic invoices. They are close but not authoritative.
- Compaction threshold is empirical. The ~165K trigger point is observed behavior, not documented by Anthropic. It may change.
- No real-time updates. ContextSpectre reads the file once on open. It does not watch for changes during a live session.
- Claude Code format only. If Claude Code changes its JSONL schema, ContextSpectre needs updating. Works with both CLI and Mac desktop sessions.
- Large files are slow to parse. Sessions over 100MB take a few seconds to load. The parser is streaming but analysis is in-memory.
- Branch detection is structural, not semantic. Branches are identified by compaction boundaries and time gaps, not by understanding what was discussed.
| Document | Contents |
|---|---|
| CLI & TUI Reference | All commands, flags, keybindings, cleanup tiers |
| Concepts & Glossary | Full glossary, reasoning phases |
| Architecture | How it works, safety model, design decisions |
| Computation Methodology | Formula-level specification with source references |
| Context Deadlock | What it is, why it happens, how to recover |
| Workflow Patterns | Explore-execute-collapse, CLI status line |
| Session Architecture | Session storage, multi-instance safety |
MIT License - see LICENSE.
See CONTRIBUTING.md. Issues and pull requests welcome.
Built by Obsta Labs. Not affiliated with or endorsed by Anthropic.