watch-cortana — auto-handoff at the usage limit
A skill cannot monitor anything - it is only text loaded into a turn. The watching
has to be done by the harness. This skill installs two small entry points into the
same script, then gets out of the way. Both are Claude Code hooks; codex needs
only the gate (see Codex below); for cursor/antigravity see Other hosts.
| Piece | Event | Job |
|---|---|---|
hooks/usage-watch.* probe |
statusLine |
The only place Claude Code exposes rate_limits.*.used_percentage. Records the highest percentage seen to <config dir>/handoff-watch/<session_id> - <config dir> is $CLAUDE_CONFIG_DIR when set, else ~/.claude; CLAUDE_USAGE_WATCH_DIR overrides both - then delegates to whatever statusline was already configured. |
hooks/usage-watch.* gate |
Stop |
At the end of a turn, if the recorded percentage ≥ threshold, returns {"decision":"block"} with the three-step preserve order below. |
hooks/usage-watch.* level |
none — called | Prints one line, src=<claude-code|codex|none> 5h= 7d= ctx= max=, from the same sources as check; no stdin, no .done, no threshold. relay-morpheus reads it between chain stages. |
level is a reading, not a gate. The 80 % hold that relay-morpheus places on
a chain of ticket workflows is relay's own wait (chain hold / chain wait,
references/chain.md there) and is not a handoff: nothing here fires, no
document is written, and the 92 %/90 % orders below are unchanged if a running
stage reaches them.
When it fires, Claude is told to do three things in order, so the saved state is whole rather than just a narrative:
- Drain the agents — wait for or stop any running subagent, workflow or background task, and record what it had accomplished. In-flight agent work is never left undescribed.
- Sync the board —
skillator:tickets-zordonoverTICKETS.md, statuses only (it is told not to start working open tickets — there is no budget left): close what actually landed, downgrade half-done work to in-progress, file tickets for anything found this session that has none. - Write the doc —
skillator:handoff-cortana, with a status table that matchesTICKETS.mdticket-for-ticket and a section listing the in-flight agent work from step 1 plus the exact prompt to resume it.
Both rate_limits (5-hour and 7-day windows) and context_window.used_percentage
are picked up; whichever is highest wins.
The 7-day window is its own gate, and it is different in kind. The 5-hour
window refills in hours, so crossing it is a pause and the three steps above
are the whole job. The 7-day window does not refill for days, so crossing it
ends the week's work — it fires at 97% (CLAUDE_USAGE_HANDOFF_WEEKLY_PCT,
default 97; do not stop at 90% — when 7-day quota reaches 97%, stop all agents
and create a handoff) and adds a step 4 the other
windows have no use for: after the handoff, put the next direction to the user
with AskUserQuestion as concrete options drawn from the open board and the
handoff's own next-steps, with the recommendation first and its reason in one
line. Stopping on a summary is what step 4 exists to prevent — a week is long
enough that "what now?" needs answering while the context is still loaded.
The probe records the weekly percentage to <flag>.weekly, beside the main
flag rather than inside it: the flag is read by both mirrors as bare bytes with
no line endings (A12), so a second value cannot share the file. One .done
covers both gates — the handoff is written once.
Fires once per session (a .done marker next to the flag file), and never
loops (stop_hook_active is honoured). When both gates are over, the weekly
order is the one that fires — it is the one the session needs.
Install
Use forward slashes in every path — PowerShell accepts them and it removes
all backslash-escaping from the JSON. Windows shown; on macOS/Linux use usage-watch.sh with probe/gate as
the first argument.
Add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"<SKILL>/hooks/usage-watch.ps1\" -Mode probe -Then \"<YOUR EXISTING STATUSLINE COMMAND>\""
},
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command", "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"<SKILL>/hooks/usage-watch.ps1\" -Mode gate", "timeout": 5 } ] }
]
}
}
<SKILL>is this skill's directory.-Thenis optional. Drop it if there is no existing statusline; the probe then prints nothing and the statusline is empty.- POSIX:
"command": "<SKILL>/hooks/usage-watch.sh probe '<YOUR EXISTING STATUSLINE COMMAND>'".
Codex
Codex has no statusline, so there is no probe: gate reads the usage straight
from the rollout named by the transcript_path its Stop stdin carries (last
token_count: rate_limits.*.used_percent and
last_token_usage.total_tokens / model_context_window, highest wins). Verified
live on codex-cli 0.156.1 codex exec (A83,
practice/baselines/green-codex-stop-gate.txt).
Put this in $CODEX_HOME/hooks.json (~/.codex unless CODEX_HOME is set;
a per-repo .codex/hooks.json also works in a trusted project):
{"hooks":{"Stop":[{"matcher":"","hooks":[
{"type":"command","command":"powershell -NoProfile -ExecutionPolicy Bypass -File \"<SKILL>/hooks/usage-watch.ps1\" -Mode gate","timeout":30}
]}]}}
POSIX: "command": "<SKILL>/hooks/usage-watch.sh gate". Then trust the
hook: open an interactive codex once and approve it in the hook review.
Untrusted hooks are skipped silently (--dangerously-bypass-hook-trust is for
tests only). To check it, run one turn with CLAUDE_USAGE_HANDOFF_PCT=1 in the
environment: codex prints hook: Stop Blocked and runs a second turn on the
preserve order, whose Stop arrives with stop_hook_active:true and ends it.
Same one-shot .done as Claude Code, keyed by the codex session id.
A rate_limits window with window_minutes: 10080 is the 7-day one (A98): it
gets the same weekly gate as the Claude path (90% hard stop, step-4 question),
while every shorter window and the live context still compare against the 92%
threshold.
Other hosts (cursor, antigravity)
Claude Code and codex are the hosts where a turn-end hook is confirmed to
both read the usage percentage and inject an instruction back into the turn.
The others get -Mode check / check: no stdin, reads whatever the host leaves on disk, prints
either watch-cortana: <host> <pct>% of <limit>% - ok or HANDOFF NOW followed
by the same three-step preserve order.
powershell -NoProfile -ExecutionPolicy Bypass -File <SKILL>/hooks/usage-watch.ps1 -Mode check
<SKILL>/hooks/usage-watch.sh check
Nothing calls it on a timer. It is wired by the always-on project file that
skillator:grayskull-power writes on activation (.skillator/grayskull.md,
pointed at from CLAUDE.md / AGENTS.md / GEMINI.md), which tells the agent
to run it before each non-trivial step. Fires once per session (.done marker),
same as the Claude Code gate.
The honest state per host — this is what "armed" actually means:
| Host | Usage signal | Turn-end hook that can inject | Active fallback |
|---|---|---|---|
| claude-code | statusLine rate_limits.*.used_percentage |
Stop → {"decision":"block"} |
none needed — full auto |
| codex | yes — $CODEX_HOME/sessions/**/rollout-*.jsonl, last token_count: rate_limits.*.used_percent and last_token_usage.total_tokens / model_context_window |
Stop → usage-watch.* gate, reads the session's own rollout via transcript_path; verified 0.156.1 codex exec (A83); hook must be trusted |
none needed once the hook is trusted — full auto; check still works |
| cursor | no — chats are SQLite store.db, no usage anywhere on disk |
stop hook exists (~/.cursor/hooks.json, command/prompt handlers) |
none — check prints "no usage signal on this host"; handoff is manual |
| antigravity | no | AfterAgent and PreCompress in ~/.gemini/settings.json |
PreCompress is the real trigger — context is about to be lost; wire handoff-cortana there |
Codex uses last_token_usage.total_tokens, not total_token_usage — the latter
is cumulative for the whole session and reads several hundred percent.
Codex's Stop hook — what is known. Earlier versions of this file said Codex
had no turn-end hook. That was wrong. Codex configures hooks in hooks.json, and
the event enum read out of the shipped codex.exe (codex-cli 0.147.0-alpha.6.5) is PreToolUse, PermissionRequest, PostToolUse,
PreCompact, PostCompact, SessionStart, SessionEnd, UserPromptSubmit,
SubagentStart, SubagentStop, Stop. Only command handlers run —
prompt and agent handlers are in the schema but the binary reports them "not
supported yet", as are async hooks. There is an additionalContext output field
with an additionalContextLimit, and a warning that some events cannot emit it;
the binary does not say which.
Live test, 2026-09-23, codex-cli 0.155.1, codex exec: the hook fires. A
command handler in
{"hooks":{"Stop":[{"matcher":"","hooks":[{"type":"command","command":…,"timeout":30}]}]}}
ran from both $CODEX_HOME/hooks.json and a per-repo .codex/hooks.json. The
per-repo file needs a trusted project. Both need hook trust:
--dangerously-bypass-hook-trust, or trust persisted by the interactive review.
Untrusted hooks are skipped silently. Stdin carries stop_hook_active and
last_assistant_message. Exit 2 + stderr does not continue the turn
(reported Stop Failed). stdout {"decision":"block","reason":…} does: the
reason re-enters as a <hook_prompt> and the model runs again with
stop_hook_active:true. The 0.153.2 failure (see PLATFORMS.md) is superseded.
usage-watch.* gate is now wired and verified as that handler — see Codex
above. Do not remove check: it remains the only mechanism cursor and
antigravity have.
Don't claim cursor is armed. It isn't, and no amount of scripting makes it so until Cursor writes a usage number somewhere readable.
Configure
- Threshold —
CLAUDE_USAGE_HANDOFF_PCTenv var (default92). Set it insettings.jsonunderenvto make it stick. - Where the handoff lands — decided by the
handoff-cortanaskill (docs/handoffs/by default), not here.
Verify
powershell -NoProfile -ExecutionPolicy Bypass -File <SKILL>/hooks/selftest.ps1
Prints ok. It feeds fake statusline JSON through probe/gate and asserts:
the max percentage wins, no fire below threshold, a block with the percentage
above it, no second fire, and no fire when stop_hook_active. It then runs
check for real and asserts it exits 0, says one of its three allowed lines,
and never reports over 100% (the guard against reading Codex's cumulative
total_token_usage instead of last_token_usage).
To check it live, temporarily set CLAUDE_USAGE_HANDOFF_PCT=1 and end a turn -
the handoff should be written immediately.
Troubleshooting
- Never fires in one profile but works in another — the wiring lives in
that config dir's
settings.json. ACLAUDE_CONFIG_DIRprofile (~/.claude-work,~/.claude-bodish, …) is a separate install: arming~/.claudearms nothing else. Wire every profile you actually code in, and point-Thenat that profile's own statusline command. Each profile keeps its own flag files too ($CLAUDE_CONFIG_DIR/handoff-watch/), andcheck/levelread only the current session's (CLAUDE_CODE_SESSION_ID), and only while under 3 hours old (A130). - Never fires — the statusline is where the percentage comes from. If
<config dir>/handoff-watch/<session_id>does not exist, the probe is not wired in asstatusLine, or this Claude Code build predates therate_limitsstatusline field (2.0.44+). - Statusline went blank — the
-Thencommand is wrong or missing. - Fired once, want it again — delete
<config dir>/handoff-watch/<session_id>.done. - Stale flag files — plain text, a few bytes each; delete
<config dir>/handoff-watch/whenever.
Related
skillator:handoff-cortana— writes the document this skill triggers.skillator:tickets-zordon— theTICKETS.mdboard the handoff is reconciled against.skillator:resume-cortana— executes it in the next session.