🧠 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:            │
                            │         │
                            │ WARNING: 25k free...    │
                            │        │
                            └─────────────────────────┘

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 ...                                   │
│                                                             │
│                                         │
│ CHECKPOINT RECOMMENDED: Context at 22k after 12 operations. │
│ Good time to /compact. Summarize progress to preserve.      │
│                                        │
│                                                             │
│ 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

🧠 Why It Works: Natural Language Understanding

This plugin doesn't use pattern matching or hardcoded rules. It simply gives Claude information and lets it reason naturally.

┌─────────────────────────────────────────────────────────────┐
│ You type: "can you do a full refactor of this codebase?"    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Hook injects context state:                                 │
│ CRITICAL: Only 13k tokens free.   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Claude sees BOTH pieces of information:                     │
│ • Context is critically low (13k free)                      │
│ • User wants a refactor (~50k tokens needed)                │
│                                                             │
│ Claude naturally reasons: 13k < 50k → warn user             │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Claude responds:                                            │
│ "Context is at 13k free. A refactor needs ~50k.             │
│  Run /compact first to avoid mid-task interruption."        │
└─────────────────────────────────────────────────────────────┘

No prediction needed. The plugin provides facts, Claude reasons about them.

This is the power of LLMs — natural understanding, not brittle pattern matching.

🚦 Status Indicators