🧠 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

🧠 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:                                 │
│ <context-status>CRITICAL: Only 13k tokens free.</context>   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ 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

💰 Token Cost

Designed to be extremely lightweight:

Most of the time: zero tokens. The hook only injects when context is actually concerning.

📏 Task Size Reference

Use this to gauge if you have enough headroom:

Rule of thumb: If free space < task estimate, run /compact first.

🔒 Security

This plugin:

• ✅ Runs locally — no external API calls
• ✅ No data collection — nothing leaves your machine
• ✅ Minimal permissions — only reads Claude Code's context data
• ✅ Open source — full code visibility
• ✅ No network access — pure shell scripts

What the scripts do:

All scripts are simple bash — inspect them yourself in /scripts/.

🔧 Technical Details

Context Window Math

Total context:        200,000 tokens
Autocompact buffer:   ~45,000 tokens (22.5%)
─────────────────────────────────────
Usable space:         ~155,000 tokens

Free space = Usable - Current usage

The status line shows free space before compaction triggers, not total context remaining.

How Claude Code Provides Data

The status line receives JSON via stdin:

{
  "context_window": {
    "context_window_size": 200000,
    "current_usage": {
      "input_tokens": 93000,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 8000
    }
  }
}

📁 Project Structure

compaction-advisor/
├── .claude-plugin/
│   ├── plugin.json           # Plugin manifest
│   └── marketplace.json      # Marketplace listing
├── commands/
│   ├── setup.md              # /compaction-advisor:setup command
│   └── test.md               # Diagnostic command
├── hooks/
│   └── hooks.json            # All hook configurations
├── scripts/
│   ├── context_status.sh     # Status line script
│   ├── inject_context.sh     # UserPromptSubmit hook
│   ├── checkpoint_advisor.sh # PostToolUse hook (mid-task)
│   ├── precompact_advisor.sh # PreCompact hook (emergency)
│   └── setup.sh              # Auto-configures settings.json
├── references/
│   └── THRESHOLDS.md         # Detailed threshold math
├── install.sh                # One-line curl installer
├── SKILL.md                  # Claude instructions
├── LICENSE                   # MIT
└── README.md

🗑️ Uninstall

Plugin Marketplace Install

/plugin uninstall compaction-advisor
rm ~/.claude/status/context_status.sh
rm ~/.claude/context_state_*.json

Curl Install

rm ~/.claude/status/context_status.sh
rm ~/.claude/inject_context.sh
rm ~/.claude/context_state_*.json

Then remove the hook from ~/.claude/settings.json.

📄 License

MIT — use it however you want.

💡 Why This Exists

Mid-task compaction is frustrating:

• You lose nuanced understanding of your codebase
• Claude has to re-read files it already knew
• Flow state is broken
• Important debugging context vanishes

Proactive compaction puts you in control:

• You decide when to compact
• You specify what context to preserve
• No surprise interruptions
• Better output quality

<p align="center"> <i>Built with Claude Code 🤖</i> </p>