🧠 Compaction Advisor
Automatic context monitoring for Claude Code — never get interrupted by mid-task compaction again.

📦 Installation
Option 1: Plugin Marketplace (Recommended)
/plugin marketplace add vignesh07/compaction-advisor
/plugin install compaction-advisor
/compaction-advisor:setup
Then restart Claude Code. That's it!
Requires: jq (JSON processor). Install with brew install jq (macOS) or apt install jq (Linux).
Option 2: One-Line Install (without plugin system)
curl -fsSL https://raw.githubusercontent.com/vignesh07/compaction-advisor/main/install.sh | bash
Then restart Claude Code.
🎯 The Problem
Claude Code auto-compacts when your context window fills up. This often happens mid-task — right when you're deep in a refactor or debugging session. You lose important context, and Claude has to rediscover things it already knew.
The worst part? By the time you see the warning, it's too late.
✨ The Solution
Compaction Advisor gives Claude real-time awareness of context usage with intelligent checkpointing. No user intervention needed.
┌────────────────────────────────────────────────────────────┐
│ │
│ Status Line: [Opus] 🟠 25k free ████████░░ │
│ │
│ You: I want to refactor the authentication system │
│ │
│ Claude: Context is at 25k free — that's tight for a │
│ refactor (~50k needed). Run /compact first to │
│ avoid interruption? │
│ │
└────────────────────────────────────────────────────────────┘
Claude automatically knows when context is low and proactively advises you.
📊 How It Works
Two lightweight components work together:
┌─────────────────┐ ┌─────────────────────────┐
│ Status Line │ │ UserPromptSubmit Hook │
│ (for you) │ │ (for Claude) │
└────────┬────────┘ └────────────┬────────────┘
│ │
▼ ▼
Displays in UI Runs on every prompt
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────────────┐
│ 🟠 25k free │────────▶│ Reads state file │
│ ████████░░ │ writes │ Injects into Claude │
└─────────────────┘ └─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Claude sees: │
│ <context-status> │
│ WARNING: 25k free... │
│ </context-status> │
└─────────────────────────┘
When context is healthy → hook stays silent (0 tokens)
🔄 Intelligent Checkpointing
During long autonomous tasks (refactors, multi-file changes), the plugin monitors progress and suggests checkpoints:
┌─────────────────────────────────────────────────────────────┐
│ Claude is working on a large refactor... │
│ │
│ [Edit] file1.ts ✓ │
│ [Edit] file2.ts ✓ │
│ [Bash] npm test ✓ │
│ [Edit] file3.ts ✓ │
│ ... 8 more operations ... │
│ │
│ <context-checkpoint> │
│ CHECKPOINT RECOMMENDED: Context at 22k after 12 operations. │
│ Good time to /compact. Summarize progress to preserve. │
│ </context-checkpoint> │
│ │
│ Claude: "Good checkpoint! I've completed: │
│ • Refactored auth module (files 1-5) │
│ • Fixed 3 failing tests │
│ • Remaining: API endpoints (files 6-10) │
│ │
│ Run /compact Focus on auth refactor progress │
│ Then I'll continue with the API changes." │
└─────────────────────────────────────────────────────────────┘
Three Levels of Protection