Context-boundary hygiene for Claude Code. A Stop hook that watches your context size and forces a task-boundary checkpoint, new chat, clear, or continue, before the window quietly burns your token budget or hits auto-compaction.

Why

Claude Code doesn't warn you before a session's context balloons past the point where quality degrades, or force-compacts on its own without asking. HighWater reads real usage straight from the transcript, tracked per model, and hands the choice back to you at 55% and 88% by default, before the harness makes it for you, and it recalibrates that hard mark downward the first time it actually witnesses a real auto-compaction on your account. Every number here is yours to change, see CUSTOMIZE.md.

What's in here

• hooks/context-check.sh: a Stop hook that reads real context size from the transcript and, past a threshold, blocks the response until Claude raises the checkpoint
• CLAUDE.md.example: the rule that wires the checkpoint behavior (what it offers, how it phrases the question) into Claude's own behavior
• /refresh-context-rules: on-demand command, see COMMANDS.md
• context-check.conf.example: every threshold and toggle, commented at its default, see CUSTOMIZE.md
• tests/: a bats suite covering the hook's state machine and checking the docs' quoted percentages against the script (bats tests/)

Looking for cost-aware model routing (which subagent tier handles a task) instead of context hygiene? That's a separate tool, Bullpen, safe to install alongside this one.

Install

/plugin marketplace add reganomika/HighWater
/plugin install highwater@highwater

Sonnet 5 and Fable 5 auto-detect their 1M window from the model name, nothing to configure. On Opus with 1M enabled, set export CONTEXT_CHECK_WINDOW=1000000 first, the transcript can't reveal your plan so it still defaults to 200K there. Full instructions, including the no-plugin-system path, what happens to chats you already have open, and how to disable or remove it: INSTALL.md.

Docs

• COMMANDS.md: the one slash command, with a real output example
• INSTALL.md: both install paths, restart caveats, uninstall
• CUSTOMIZE.md: every threshold and toggle, how to set them, how to verify what's active
• FAQ.md: common questions and corner cases
• CHANGELOG.md: notable changes, versioned per plugin.json
• CONTRIBUTING.md: running the tests, what a PR needs, versioning

License

MIT, see LICENSE.