• 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

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.

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.

# 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

{
  // Toggle the Haiku relevance evaluation (disable to save API calls)
  "relevance_eval_enabled": true,

  // Only run the eval above this usage percentage (saves cost at low usage)
  "relevance_eval_threshold_pct": 45,

  // Shell command that prints your API key (fallback when ANTHROPIC_API_KEY is unset)
  "anthropic_api_key_cmd": "cat ~/.anthropic_key",

  // Desktop notification thresholds (percentage)
  "notify_thresholds": { "info": 70, "warning": 85, "critical": 95 },

  // Compact score thresholds
  "compact_score_thresholds": {
    "suggest": 26,   // 💡 soft suggestion
    "warn": 46,      // ⚠️  warning
    "urgent": 66,    // 🚨 urgent
    "block": 80      // 🛑 block the prompt (requires block_on_critical: true)
  },

  // Set to true to hard-block prompts when score >= block threshold
  "block_on_critical": false,

  // How many recent turns to include in the relevance fingerprint
  "fingerprint_max_turns": 5,

  // Number of recent turns used for burn-rate calculation
  "burn_rate_window_turns": 4,

  // Warn if CLAUDE.md exceeds this % of the context limit
  "claude_md_bloat_threshold_pct": 15,

  // Status line integration
  "statusline_enabled": true,

  // Write context status to a file for a tmux status bar (opt-in)
  "tmux_status_enabled": false,
  "tmux_status_file": "/tmp/claude-ctx-status",

  // Where per-session state is stored
  "state_dir": "~/.claude/plugins/context-monitor/state",

  // Per-model context limits (tokens). Claude Code's live value overrides these.
  "context_limits": {
    "claude-opus-4-7": 200000,
    "claude-opus-4-6": 200000,
    "claude-opus-4-5": 200000,
    "claude-opus-4": 200000,
    "claude-sonnet-4-6": 200000,
    "claude-sonnet-4-5": 200000,
    "claude-haiku-4-5": 200000
  },

  // Per-model pricing (USD per million input tokens)
  "model_prices_per_million_input": {
    "claude-opus-4-7": 15.00,
    "claude-opus-4-6": 15.00,
    "claude-opus-4-5": 15.00,
    "claude-opus-4": 15.00,
    "claude-sonnet-4-6": 3.00,
    "claude-sonnet-4-5": 3.00,
    "claude-haiku-4-5": 0.80
  }
}

The static context_limits table is only a fallback — when Claude Code reports a live limit_tokens (e.g. a 1M-token model), the plugin uses that instead, so the bar always reflects the model actually in use.

claude-context-monitor/
├── .claude-plugin/
│   ├── plugin.json           # Plugin manifest (name, version, author)
│   └── marketplace.json      # Marketplace manifest for /plugin install
├── hooks/
│   ├── hooks.json            # Hook registrations (${CLAUDE_PLUGIN_ROOT} paths)
│   ├── settings-snippet.json # Manual install: merge into settings.json
│   ├── session-init.sh       # SessionStart — initialize session state
│   ├── check.sh              # UserPromptSubmit — main orchestrator
│   ├── update-state.sh       # Stop — persist stats after each response
│   ├── pre-compact.sh        # PreCompact — smart compact instructions
│   └── post-compact.sh       # PostCompact — save summary, reset state
├── src/
│   ├── analyze.js            # Token analyzer: reads the JSONL transcript
│   ├── advisor.js            # Scoring engine: Haiku eval + compact score
│   ├── fingerprint.js        # Context summarizer: builds the Haiku input
│   ├── statusline.sh         # Claude Code status line integration
│   ├── notify.sh             # Desktop notifications (macOS + Linux)
│   ├── dashboard.js          # CLI report (bin: context-monitor)
│   └── uninstall.sh          # Clean uninstall script
├── docs/
│   ├── HOMEPAGE.md           # Plugin homepage
│   ├── PLAN.md               # Implementation plan / roadmap
│   ├── PRIVACY.md            # Privacy details
│   └── MARKETPLACE_SUBMISSION.md
├── config.json               # User-configurable thresholds + settings
├── SETUP.md                  # API key setup guide
├── PRIVACY.md                # Privacy policy
├── LICENSE                   # MIT
└── package.json

Per-session state lives outside the repo, under ~/.claude/plugins/context-monitor/state/ (configurable via state_dir).

git clone https://github.com/fomyio/claude-context-monitor.git
cd claude-context-monitor
npm install

Branch naming

Always branch off main:

git checkout main && git pull origin main
git checkout -b feature/your-feature-name

Before submitting a PR

• npm install succeeds
• node --check src/*.js and bash -n hooks/*.sh src/*.sh pass
• All hooks run without errors in a live Claude Code session
• node src/analyze.js <transcript> <model> <session_id> returns valid JSON
• No secrets, .env files, or API keys committed
• Commits follow Conventional Commits: type(scope): description

In scope: hook improvements, platform support (e.g. Windows notifications), opt-in config features, richer dashboard output, tests for analyze.js / advisor.js.

Out of scope: breaking config.json key renames, requiring internet for core functionality, runtime deps beyond the Anthropic SDK.

Reporting issues — include your OS + Claude Code version, sample analyze.js output (redacted), your config.json (redact keys), and the exact hook output. Open an issue here.