context-monitor

🧠 claude-context-monitor

Stop losing work to silent context overflows.

A Claude Code plugin that watches your context window in real time, predicts when you'll hit the limit, and warns you before it's too late — then makes your /compact actually remember what matters.

Quick start · Features · How it works · Configuration · Cost · Privacy · Contributing

---

• Why this exists
• Quick start
• Features
• How the scoring works
• Smart Compact Instructions
• Architecture
• Requirements
• Installation
• Configuration
• CLI dashboard
• Hooks
• Cost
• Privacy
• Project structure
• Contributing
• Uninstalling
• License

---

Why this exists

Claude Code's context window fills up — and when it does, your session ends abruptly, mid-refactor or mid-debug. You get no warning. You just hit a wall.

Three problems, one plugin:

Problem	What it feels like	How this plugin fixes it
No warning	The session dies with no heads-up	A live token bar + desktop alerts at 70 / 85 / 95%
Bad timing	Compact too early and waste a session; too late and lose context	A semantic score tells you when — and why
Cumulative amnesia	Each /compact summarizes the last summary, so after 2–3 rounds key decisions vanish	Carry-forward memory injected into the compact prompt

The amnesia problem is well documented — see anthropics/claude-code#33212, #28721, and #3288.

---

Quick start

# 1. Add this repo as a plugin marketplace
/plugin marketplace add fomyio/claude-context-monitor

# 2. Install the plugin
/plugin install context-monitor@claude-context-monitor

# 3. Reload, then start a new session — the token bar appears immediately
/reload-plugins

That's it — the five hooks register automatically. For the semantic compact scoring, the plugin uses your existing ANTHROPIC_API_KEY (see API key); everything else works with no key.

Tip: prefer manual setup or want to disable the API eval entirely? See Installation and SETUP.md.

---

Features

1. Real-time context monitoring

Every message, the plugin injects a status line into Claude's context:

[CTX] 🟢 [████░░░░░░░░░░░░░░░░] 22.1% | 44K/200K | ~124 turns left

As the session grows, the color shifts 🟢 → 🟡 → 🔴 so you always know where you stand.

2. Smart compact recommendations

Above 45% usage, the plugin sends a lightweight fingerprint of your recent conversation to Claude Haiku (~$0.0005/call) and asks: is this prompt a continuation, or a new topic? It then scores the situation and escalates:

[CTX] 💡 Suggestion: You might want to /compact (Topic drift detected)
[CTX] ⚠️  Warning: Good time to /compact soon (Score 47)
[CTX] 🚨 URGENT: Strongly recommend running /compact now (Score 71)

3. Smart Compact Instructions — solves cumulative amnesia

When you run /compact, the plugin doesn't just tell you when — it tells Claude what to keep and what to drop, and carries the previous summary forward verbatim. See Smart Compact Instructions.

4. Desktop notifications

Native alerts (macOS osascript / Linux notify-send) at 70%, 85%, and 95% usage — so you're never caught off guard, even away from the terminal.

5. Status line integration

A real-time status bar in Claude Code's UI showing usage, turns left, cost, cache efficiency, and the active model:

🟢 [████░░░░░░░░░░░░░░░░] 22.1% · 44K/200K · ~124 turns · $0.012 · eff 74% · Opus 4.8

The model label tracks the live model and updates the moment you switch models mid-session — the context-window size shown is always the limit for the model currently in use.

---

How the scoring works

Every prompt is scored across four signals:

Signal	Points	What it measures
Token pressure	0–40	How full the context is right now
Task completion	0–20	Whether Claude's last response signals the task is done
Relevance drift	0–30	How related the new prompt is to the session (via Haiku)
Conversation age	0–10	How long since the last compact

The total drives the recommendation (all thresholds configurable):

Score	Action
0–25	🟢 Silent token bar only
26–45	💡 Suggestion
46–65	⚠️ Warning
66–79	🚨 Urgent
80+	🛑 Block prompt until compacted (opt-in via block_on_critical)

---

Smart Compact Instructions

Claude Code's native compaction summarizes the previous summary, not the original conversation — so after a few rounds, key decisions and file paths are lost. This plugin injects dynamic, context-aware instructions into the compact prompt via the PreCompact hook.

The full summary from the previous compaction is preserved verbatim under a "Historical Context" section, creating a cumulative memory chain that prevents exponential fidelity loss.

--- PREVIOUS COMPACT SUMMARY (PRESERVE VERBATIM) ---
This is a summary from a previous compaction in this session.
You MUST include this content in your new summary under a
"Historical Context" section. Do NOT discard or paraphrase it.

Session involved refactoring authentication module. Key decisions:
switched from JWT to session-based auth, updated middleware in auth.ts.

The advisor's Haiku-based drift detection marks which topics are stale (summarize aggressively) vs active (preserve in full detail).

--- TOPIC HISTORY ---
Topic shifts detected during this session:
  [1] Turn 5: auth refactor
  [2] Turn 18: API rate limiting [drifted]
  [3] Turn 34: deployment config
Active topic: deployment config (preserve in FULL detail)
Stale topics: auth refactor, API rate limiting
For stale topics: summarize AGGRESSIVELY — keep only final decisions and outcomes.

The advisor detects whether your current task is complete, partial, or in progress:

• COMPLETE → "It is SAFE to compact this task's details aggressively. Preserve only final decisions."
• IN PROGRESS → "Do NOT compact away the active debugging state or work-in-progress."
• UNRELATED topic shift → "The user has started a new topic. Previous context is STALE. Summarize aggressively."

After 3+ compactions, the prompt explicitly warns about cumulative quality degradation:

--- COMPACTION HISTORY ---
This session has been compacted 3 time(s) before.
WARNING: Multiple compactions cause cumulative context loss.
Be EXTRA thorough in preserving key decisions, file paths, and
user-stated constraints. Include the Historical Context section.

All data flows through a per-session state file — no external services, no API calls beyond the existing Haiku eval.

---

Architecture

SessionStart
  └── session-init.sh
        Creates per-session state file, checks CLAUDE.md bloat,
        sets up the statusline wrapper

Every prompt (UserPromptSubmit)
  └── check.sh (orchestrator)
        ├── analyze.js
        │     Reads the JSONL transcript → token counts
        │     Burn rate, turns left, cache efficiency, cost
        │     (prefers Claude Code's ground-truth context_window data)
        │
        ├── [if usage > 45%] advisor.js
        │     fingerprint.js → last 5 turns summary
        │     → Claude Haiku API (~$0.0005)
        │     Scores: token_pressure + task_completion + drift + age
        │     Persists: topic shifts, active_task to state
        │     Returns: score, action, recommendation text
        │
        └── stdout → injected into Claude's context
            osascript / notify-send → desktop notification

After each response (Stop hook, background)
  └── update-state.sh
        Persists token history, burn rate to state (atomic write)
        Writes tmux status file (if enabled)

/compact lifecycle
  ├── pre-compact.sh  → Smart Compact Instructions (carry-forward, topics, task, count)
  └── post-compact.sh → saves full summary for carry-forward, resets, notifies

Status line (real-time, from Claude Code UI)
  └── statusline.sh
        Reads Claude Code's native context_window data + live model
        Augments with burn rate, turns left, cache efficiency
        🟢 [████░░░] 22.1% · 44K/200K · ~124 turns · $0.012 · eff 74% · Opus 4.8

All writers read-fresh and write atomically (temp + rename), and pass every value to node via the environment — never interpolated into script source.

---

Requirements

• Node.js ≥ 18
• Claude Code
• macOS or Linux (desktop notifications use osascript / notify-send; Windows is not yet supported)
• (Optional) an ANTHROPIC_API_KEY for the Haiku relevance evaluation

---

Installation

Plugin marketplace (recommended)

/plugin marketplace add fomyio/claude-context-monitor
/plugin install context-monitor@claude-context-monitor
/reload-plugins

# Clone into your plugins directory
mkdir -p ~/.claude/plugins
git clone https://github.com/fomyio/claude-context-monitor.git ~/.claude/plugins/context-monitor

# Install dependencies
cd ~/.claude/plugins/context-monitor
npm install

# Register hooks — merge hooks/settings-snippet.json into ~/.claude/settings.json