Skip to content
Skills Library
AI & agents · Tool integration

setup

/setup

Verify the context-guard plugin on this machine: jq, node, whether its mod runs in this session, this session's snapshot freshness, zones.json, and every option's effective value. Seed or repair ~/.claude/context-guard/zones.json from the shipped defaults. Use when: 'set up context-guard', 'is context-guard working', a consumer reports zone unknown in a live session, or after a plugin update. Actions: check (read-only; never edits settings), apply (writes ONLY ~/.claude/context-guard/zones.json, on explicit request), apply cache-line (places the prompt-cache status-line segment; prints the sta

Licence
MIT
Last repository change
26.10.2026

Assessment and security

84/ 100Class: good
Format9 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
10
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Verify the context-guard plugin on this machine: jq, node, whether its mod runs in this session, this session's snapshot freshness, zones.json, and every option's effective value. Seed or repair ~/.claude/context-guard/zones.json from the shipped defaults. Use when: 'set up context-guard', 'is context-guard working', a consumer reports zone unknown in a live session, or after a plugin update. Actions: check (read-only; never edits settings), apply (writes ONLY ~/.claude/context-guard/zones.json, on explicit request), apply cache-line (places the prompt-cache status-line segment; prints the sta

Triggers from the description

s snapshot freshness, zones.json, and every optionset up context-guardis context-guard working

Arguments

/setup [check|apply] [defaults|cache-line]
Original author description

Verify the context-guard plugin on this machine: jq, node, whether its mod runs in this session, this session's snapshot freshness, zones.json, and every option's effective value. Seed or repair ~/.claude/context-guard/zones.json from the shipped defaults. Use when: 'set up context-guard', 'is context-guard working', a consumer reports zone unknown in a live session, or after a plugin update. Actions: check (read-only; never edits settings), apply (writes ONLY ~/.claude/context-guard/zones.json, on explicit request), apply cache-line (places the prompt-cache status-line segment; prints the sta

How it works

  1. Pre-computed context
  2. Purpose
  3. check (read-only)
  4. apply (writes only ~/.claude/context-guard/zones.json, on explicit request)
  5. apply cache-line (writes only ~/.claude/context-guard/cache-line.mjs, on explicit request)
  6. Uninstalling
  7. What this skill does not do
Original SKILL.md headings · 240 lines, 2,450 words
SKILL.md preview
---
description: "Verify the context-guard plugin on this machine: jq, node, whether its mod runs in this session, this session's snapshot freshness, zones.json, and every option's effective value. Seed or repair ~/.claude/context-guard/zones.json from the shipped defaults. Use when: 'set up context-guard', 'is context-guard working', a consumer reports zone unknown in a live session, or after a plugin update. Actions: check (read-only; never edits settings), apply (writes ONLY ~/.claude/context-guard/zones.json, on explicit request), apply cache-line (places the prompt-cache status-line segment; prints the statusLine edit)."
argument-hint: "[check|apply] [defaults|cache-line]"
user-invocable: true
disable-model-invocation: true
allowed-tools:
  - "Bash(command -v jq*)"
  - "Bash(command -v node*)"
shell: bash
---

## Pre-computed context

Three of `check`'s read-only probes run at load time. Read the values below; do not re-issue them.

`jq` (a path = present, `absent` = missing): !`command -v jq 2>/dev/null || echo "absent"`
`node` (a path = present, `absent` = missing): !`command -v node 2>/dev/null || echo "absent"`
`zones.json` contents, capped at 40 lines, or one token distinguishing an absent file from an unreadable one: !`if [ -e "$HOME/.claude/context-guard/zones.json" ]; then head -40 "$HOME/.claude/context-guard/zones.json" 2>&1 || echo "(present but unreadable)"; else echo "(absent)"; fi`

## Purpose

Narrow-write setup. The plugin's module (`hooks/register.tsx`, a Claude Code mod) writes each
session's snapshot, sends Claude the zone lines, draws the optional band row and
serves the `mcp__context-guard__status` tool. Nothing about it needs wiring, so `check` inspects
and reports PASS/FAIL/INFO with one remediation line per FAIL. The plugin also owns the machine file
`~/.claude/context-guard/zones.json`, whose schema it defines and whose values the operator may
edit; that owned writable file is what obliges an `apply`, and a bare `apply` writes nothing else.
`apply cache-line` places the one other file, the optional status-line segment.

Action routing: no argument or `check` runs the check; `apply cache-line` runs only the cache-line
section below; any other `apply` runs the zones.json section.

The code is the source of truth for its own behavior. Read `${CLAUDE_PLUGIN_ROOT}/hooks/register.tsx`
and `${CLAUDE_PLUGIN_ROOT}/scripts/context-zone.sh` when a finding depends on what they do, rather
than reciting this file. The consumer-facing constants (snapshot path pattern, staleness rule,
default zone bands, zones.json shape) are owned by
`${CLAUDE_PLUGIN_ROOT}/reference/reader-contract.md`.

## `check` (read-only)

1. **`jq`**. Read the pre-computed `jq` value. FAIL when it is `absent`: the bash resolver this
   check runs for the zone report (`${CLAUDE_PLUGIN_ROOT}/scripts/context-zone.sh`) then prints `unknown`, and `apply`
   cannot merge into an existing `zones.json`. The module and the PostCompact marker hook do not
   use jq. Remediation: install jq (<https://jqlang.org/download/>).
2. **`node`**. Read the pre-computed `node` value. FAIL when it is `absent`: the PostCompact marker
   row in `${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json` runs `node hooks/exec-bash.mjs`, and the module
   writes each snapshot by running `node lib/write-snapshot.mjs`, and Claude Code's native binary
   neither ships nor uses Node (<https://code.claude.com/docs/en/setup>). Without `node` on `PATH`
   the marker does not launch and no snapshot is written, so file readers read `unknown`; report
   that a hook that fails to launch is non-blocking, so nothing else says so. The module's zone
   lines, band row and status tool do not need `node`. Remediation: install Node.js
   (<https://nodejs.org/en/download>) and restart Claude Code. The Node claim was verified
   2026-09-29 against the setup page above; recheck when a Claude Code release note says the
   native binary bundles Node or runs hooks without it, or when that page stops saying the native
   binary needs no Node.
3. **Module state.** The module loads only where mods can.
   - **This session**: the module registers `mcp__context-guard__status` when the session starts.
     Look for that name in your own tool list, deferred tool names included. Present → PASS, the
     mod is running in this session. Absent → INFO "mods off in this session, or the status tool
     was refused by policy" (a refused registration leaves one debug-log line, "context-guard: the
     status tool could not register").
   - Run `claude --version`. Older than 2.1.287 → FAIL "mods off: Claude Code <version> is older
     than the 2.1.287 floor; older builds are unsupported". Remediation: update Claude Code.
   - A separate `claude plugin test` process never sees this session's settings (a
     `disableAllHooks` in this session's settings, `--bare`, worker crashes), so it may only say
     whether mods can load on this build, read against the troubleshoot table at the pointer
     below; never report it as this session's state.
   - Where mods are off, the plugin runs reactive-only there: no zone lines,
     no band row, no status tool and no snapshot writes; the PostCompact marker, a
     settings hook, still runs wherever settings hooks do.

   - **Pointer**: [troubleshoot: check whether mods can load](https://code.claude.com/docs/en/plugins/mods/troubleshoot#check-whether-mods-can-load)
     and [the mod doesn't load](https://code.claude.com/docs/en/plugins/mods/troubleshoot#the-mod-doesn%E2%80%99t-load).
   - **As of**: 2026-10-03, Claude Code 2.1.288; the doesn't-load anchor 2026-10-11.
   - **Recheck trigger**: that table changes a message, or the minimum version changes.
4. **Live-session snapshot freshness**. This session's id is `${CLAUDE_SESSION_ID}`. The module
   writes after every tool call, so this check's own Bash calls have each given it a chance to
   write before you read the file. Probe
   `~/.claude/context-guard/context/${CLAUDE_SESSION_ID}.json`:
   - Exists and `captured_at` is within the reader contract's 10-minute staleness window → PASS
     (zone-informed consumers get real data). Also report the zone:
     `bash "${CLAUDE_PLUGIN_ROOT}/scripts/context-zone.sh" ${CLAUDE_SESSION_ID}`.
   - Fresh but `used_percentage` or `current_usage` null → INFO: the state before the session's
     first response or right after `/compact`; the resolver correctly answers `unknown`. Not a
     defect.
   - Absent or stale while step 3 reported mods off → INFO "mods off": no module runs here to
     write it, and readers take their conservative path. Not a missing instrument and not a
     wiring defect.
   - Absent or stale while step 3 found the mod running → FAIL: the module ran but its write did
     not land. Check step 2 (`node`), then the debug log for "context-guard: snapshot write failed"
     or "context-guard: snapshot write did not run", then the permissions of
     `~/.claude/context-guard/context/`.
   - If the literal string `${CLAUDE_SESSION_ID}` appears unexpanded above, report that this
     Claude Code version lacks the substitution and consumers will take the conservative path;
     probe the newest file in `~/.claude/context-guard/context/` instead, labeled as such.
5. **zones.json state**, a read-only report over the pre-computed `zones.json` value: absent
   (shipped defaults in effect, percentage 50/75 plus the window-class token bands; valid
   zero-config state, not a defect), present and valid
   (report the bands in effect, both shapes), or present with a malformed shape (report per
   shape: the resolver validates percentage keys and `token_bands` independently and falls back
   per shape with a stderr notice; a percentage-only file without `token_bands` is valid, with
   shipped token bands silently in effect; remediation: `apply`). A `(present but unreadable)`
   token, or a `cat:` error in place of the contents, is the fourth state: the file exists and
   cannot be read, which is a defect the absent branch would hide. Report the read error and route
   the operator to the file's permissions, not to `apply`. Also report the module's keys when
   present (`approach_margin`, `actions`, `thresholds`; the reader contract's "Zones"
   section defines them); an absent or invalid one means its default, never a defect. The module
   resolves zones with the same bands from the live session, so a machine with no snapshot files
   still gets lines.
6. **Cache-line copy** (INFO only). When `~/.claude/context-guard/cache-line.mjs` exists, compare
   it byte for byte with `${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjs`: identical → INFO current;
   different → INFO stale, remediation `apply cache-line`. Absent → INFO not installed, which is
   the default and never a defect.
7. **Option posture**. Report every option, each as its own row with the value substituted below
   and what that value does. Never collapse them into one "active" status: a plugin that is
   enabled while its kill switch is off, or whose lines are off, is the exact state an operator is
   diagnosing when lines are missing.

   | Option | Value | What it does |
   |---|---|---|
   | `context_guard_hooks_enabled` | `${user_config.context_guard_hooks_enabled}` | `false` → **INERT**: the module sends no lines, and the PostCompact marker hook exits at once. Snapshot writes, the band row and the status tool continue. |
   | `model_notices` | `${user_config.model_notices}` | `false` (the default) → no lines to Claude and no operator-mode suggestions; the toast, band and writes continue. `true` sends the zone lines. |
   | `zone_report_mode` | `${user_config.zone_report_mode}` | `automatic` sends the lines to Claude; `operator` holds them in a turn a person typed and offers them as a prompt suggestion plus a notice row. |
   | `zone_line_data` | `${user_config.zone_line_data}` | The figures a line carries beside its zone (`percent`, `tokens`, `window`); `zone` alone means none. |
   | `context_guard_band` | `${user_config.context_guard_band}` | `false` (the default) leaves the band row off; `true` draws it. `/context-guard band on` or `band off` sets it for one session. |
   | `context_guard_toast` | `${user_config.context_guard_toast}` | `true` shows a toast at each zone crossing; `false` leaves only the transcript line. |

   - Any value still showing its literal `${user_config.<name>}` token (unset key, or a Claude
     Code without the substitution) → **UNKNOWN** for that row, never the default stated as fact.
     Say which source was read: the module gets every option with the `plugin.json` default filled
     in, and the PostCompact marker hook applies its own in-script default (on). The
     operator-inspectable source of truth is this plugin's `pluginConfigs` options block in the
     user `settings.json` (the hook-config-delivery convention,
     <https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/hook-config-delivery/README.md>,
     owns why the declared `default` field is not delivered to hook processes).
   - A `zone_line_data` item outside the four words reads as that option's default, and the module
     logs one transcript line naming it at session start. Report the value as invalid and the
     default as what runs.
   - A `pluginConfigs` key the plugin no longer declares (`zone_lines_enabled`, which
     `model_notices` replaced; `zone_hook_mode`, `zone_gate_grace_calls`, `zone_block_unattended`),
     or a `block` action in `zones.json` (which reads as `none`), gates nothing. Report it as INFO, safe to remove.
   - Every option acts only where step 3 found the mod running, except
     that the kill switch also turns off the PostCompact marker hook, a settings hook that can run
     where mods are off.
   - The module reads its options when it loads, and Claude Code reloads a module when its options
     change, so a changed value acts from the next event. The marker hook reads its value at session
     start.

## `apply` (writes only `~/.claude/context-guard/zones.json`, on explicit request)

Seed or refresh `~/.claude/context-guard/zones.json` from the shipped defaults
(`smart_max_used_percentage: 50`, `acceptable_max_used_percentage: 75`, and the window-class
`token_bands`, the reader contract owns these numbers; read them from
`${CLAUDE_PLUGIN_ROOT}/reference/reader-contract.md` rather than this file if they ever disagree).
The `defaults` argument changes only how a present file is treated:

1. **File absent**. Create the directory if needed and write exactly:

   ```json
   {
     "smart_max_used_percentage": 50,
     "acceptable_max_used_percentage": 75,
     "token_bands": {
       "200000": { "smart_max_tokens": 100000, "acceptable_max_tokens": 150000 },
       "1000000": { "smart_max_tokens": 128000, "acceptable_max_tokens": 500000 }
     }
   }
   ```

2. **File present**. Behavior is mode-explicit, never ambiguous:
   - `apply` (no argument): repair-only. Valid recognized band values are left untouched and
     reported; recognized keys that are missing or invalid (non-numeric, inverted, out of range; for `token_bands`, invalid per the reader contract's per-shape validity rules) are set to the
     shipped defaults. An absent `token_bands` is repaired by adding the shipped token bands
     (absence is valid zero-config for the resolver, but the seeded SSOT should carry the full
     tunable surface). An operator's custom-but-valid thresholds are never overwritten by a
     bare `apply`.
   - `apply defaults`: set all recognized band keys (both percentage keys and `token_bands`) to
     the shipped defaults explicitly. This converges forward to a known state; it is not teardown,
     and it never removes the file or any key it does not recognize.
   - Both modes **preserve every unrecognized key semantically**: same keys, same JSON values
     (the file is a shared SSOT the operator's own tools may extend). The module's own keys
     (`approach_margin`, `actions`, `thresholds`) are kept the same way. Preservation is
     value-level, not lexical: a `jq` merge reserializes the document, so formatting and escape
     spellings may normalize (`"blue"` → `"blue"`); consumers of this file must parse it as
     JSON, never depend on its raw bytes. Use `jq` to merge so the result stays valid JSON. If
     `jq` is absent while the file exists, FAIL with the jq install remediation
     (<https://jqlang.org/download/>) instead of attempting a merge, never risk clobbering the
     operator's keys with a jq-less rewrite. (Step 1's template write needs no jq.)
3. **Idempotent**, a second identical `apply` produces no content change; say so.
4. **Report exactly what was written** (old bands → new bands, unrecognized keys preserved), and
   remind that consumers re-read the file on their next zone decision. No restart needed.

`apply` never touches `settings.json`, the snapshot directory, or anything in
`~/.claude/context-guard/` other than `zones.json`.

## `apply cache-line` (writes only `~/.claude/context-guard/cache-line.mjs`, on explicit request)

Places the optional prompt-cache status-line segment at a fixed path this plugin owns, so the
operator's status line never depends on where the installed plugin's files live. Pointer: for
where those files live, see
<https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves>. As of:
2026-10-11. Recheck trigger: that section names a stable install path a status line could use.

1. **Copy** `${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjs` to
   `~/.claude/context-guard/cache-line.mjs`, creating the directory if needed. When the target is
   already byte-identical, write nothing and say so.
2. **Find the `statusLine` in effect.** Read (read-only) every settings file that can set it and
   take the one that wins by Claude Code's settings precedence; name that file to the operator. When
   the winner is managed settings, stop: the operator cannot change it, so report that and print no
   edit. When no file sets it, the target is the user `settings.json`. Pointer: for the precedence
   order and the scopes a status line can live in, see
   <https://code.claude.com/docs/en/settings#settings-precedence> and
   <https://code.claude.com/docs/en/statusline#manually-configure-a-status-line>. As of:
   2026-10-11. Recheck trigger: either section changes the scope order or where a status line may
   be set.
3. **Print the statusLine edit; never write it, and never compose it by hand.** Pipe that file
   (`{}` when it is absent) into `node "${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjs" --wire` and
   print its output as the paste-ready `statusLine` object for that same file. With an existing
   `command` it wraps that command as one quoted argument to `--after`, which runs it on the same
   input before the segment, and keeps every other `statusLine` key; with none it prints the bare
   segment. Relay its stderr note when it says the line is already wired, and show the exact
   current `command` it wrapped. On native Windows without Git Bash, say the wrapper's quoting is
   POSIX and stop rather than print an edit that would break the existing line.

   Then point the operator at this plugin README's "Prompt-cache status-line segment" section for
   what the segment needs and covers, rather than restating it here.
4. **After a plugin update**, re-running `apply cache-line` refreshes the copy; step 6 of `check`
   reports a stale one.

## Uninstalling

Uninstalling the plugin removes the cache directory, so the module stops and nothing writes new
snapshots. The operator's directory `~/.claude/context-guard/` (`zones.json`, the snapshots, the
compaction markers and, after `apply cache-line`, `cache-line.mjs`) stays. Removing it is safe once
the operator's `statusLine` no longer runs `cache-line.mjs`: restore the command `--after` wrapped,
or drop the bare segment, first. Readers then read `unknown` and take their conservative path.

## What this skill does not do

- Write the plugin cache, Claude Code user settings, or `pluginConfigs`, per the uniform setup
  contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace
  repository). Nor `settings.json` (user or project), the operator's status line command, or any
  other Claude Code settings surface; `apply cache-line` prints the statusLine edit for the operator
  to paste.
- Install `jq`, `node` or any system package.
- Write to the snapshot directory `~/.claude/context-guard/context/`; the module owns those files.
- Write anywhere outside `~/.claude/context-guard/zones.json` and, on `apply cache-line` only,
  `~/.claude/context-guard/cache-line.mjs`, including the sibling
  `rate-limit-guard` directory.
Files in this package (2)
  • SKILL.md 18 KB
  • evals/evals.json 4 KB

Versions

RepositoryScoreLicence
This page · melodic-software/claude-code-plugins84MIT
HwangSlater/harness-fit100MIT
nesquikm/dev-process-toolkit100MIT
userKael/rastro100MIT
als-apg/osprey100BSD-3-Clause
dedujeong/gemba100Apache-2.0
eigenwise/eigenwise-toolshed100MIT
awrshift/agent-memory-kit100MIT
lifecycle-innovations-limited/claude-ops100MIT

Database snapshot: 13.11.2026 · package version ccc665b48d2a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100guard
    Protect Claude Code sessions from context overflow by running a background daemon that monitors session size and auto-prunes before compaction hits. Use when the user says "guard", "protect session", "context getting long", "prevent compaction", "session management", or is…
  • 100setup-agent-guard
    Diagnose, install, and verify Agent Guard's plugin-local binary, jq and gitleaks dependencies, the active host integration, and live hook protection. Use when Agent Guard reports degraded protection, a SessionStart warning asks for setup, plugin hooks fail or appear bypassed, or…
  • 90handoff
    Write or resume a session handoff so work continues cleanly in a new Claude Code session. Use when context is around 60-70% at a task boundary, when a context-guard warning appears, when the user asks for a handoff or to "turn the session over", and when resuming from a handoff file.
  • 100apd-toggle
    Toggle claude-apd@zstevovich-plugins enabled state in CC settings without leaving the session. Use when the user asks to disable APD, turn it off, enable it, switch APD on/off, or hit a guard block they want to bypass intentionally for non-APD work. Defaults to flipping current…
  • 100refresh-plugin-cache
    This skill should be used when the user asks to "refresh the plugin cache", "update plugin cache", "sync plugin cache", "update installed plugins", "check for plugin updates", "are my plugins up to date", "is the plugin cache fresh", or "verify plugin versions". Scoped to…
  • 100cache
    Use this skill when the user asks to "enable cache protection", "block on cache miss", "avoid cache expiration cost", "/ar:cache", "protect against compaction", "cache pressure guard", "cache hit ratio threshold", or "set cache-miss threshold". Covers the /ar:cache slash command…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.