setup
Verify the context-usage 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-usage/zones.json from the shipped defaults. Use when: 'set up context-usage', 'is context-usage 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-usage/zones.json, and moves a directory left by the earlier plugin name, on explicit request), apply cache-line (places the prompt-cache status-line segment; prints the statusLine edit).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- shell
- bash
- description
- Verify the context-usage 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-usage/zones.json from the shipped defaults. Use when: 'set up context-usage', 'is context-usage 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-usage/zones.json, and moves a directory left by the earlier plugin name, on explicit request), apply cache-line (places the prompt-cache status-line segment; prints the statusLine edit).
- allowed-tools
- [ "Bash(command -v jq*)", "Bash(command -v node*)" ]
- argument-hint
- [check|apply] [defaults|cache-line]
- user-invocable
- true
- disable-model-invocation
- true
03 SKILL.md 正文
Pre-computed context
Four 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-usage/zones.json" ]; then head -40 "$HOME/.claude/context-usage/zones.json" 2>&1 || echo "(present but unreadable)"; else echo "(absent)"; fi
Leftover directory from the plugin's earlier name (its entries, or (absent)): !if [ -d "$HOME/.claude/context-guard" ]; then ls -A "$HOME/.claude/context-guard" 2>&1; echo "compaction markers: $(find "$HOME/.claude/context-guard/context" -maxdepth 1 -name '*.compacted' 2>/dev/null | wc -l)"; 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-usage__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-usage/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. Open plugin files by the ${CLAUDE_PLUGIN_ROOT}
paths this skill names, with the Read tool; never Glob or Grep the plugin directory.
check (read-only)
-
jq. Read the pre-computedjqvalue. FAIL when it isabsent: the bash resolver this check runs for the zone report (${CLAUDE_PLUGIN_ROOT}/scripts/context-zone.sh) then printsunknown, andapplycannot merge into an existingzones.json. The module and the PostCompact marker hook do not use jq. Remediation: install jq (https://jqlang.org/download/). -
node. Read the pre-computednodevalue. FAIL when it isabsent: the PostCompact marker row in${CLAUDE_PLUGIN_ROOT}/hooks/hooks.jsonrunsnode hooks/exec-bash.mjs, and the module writes each snapshot by runningnode lib/write-snapshot.mjs, and installing Claude Code does not putnodeonPATHfor them (pointer below). WithoutnodeonPATHthe marker does not launch and no snapshot is written, so file readers readunknown; report that the marker cannot launch (how Claude Code treats a hook that cannot start: Hooks, "Exit code output"), since nothing else says so. The module's zone lines, band row and status tool do not neednode. Remediation: install Node.js (https://nodejs.org/en/download) and restart Claude Code.- Pointer: Set up, "Install with npm",
for whether the installed
claudebinary uses Node.
- Pointer: Set up, "Install with npm",
for whether the installed
-
Module state. The module loads only where mods can.
-
This session: the module registers
mcp__context-usage__statuswhen 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-usage: 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 testprocess never sees this session's settings (adisableAllHooksin 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 and the mod doesn't 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.
-
-
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. Read~/.claude/context-usage/context/${CLAUDE_SESSION_ID}.jsonwith theReadtool:- Exists and
captured_atis 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_percentageorcurrent_usagenull → INFO: the state before the session's first response or right after/compact; the resolver correctly answersunknown. 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-usage: snapshot write failed" or "context-usage: snapshot write did not run", then name the permissions of~/.claude/context-usage/context/as the operator's next check; never write or touch a file there to test them. - 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-usage/context/instead, labeled as such.
- Exists and
-
zones.json state, a read-only report over the pre-computed
zones.jsonvalue: 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 andtoken_bandsindependently and falls back per shape with a stderr notice; a percentage-only file withouttoken_bandsis valid, with shipped token bands silently in effect; remediation:apply). A(present but unreadable)token, or acat: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 toapply. 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. An old key name (smart_max_*,acceptable_max_*, orsmart,acceptableordumbunderactions) is INFO: read as its new name for one release; remediationapply, which renames it. The module resolves zones with the same bands from the live session, so a machine with no snapshot files still gets lines. -
Cache-line copy (INFO only). When
~/.claude/context-usage/cache-line.mjsexists, compare it byte for byte with${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjs: identical → INFO current; different → INFO stale, remediationapply cache-line. Absent → INFO not installed, which is the default and never a defect. -
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_usage_hooks_enabled${user_config.context_usage_hooks_enabled}false→ INERT: the module sends no lines and shows no toast or crossing notice, 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.truesends the zone lines.zone_report_mode${user_config.zone_report_mode}automaticsends the lines to Claude;operatorholds 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);zonealone means none.context_usage_band${user_config.context_usage_band}false(the default) leaves the band row off;truedraws it./context-usage band onorband offsets it for one session.context_usage_toast${user_config.context_usage_toast}trueshows a toast at each zone crossing;falseleaves 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${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.jsondefault filled in, and the PostCompact marker hook applies its own in-script default (on). The operator-inspectable source of truth is this plugin'spluginConfigsoptions block in the usersettings.json(the hook-config-delivery convention, https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/hook-config-delivery/README.md, owns why the declareddefaultfield is not delivered to hook processes). - A
zone_line_dataitem 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
pluginConfigskey the plugin no longer declares (zone_lines_enabled, whichmodel_noticesreplaced;zone_hook_mode,zone_gate_grace_calls,zone_block_unattended), or ablockaction inzones.json(which reads asnone), 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.
- Any value still showing its literal
-
Directory left by the earlier name (migration). Read the pre-computed leftover value.
(absent)→ PASS. Otherwise FAIL "drift:~/.claude/context-guard/is left from the plugin's earlier name", list its entries and its compaction-marker count (each marker records a session compacted before the rename; the module still reads them there until they move), and say whether the usersettings.jsonstatusLinecommand names that directory. When it holdszones.jsonand~/.claude/context-usage/zones.jsonis absent, add the drift line "zones.json still in the earlier directory": the module and the resolver read the operator's bands from there untilapplymoves them. Remediation:apply, which moves it (see "Earlier-name directory" below). A session still running the plugin under its earlier name recreatescontext/there until it ends.
apply (writes only ~/.claude/context-usage/, on explicit request)
Earlier-name directory (migration)
Runs first, on every apply form, when ~/.claude/context-guard/ exists:
zones.json: when~/.claude/context-usage/zones.jsonis absent, move the old file there unchanged (create the directory with mode 700). When both exist and differ, keep both, report the two band sets, and stop this section: the operator chooses which to keep.cache-line.mjs: when the old directory holds one, copy${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjsto~/.claude/context-usage/cache-line.mjs. When thestatusLinein effect (found as inapply cache-linestep 2) names the old path, print the samestatusLinewith that path replaced by~/.claude/context-usage/cache-line.mjsfor the operator to paste; never write it.- Compaction markers: move each
context/<session_id>.compactedto~/.claude/context-usage/context/(create it with mode 700), never over a marker already there. A marker is written only at a compaction, so a resumed session that lost it would read as never compacted. - Remove
~/.claude/context-guard/(its snapshots are per-session state the module writes afresh) unless step 1 stopped, a marker could not move, thestatusLinestill names it, or a file in itscontext/changed within the reader contract's 10-minute staleness window (a session still running the plugin under its earlier name; a laterapplyfinishes it). Report what moved, what was copied and what was removed.
Zone bands
Seed or refresh ~/.claude/context-usage/zones.json from the shipped defaults
(light_max_used_percentage: 50, moderate_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:
-
File absent. Create the directory if needed and write exactly:
{ "light_max_used_percentage": 50, "moderate_max_used_percentage": 75, "token_bands": { "200000": { "light_max_tokens": 100000, "moderate_max_tokens": 150000 }, "1000000": { "light_max_tokens": 128000, "moderate_max_tokens": 500000 } } } -
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; fortoken_bands, invalid per the reader contract's per-shape validity rules) are set to the shipped defaults. An absenttoken_bandsis 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 bareapply.apply defaults: set all recognized band keys (both percentage keys andtoken_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 rename the old key names first, keeping their values:
smart_max_used_percentage→light_max_used_percentage,acceptable_max_used_percentage→moderate_max_used_percentage, and in eachtoken_bandsrowsmart_max_tokens→light_max_tokensandacceptable_max_tokens→moderate_max_tokens; underactions,smart→light,acceptable→moderateanddumb→heavy. Where both names are set, keep the new one and drop the old. Report each rename. - 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: ajqmerge 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. Usejqto merge so the result stays valid JSON. Ifjqis 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.)
-
Idempotent, a second identical
applyproduces no content change; say so. -
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 (beyond the earlier-name
migration's marker move), or anything in ~/.claude/context-usage/ other than zones.json and
the earlier-name migration above.
apply cache-line (writes only ~/.claude/context-usage/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.
-
Copy
${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjsto~/.claude/context-usage/cache-line.mjs, creating the directory if needed. When the target is already byte-identical, write nothing and say so. -
Find the
statusLinein 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 usersettings.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. -
Print the statusLine edit; never write it, and never compose it by hand. Pipe that file (
{}when it is absent) intonode "${CLAUDE_PLUGIN_ROOT}/scripts/cache-line.mjs" --wireand print its output as the paste-readystatusLineobject for that same file. With an existingcommandit wraps that command as one quoted argument to--after, which runs it on the same input before the segment, and keeps every otherstatusLinekey; with none it prints the bare segment. Relay its stderr note when it says the line is already wired, and show the exact currentcommandit 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.
-
After a plugin update, re-running
apply cache-linerefreshes the copy; step 6 ofcheckreports a stale one.
Uninstalling
Once the plugin is uninstalled the module stops and nothing writes new snapshots (what an uninstall
removes:
Plugins CLI reference, "What an uninstall deletes and keeps").
The operator's directory ~/.claude/context-usage/ (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). Norsettings.json(user or project), the operator's status line command, or any other Claude Code settings file;apply cache-lineprints the statusLine edit for the operator to paste. - Install
jq,nodeor any system package. - Write to the snapshot directory
~/.claude/context-usage/context/, except moving.compactedmarkers there in the earlier-name migration; the module owns those files. - Write anywhere outside
~/.claude/context-usage/zones.jsonand, onapply cache-lineor the earlier-name migration only,~/.claude/context-usage/cache-line.mjs, including the siblingrate-limitsdirectory. The migration's one removal is the earlier-name directory.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').