context-guard
A Claude Code plugin that watches your conversation context and auto-compacts before you cross into premium-tier billing.
Cross-platform: macOS, Linux, and WSL Ubuntu on Windows.
The problem
Claude Opus 4.7's 1M-context mode flips into a premium billing tier (roughly 2x the standard rate) once a single turn's input exceeds 200K tokens. Once you cross that line, every subsequent turn in the session bills at the higher rate until you compact or clear.
Claude Code's built-in auto-compact is tied to the model's full context window (around 920K for the 1M variant), not the 200K billing threshold. So by the time native auto-compact fires, you've already been paying the premium rate for hundreds of thousands of tokens.
This plugin closes that gap.
What it does
Runs as a Stop hook after every assistant turn. Reads the session transcript, sums the most recent turn's input + cache_read + cache_create tokens, and reacts based on which tier the count falls into:
| Tier | Default | Terminal output | GUI (opt-in) |
|---|
| soft | 150K+ | Stderr line | Desktop notification |
| loud | 180K+ | ASCII banner + bell | Notification with sound |
| compact | 185K+ | Banner + auto-/compact instruction (exit 2) | Notification with sound |
| alarm | 195K+ | Banner + double-bell | Modal dialog suggesting /clear |
| over | 200K+ | Banner + double-bell | Modal: premium tier active |
/compact is the only auto-action. /clear is always a suggestion, never automatic, so you don't lose conversation history without consenting.
Desktop notifications and modal dialogs are off by default. Since the 185K tier auto-runs /compact to keep you under the billing line, the popups are belt-and-suspenders. If you want them, set CONTEXT_GUARD_NOTIFICATIONS=1 (see Configuration). Stderr output is always on.
Install
Via Claude Code marketplace (recommended)
In Claude Code:
/plugin marketplace add Blue-Corvid-Group/claude-context-guard
/plugin install context-guard
That's it. The hook is wired up automatically. Restart your Claude Code session to pick up the new hook.
Manual install
If you'd rather install from a local clone:
git clone https://github.com/Blue-Corvid-Group/claude-context-guard.git ~/code/claude-context-guard
Then in Claude Code:
/plugin install ~/code/claude-context-guard
Requirements
All platforms:
bash, python3, jq (standard on macOS and Ubuntu)
That's it for default behavior. The plugin's core features (terminal warnings + auto-/compact at 185K) work everywhere with just those three.
Only if you opt into GUI alerts via CONTEXT_GUARD_NOTIFICATIONS=1:
Configuration
All settings are environment-variable configurable. Set them in your shell profile (~/.bashrc, ~/.zshrc, or equivalent):
# Enable desktop notifications and modal dialogs (off by default)
# The 185K auto-/compact already prevents the billing problem; turn this on
# only if you want extra alerting on top of terminal output.
export CONTEXT_GUARD_NOTIFICATIONS=1
# Disable the plugin entirely
export CONTEXT_GUARD_DISABLE=1
# Change the premium-tier threshold (default 200000)
# Useful if you're on a different model or pricing structure
export CONTEXT_GUARD_THRESHOLD=200000
# Override individual tier thresholds (defaults shown)
export CONTEXT_GUARD_SOFT=150000
export CONTEXT_GUARD_LOUD=180000
export CONTEXT_GUARD_COMPACT=185000
export CONTEXT_GUARD_ALARM=195000
export CONTEXT_GUARD_OVER=200000
How auto-compact works
When the 185K tier fires, the hook exits with code 2 and prints an instruction to stderr. Claude Code's Stop hook contract treats exit-2 as "block the turn end and feed the stderr text back to Claude as a new instruction." Claude then runs /compact, which summarizes the conversation and frees up context. The next turn lands well under 200K.
Blue-Corvid-Group
JuliusBrussee
thedotmack
xrf9268-hue
alirezarezvani