# Watch Cortana

> Use when the user asks to "monitor usage limits", "auto handoff before I run out", "warn me at 92%", "save the session before the limit", "hand off automatically", or wants to install, configure or debug the usage watcher. Installs hooks — the monitoring is done by those hooks, not the model, and the handoff document itself comes from the handoff skill. NOT for reporting current usage (use /usage) and NOT for context-compaction tuning.

- Skill: `bodish-coder/watch-cortana` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add bodish-coder/watch-cortana`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bodish-coder/watch-cortana/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bodish-coder (https://skillmd.com/u/bodish-coder)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/bodish-coder/watch-cortana

---


# 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:

1. **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.
2. **Sync the board** — `skillator:tickets-zordon` over `TICKETS.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.
3. **Write the doc** — `skillator:handoff-cortana`, with a status table that matches
   `TICKETS.md` ticket-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`:

```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.
- `-Then` is 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):

```json
{"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_PCT` env var (default `92`). Set it in
  `settings.json` under `env` to make it stick.
- **Where the handoff lands** — decided by the `handoff-cortana` skill (`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`. A `CLAUDE_CONFIG_DIR` profile
  (`~/.claude-work`, `~/.claude-bodish`, …) is a separate install: arming
  `~/.claude` arms nothing else. Wire every profile you actually code in, and
  point `-Then` at that profile's own statusline command. Each profile keeps
  its own flag files too (`$CLAUDE_CONFIG_DIR/handoff-watch/`), and `check` /
  `level` read 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
  as `statusLine`, or this Claude Code build predates the `rate_limits` statusline
  field (2.0.44+).
- **Statusline went blank** — the `-Then` command 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` — the `TICKETS.md` board the handoff is reconciled against.
- `skillator:resume-cortana` — executes it in the next session.

