context-check — read real context usage, don't guess

Never estimate context usage. Read the measured number.

The number comes from a watchdog hook that fires on every UserPromptSubmit and Stop, takes the latest assistant turn's footprint (input_tokens + cache_read_input_tokens + cache_creation_input_tokens) from the session transcript, and appends one line per firing to .claude/hooks/.watchdog-<session-id>.log in the current project. Logs are per-session, so concurrent sessions never mix lines.

Requirements

jq is needed only for the bash hook. The PowerShell hook has no dependencies beyond Windows PowerShell 5.1, which ships with Windows 10 1809+ and Windows 11.

Register one hook per machine, not both — they write to the same log, so a double registration produces two lines per event. setup.ps1 warns when it sees the bash hook already registered.

Step 1 — Ensure the hook exists

Run this first, every invocation:

On macOS, Linux, WSL, or Git Bash — anywhere the Bash tool is available:

SK=$(ls -d "$HOME/.claude/skills/context-check" "${CLAUDE_PROJECT_DIR:-.}/.claude/skills/context-check" 2>/dev/null | head -n 1)
bash "$SK/scripts/setup.sh"

On native Windows without Git Bash, where the harness gives you the PowerShell tool instead of Bash, run the PowerShell installer — same behaviour, same log format:

$sk = @("$env:USERPROFILE\.claude\skills\context-check", "$env:CLAUDE_PROJECT_DIR\.claude\skills\context-check") |
      Where-Object { Test-Path $_ } | Select-Object -First 1
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$sk\scripts\setup.ps1"

It is idempotent: on an already-wired machine it prints up-to-date / already registered and changes nothing. It installs hooks/context-check.sh to ~/.claude/hooks/ (with --project, to $CLAUDE_PROJECT_DIR/.claude/hooks/), registers it for UserPromptSubmit + Stop in the matching settings.json leaving other hooks untouched, and prints the newest log line.

Act on its output:

• log: none yet / no line for this session yet — first install, or the session predates registration. The hook writes its first line on the next prompt or turn end, so there is no measured number for this moment. Say that. Do not produce a figure; the user's status line (which shows remaining) is the only stand-in until the next firing.
• MISSING / NOT registered / STALE, or a jq is required error — report the blocker verbatim. jq is a hard dependency.
• A log line is shown — continue to Step 2.

Step 2 — Read this session's number

tail -n 3 "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/.watchdog-${CLAUDE_CODE_SESSION_ID}.log"

Each line is TIMESTAMP EVENT PCT% (USED tokens, window WINDOW, MODEL). PCT% is the real percentage used against the correct window. Apply no math and no 2× correction.

Window detection: 1,000,000 for opus and for Fable pinned to the [1m] long-context model in ~/.claude/settings.json; 500,000 for plain Fable; 500,000 otherwise. CLAUDE_CONTEXT_WINDOW overrides it; CLAUDE_CONTEXT_WARN_PCT sets the warn threshold (default 70).

Step 3 — Report and advise

Report as: N% used (M% remaining) — ~USED of WINDOW tokens, model MODEL. Include remaining, because the status line frames it that way ("N% ctx" = N% remaining).

• < 70% used — healthy. Keep working; no close-out on context grounds alone.
• ≥ 70% used — finish the current unit, update whatever handoff/progress docs the project uses, prompt the user to start a fresh session.

Keep the two reasons to hand off separate: context pressure (this number) vs. a new major task (a fresh session is cheap regardless of the number). Do not cite context pressure when the reason is a clean task boundary.

Fallbacks

• $CLAUDE_CODE_SESSION_ID unset: read the newest .watchdog-*.log in the directory and say the number may belong to a sibling session.
• Newest line is stale (timestamp well before now): note that it reflects the last hook firing, not this instant.
• Project-level registration: a project settings.json hook shadows the global one. Both write the same format, so the reading is unaffected.
• Session logs older than 7 days are pruned by the hook.
• A shared .watchdog.log from a pre-per-session version is unused; delete it with setup.sh --prune-legacy.