Context Guardian

Graceful context wind-down with session handoff for Claude Code.

Quick Start

npx context-guardian

That's it. One command. The installer copies two hook scripts to ~/.claude/hooks/ and configures your settings.json with a statusline and a PostToolUse hook. It merges with your existing settings -- nothing is overwritten.

To install for the current project only (instead of globally):

npx context-guardian --local

What You Get

After installation, your Claude Code statusline shows a live context usage bar:

Claude Opus 4.6 | my-project  ████████░░ 78%      <- normal (green)
Claude Opus 4.6 | my-project  █████████░ 85%      <- wind down (orange)
Claude Opus 4.6 | my-project  💀 ██████████ 96%   <- emergency (red+blink)

As context fills up, Claude receives escalating warnings that shift its behavior:

• At 80% -- Wrap up current work, avoid starting new tasks.
• At 85% -- Finish in-progress work only, no new work.
• At 95% -- Stop immediately. Write a handoff file with what was done, what remains, and the exact prompt to continue. Suggest /clear.

The result: every session ends with a handoff file. No work lost, no context wasted.

Uninstall

npx context-guardian --uninstall
npx context-guardian --uninstall --local

The Problem

Claude Code conversations have a finite context window. When it fills up, Claude Code auto-compacts -- silently summarizing and discarding older messages. This means:

• Work gets lost mid-task. Claude forgets what it was doing, why, and what remains.
• No warning before it happens. A productive session becomes amnesia with no transition.
• No graceful handoff. There is no mechanism for Claude to document its state or prepare a continuation plan before context is wiped.

The problem is not that context is finite -- it is that there is no protocol for winding down gracefully.

How It Works

Two scripts, two hooks -- a sensor and an actuator:

• cg-statusline.cjs (StatusLine hook) -- The sensor. Runs on every statusline render. Reads context_window.remaining_percentage from Claude Code's stdin, calculates the scaled usage percentage, persists session state to disk, and renders a colored progress bar.

• cg-context-monitor.cjs (PostToolUse hook) -- The actuator. Runs after every tool call. Reads the session state and, when a threshold is crossed, injects a system-level warning into Claude's context via additionalContext. Fires once per level transition to avoid noise.

Data Flow

Claude Code statusline refresh
  -> stdin JSON with context_window.remaining_percentage
  -> cg-statusline.cjs calculates scaled used%
  -> Writes to ~/.claude/context-guardian/sessions/session-{id}.json
  -> Returns statusline text with visual progress bar

Claude uses any tool
  -> PostToolUse fires cg-context-monitor.cjs
  -> Reads session-{id}.json
  -> If level CHANGED (not repeated) -> injects additionalContext
  -> Claude receives the warning and acts accordingly

Key Design Decisions

• Statusline writes, PostToolUse reads. The StatusLine hook is the only one that receives context_window data from Claude Code. PostToolUse hooks do not get this data, so state is persisted to a file that the PostToolUse hook reads. This two-file architecture is the core of the plugin.

• Scaled percentage. Context usage is scaled so that 100% on our bar means Claude has only 5% of its raw context remaining. This gives the user a percentage that matches their intuition ("100% means full") while leaving a small safety margin.

• One-shot warnings. Each level fires exactly once. Crossing a threshold triggers one notification; re-notification only occurs when the next threshold is crossed. This prevents spam while ensuring every transition is communicated.

• Advisory, not blocking. The plugin never executes /clear or /compact automatically. It injects messages that Claude reads and acts on. The user makes the final call.

• claude-mem detection. At Level 3, the plugin checks if claude-mem is installed. If yes, the emergency message notes that persistent memory is active. If not, it emphasizes that everything must be written to the handoff file.

Alert Levels

| Level | Threshold | Action | |-------|-----------|--------| | 0 | < 80% | Normal operation | | 1 | >= 80% | Wrap up current work, avoid starting new tasks | | 2 | >= 85% | Finish in-progress work only, no new work | | 3 | >= 95% | Write handoff summary and suggest /clear |

Levels are one-way during a session -- once escalated, the level never drops back down.

Session Data

All state is stored in ~/.claude/context-guardian/:

• sessions/ -- Per-session state files (current alert level, context percentage, timestamps). Auto-cleaned after 24 hours.
• handoffs/ -- Handoff summaries written by Claude at Level 3.

This directory lives outside any repository. Context Guardian never reads or writes files in your project.

Dependencies

None. Pure Node.js with no external packages. Uses only fs, path, and os from the standard library.

Compatibility

Context Guardian operates independently through its own hooks and state directory. It works alongside other Claude Code plugins -- claude-mem, KanClaw, or any combination -- without conflicts.

Note on GSD StatusLine: If you also use GSD (Get Shit Done), the installer will detect its existing statusline and warn you rather than overwriting it. Use --force to replace the GSD statusline with Context Guardian's. The PostToolUse warning hook works regardless of which statusline is active, as long as one writes the session state file.

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request. Bug reports, feature requests, and documentation improvements are all appreciated.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the tests: node --test test/*.test.js
5. Open a pull request against main

License

MIT