compaction-advisor

🧠 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