context-guard

Reviewed at commit c527c78 New version, not yet reviewed

Per-session context-window observability. A mod writes each session's context-window figures to a snapshot file and tells Claude its context zone (smart…

What we checked

Measures how full the context window is and shows a toast and a transcript line when the session moves into a worse zone (light, moderate or heavy); telling Claude the zone as well is an option that is off by default. It saves the figures to small files under ~/.claude/context-guard, and its setup skill can copy an optional prompt-cache status-line script there. No network calls.

Review details

Static review of the source at the pinned commit; not run. Full re-review of version 5.0.6 (the diff since 8794d87 is too large for a delta review). Read in full: plugin.json, hooks.json, register.tsx, exec-bash.mjs, post-compact-mark.sh, payload.sh, zone.ts, write-snapshot.mjs, cache-line.mjs, check-mod-load.sh and the setup skill; context-zone.sh (a read-only jq resolver) was read by its header and searched; the fixtures and test files were not read. hook-utils.sh (249 KB, sourced by the PostCompact script) is not in the bundle and was checked in the clone: its top level only sets variables, hook::emit_telemetry was read in full, and a search for network, eval and install commands found nothing the PostCompact path uses. Hooks: session.start (registers the read-only mcp__context-guard__status tool and the /context-guard command), session.end, session.compact, prompt.submit and tool.call (append zone lines to the prompt context or tool result only with the model_notices option on, off by default; tool.call also answers its own status tool), session.measure, turn.start and turn.complete (a 15 s timer keeps the snapshot fresh; operator mode offers the lines as a prompt suggestion via $.prompt.suggest), command.run for /context-guard (status, band row on or off) and ui.render AbovePrompt (optional band row and notice). The earlier opt-in blocking mode (denying edits in the worst zone) and the SessionStart node check were removed; a block action in zones.json now reads as none. Runtime calls: $.session.usage, $.fs stat/read of ~/.claude/context-guard/zones.json and the compaction marker, $.process.run of node lib/write-snapshot.mjs (writes a 0600 JSON snapshot of context percentage and token counts to ~/.claude/context-guard/context/<session>.json, at most once per 60 s when unchanged, and hourly prunes that folder's files older than 14 days), $.ui.toast, $.ui.log, $.ui.invalidate, $.env for HOME, USERPROFILE, CLAUDE_CONFIG_DIR and HOOK_TELEMETRY_SINK. Shell hook: PostCompact runs post-compact-mark.sh through exec-bash.mjs (a node launcher that resolves an absolute-path bash, no flags used) and writes a small marker file next to the snapshot, pruning markers older than 14 days. If the user sets the documented HOOK_TELEMETRY_SINK variable, small JSON envelopes (zone, hook name, session id) are piped to that executable; a relative path resolves against the project root, and the value @harness-ops runs the launcher another plugin (harness-ops) keeps in its plugin data folder. The setup skill is user-invoked only (disable-model-invocation), pre-approves only command -v jq and command -v node, writes only zones.json on apply, and on apply cache-line copies cache-line.mjs to ~/.claude/context-guard and prints a statusLine edit for the user to paste without editing settings; that script, once wired, runs the user's existing status-line command first and adds a prompt-cache segment. No network, no model calls, no settings edits.

What it uses
  • Reads your prompts: no
  • Sees tool calls: yes
  • Blocks or changes tool calls: no
  • Reads or writes files: yes
  • Runs programs on your machine: yes
  • Calls the model (uses tokens): no
  • Sends data over the network: no
  • Stores data: yes
  • Shows something on screen: yes
Hooked events

Per-session context-window observability. A mod writes each session's context-window figures to a snapshot file and tells Claude its context zone (smart, acceptable or dumb, from bands in zones.json) at each crossing, approach and compaction; the person gets a toast and a transcript line. /context-guard prints status and toggles an optional band row. It answers a status tool. Optional blocking mode gates new mutating work in a blocked zone, except handoffs. A PostCompact hook leaves a marker.

Made this mod? Add a badge to your README

modsforClaude badge for context-guard

Paste this into your README. The badge says reviewed once the current version has been reviewed, and links readers to this page.

[![Listed on modsforClaude](https://modsforclaude.com/badge/context-guard.svg)](https://modsforclaude.com/mods/context-guard/)

← All mods