# usage-guard

Adopt this skill: https://proskills.md/skills/other/shirley-xue-2025-usage-guard-skill-usage-guard

Page: https://proskills.md/skills/other/shirley-xue-2025-usage-guard-skill-usage-guard
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill/usage-guard/SKILL.md
size: 13400
sha: 2df792a83b8ff21d3c66e3b643ba0fa828b82378
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/SKILL.md

````text
---
name: usage-guard
description: Arm proactive 5-hour usage protection for long Claude Code sessions (batch, subagents, high window % at start). Daemon reads account-level 5-hour window usage (not per-session). User types /usage-guard at session start. Re-arm every sitting. If user mentions usage-guard by name, read this file and run arm.sh.
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash, Read, Write, Edit
argument-hint: [resume | your task description]
---

# usage-guard

Proactive usage guard for long Claude Code sessions (Desktop Code tab or CLI). **Invoke once at session start** before heavy batch, subagent, or overnight work — especially when the account window is already partly used.

### Why account-level monitoring matters

Each Claude session only sees its own usage. The **shared 5-hour window** is account-level — you can start at 58% in one session while another tab or earlier work already pushed the window to 94%. The daemon polls the OAuth usage API (same as Desktop Settings) so the guard sees the real window, not just this chat's view.

### Re-arm every sitting

**Arms do not survive** Desktop quit, crash, or daemon exit. At the start of **every** new sitting, run `/usage-guard` (or `/usage-guard resume` if continuing a paused task). If `arm.sh` prints `"warning"`, the previous guard was stale — proceed with the new arm.

## If the user mentions usage-guard without `/usage-guard`

When the user says "use usage-guard", "pay attention to usage limits", or names this skill but does not run the slash command:

1. **Follow this file** (you are reading it — treat that as the contract).
2. Run `arm.sh` via bash before heavy work (same as ARM MODE below).
3. Tell the user: `/usage-guard` is the normal entry point; with `disable-model-invocation` it may not show in the slash picker — **typing `/usage-guard` still works**.

Do **not** auto-arm on your own initiative without the user asking for usage protection.

## When the user invokes `/usage-guard`

### Mode detection

- If the argument is `resume` (or starts with `resume`): **RESUME MODE** (skip arm, go to section 4).
- Otherwise: **ARM MODE**.

---

## 1. ARM MODE — start guard

Run:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/arm.sh" {{ARGUMENTS}}
```

If arm fails, **stop** and tell the user to run `usage-guard doctor` in Terminal. Do not start heavy work without a successful arm.

Read `~/.usage-guard/control.json` once and confirm:

- `armed: true`
- `phase` is `normal` (or `five_hour_percent` is set) — **not** stuck on `waiting_first_poll` without a live daemon
- If arm JSON output includes `"warning"`, tell the user the prior guard was not active and this is a fresh arm
- Report go/no-go using arm JSON: `five_hour_percent`, `five_hour_reset_local`, `seconds_until_five_hour_reset`, `state` — **not** raw UTC strings
- If `weekly_percent` is present (weekly monitoring enabled in config), also report weekly % and `weekly_reset_local` / `seconds_until_weekly_reset`. **Weekly can trigger PAUSE even when 5h looks safe.**
- If present in control.json, also report **extra usage wallet**: `extra_used_credits`, `extra_monthly_limit`, `extra_utilization`, `extra_currency` (amounts are in cents; `usage-guard status` formats them), or run `usage-guard poll` for a live snapshot

**If arm JSON has `"already_armed": true`** (daemon from a prior sitting):

- **Proceed** — guard is active; do not `--force` restart unless user asks.
- **Same arc, new sitting** → `join.sh --task "label"` (not arm with a task — task is ignored on already_armed; JSON includes `task_ignored` if you tried).
- **After join** → `checkpoint.sh` writes to `sitting_session_id` automatically (stored in control.json). Do **not** use primary `session_id` unless you pass `--session-id` intentionally.
- **Continuing paused work** → `/usage-guard resume` (not join, not fresh arm).

**Decision tree:** already_armed + same sitting → proceed on `checkpoint_writes_target` | new sitting same arc → join.sh | paused task → resume | dead daemon → arm fresh

**Warmup:** right after arm, `phase` may be `waiting_first_poll` with null telemetry while the daemon fetches usage. `arm.sh` blocks up to ~45s for the first poll. If `phase` is still `waiting_first_poll` after arm returns, the daemon is warming up — **do not** start heavy subagent batches yet; re-read control.json in a few seconds. If `five_hour_percent` stays null and daemon is dead (`usage-guard status` → daemon not running), stop and run `usage-guard doctor`.

---

## 2. Session contract (inform up front — before main work)

You are now **usage-guard armed**. Follow this for the rest of this session:

### Control file (only signal that matters)

- Path: `~/.usage-guard/control.json`
- Obey **`state` only**: `RUN` = continue, `PAUSE` / `COOLDOWN` / `UNKNOWN` = stop dispatching new work.
- **Either limit can pause:** account **5-hour window** (default 90%) **or** **weekly limit** (opt-in, default 98%) — check `pause_reason` (`five_hour`, `weekly`, or `both`) in control.json.
- **`UNKNOWN`:** guard is blind (usage API returned no 5h percent for several polls) **or** the file is past `valid_until`. Do **not** start heavy work; tell user to run `claude login` or `usage-guard doctor`. Prefer `effective_state` if present — it already fails closed on staleness/blindness.
- **Freshness:** if `now` is past `valid_until` (or `stale: true`), treat as `UNKNOWN` even when `state` still says `RUN` (daemon may have died while numbers looked healthy).
- **Never** decide pause/continue from `five_hour_percent` yourself.
- **Never compare timestamps yourself** (`five_hour_resets_at`, `sleep_until`, etc.). UTC trips up models. Use precomputed fields only:
  - `seconds_until_five_hour_reset` — positive = reset not yet; negative or `five_hour_reset_pending: false` = reset time passed
  - `five_hour_reset_local` — for user-facing reports (local timezone, not UTC)
  - `weekly_percent`, `weekly_reset_local`, `seconds_until_weekly_reset` — when weekly monitoring is enabled (OAuth `seven_day` = Desktop "All models" weekly bar)
  - If `state` is **`RUN`**, continue — **do not** call percent "stale" because a UTC clock comparison looked past. Wrong timezone math caused false "reset already passed" bugs.
- **Post-reset poll lag:** `five_hour_reset_pending: false` + non-null `five_hour_percent` (e.g. 88% with reset time an hour ago) means the **old window's percent** until the daemon re-polls — not a reason to pause. Check `awaiting_post_reset_poll` and `percent_note`; trust **`state`**. Expect correction at `daemon_next_poll_at` / `daemon_next_poll_local`.
- After a **window reset**, `five_hour_percent` may be `null` until the daemon's next poll. If `state` is `RUN`, trust `state` (check `last_reset_at` if present) — do not wait for the user to return.
- **`session_check_seconds`** — recommended delay for self-paced `/loop` guard ticks while armed. During `PAUSE`/`COOLDOWN`, prefer **`sleep_until`** instead. Daemon polling is separate (`daemon_next_poll_at`).

### Checkpoint file

- Path: `~/.usage-guard/sessions/<session_id>/checkpoint.json` (session_id from control.json)
- After **every completed unit** (file, batch item, subagent return): update checkpoint (`done`, `next`, `note`).
- **Prefer bash** (atomic, no Read-before-Write harness issue):

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/checkpoint.sh" --quiet --json '{"done":["item-id"],"next":"next-item","note":""}'
```

Or flags: `checkpoint.sh --quiet --done item-id --next "next-item" --note "" --task "short label for status"`

Set **`task`** on the first checkpoint (via `/usage-guard <task>` at arm, or `checkpoint.sh --task`) so `usage-guard status` stays readable.

### Multi-session arcs (orchestrator + worker sessions)

PAUSE/RUN is **account-level** (one daemon). Checkpoints are **per `session_id`**.

- First sitting: `/usage-guard <task>` (arms daemon; sets primary `session_id` and `sitting_session_id`).
- Later sitting (daemon already running): `join.sh --task "this sitting's label"` — sets `sitting_session_id` in control.json; **all `checkpoint.sh` writes go there** until the next arm/join.
- To **share one checkpoint chain** across sittings (advanced): pass `--session-id <existing>` to checkpoint.sh explicitly.
- **join** = new sitting, new checkpoint file, same daemon. **resume** = continue a **paused** task from checkpoint (COOLDOWN/PAUSE arc), not "daemon already live."

`active_session_ids` lists all sittings; `sitting_session_id` is the active checkpoint write target.

- User can run `usage-guard status` in Terminal to see progress if Desktop UI is stuck.

### Safe checkpoints (critical for subagents / long runs)

Read control.json only at these times:

1. Before starting the main task loop
2. **Before dispatching each subagent or parallel batch**
3. After each subagent returns
4. Before starting any new multi-step tool sequence expected to take >10 minutes
5. At each `/loop` iteration dedicated to guard checks

**Never** rely on the user sending a chat message mid-run — messages queue during subagent work.

### On `state == PAUSE` or `COOLDOWN`

1. Finish the **current atomic unit** only — do not abandon mid-write.
2. Update checkpoint with `done`, `next`, clear `note`.
3. Tell the user: paused near usage limit (`pause_reason`); daemon may macOS-notify at reset. **Do not** treat that as a substitute for scheduling your own wake-up below.
4. **Do not** start new subagents, batches, or long tool chains this turn.
5. During `COOLDOWN`, use **`sleep_until`** / `seconds_until_five_hour_reset` for wait duration — do **not** poll every 5 minutes.

   **Before ending this turn**, you **must** schedule a wake-up. **Forbidden:** ending with "ping me when reset", "tell me when you're back", or "message me after the window resets".

   Pick **one** path (in order of preference):

   **A. `/loop` guard tick (preferred)** — any session type:
   ```text
   /loop Read ~/.usage-guard/control.json. If PAUSE/COOLDOWN: checkpoint if needed; sleep until sleep_until (cap 59m per iteration; chain). If RUN: continue from checkpoint next.
   ```
   Dynamic `/loop` (no interval) uses `ScheduleWakeup` internally after each iteration.

   **B. One-shot wake at reset** — if you are **not** starting `/loop`:
   - Natural language: `in N minutes, re-read ~/.usage-guard/control.json; if RUN continue checkpoint next; if still COOLDOWN schedule again`
   - Or `CronCreate` one-shot pinned to `five_hour_reset_local` (+ ~3 min margin)
   - Claude may implement this via `ScheduleWakeup` or `CronCreate` — either is fine
   - Chain: if still `COOLDOWN` after fire, schedule the next check (cap 59m steps)

   **C. Non-negotiable:** schedule *something* before ending the turn. Platform docs emphasize `ScheduleWakeup` for dynamic `/loop`, but it often works for one-shot waits too — **never** fall back to asking the user to ping you.

6. If wake scheduling fails (cron disabled, provider lacks loop-dynamic), say so explicitly and give `five_hour_reset_local` — checkpoint is still safe for `/usage-guard resume`.

### On `state == RUN` with existing checkpoint

Continue from `next` in checkpoint; skip items in `done`.

### Subagent discipline (long batch runs)

- Prefer **smaller** subagent batches when armed (e.g. 3–5 items, not 50).
- Before each dispatch: read control.json; if not `RUN`, do not dispatch.
- Main chat orchestrates workload so subagents respect the timetable — **no mid-run chat reminders**.

### Session wrap — report window delta

At session end (or before a long pause), tell the user:

- **5h window now:** `five_hour_percent`, `five_hour_reset_local`, `state`
- **Weekly limit** (if enabled): `weekly_percent`, `weekly_reset_local`, `pause_reason`
- **Extra usage wallet** (if enabled): `extra_used_credits` / `extra_monthly_limit` / `extra_utilization` from control.json, or `usage-guard status` for formatted amounts
- **Delta this sitting** if you recorded percent at arm/join (e.g. "4% → 41% this session")
- This is the most useful user-facing summary — report it even without subagents

---

## 3. Start work

If the user provided a task in `/usage-guard <task>`, begin it under the contract above using self-paced `/loop`.

Example loop prompt:

```text
/loop Read ~/.usage-guard/control.json. If PAUSE/COOLDOWN: checkpoint and stop new work; sleep until sleep_until (or session_check_seconds). If RUN: continue task from checkpoint.
```

---

## 4. RESUME MODE — `/usage-guard resume`

1. Read `~/.usage-guard/control.json` — if `state` is not `RUN`, tell user to wait (show `five_hour_reset_local` / `sleep_until_local`, or `seconds_until_*`).
2. Read checkpoint for `sitting_session_id` (or `checkpoint_writes_target` / primary `session_id` if no join).
3. Continue from `next`; dedupe using `done`.
4. Re-arm only if `armed` is false: run `arm.sh` again.

---

## 5. Limits (be honest with user)

- Cannot force-stop a running subagent from outside; guard prevents **new** work after PAUSE.
- Progress safety depends on frequent checkpoint writes.
- After force-quit Desktop, use `/usage-guard resume` in a **new** session (re-arms daemon if needed).
- Daemon exit does **not** keep the guard active — always `/usage-guard` or `/usage-guard resume` at the start of a sitting.
````

## File: skill/usage-guard/scripts/arm.sh
size: 302
sha: bde25c395f122019dff519844e3a905db44d669b
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/scripts/arm.sh

```text
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=resolve-guard.sh
source "${SCRIPT_DIR}/resolve-guard.sh"

TASK="${*:-}"
resolve_guard_bin

if [ -n "$TASK" ] && [ "$TASK" != "resume" ]; then
  $GUARD_BIN arm --task "$TASK"
else
  $GUARD_BIN arm
fi
```

## File: skill/usage-guard/scripts/checkpoint.sh
size: 211
sha: 5751dcd56162f0fec4e7e594b33fc4e261566e37
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/scripts/checkpoint.sh

```text
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=resolve-guard.sh
source "${SCRIPT_DIR}/resolve-guard.sh"

resolve_guard_bin
exec $GUARD_BIN checkpoint "$@"
```

## File: skill/usage-guard/scripts/disarm.sh
size: 197
sha: 9a3639979b839f4e4dc675fe8304b520589ea175
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/scripts/disarm.sh

```text
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=resolve-guard.sh
source "${SCRIPT_DIR}/resolve-guard.sh"

resolve_guard_bin
$GUARD_BIN disarm
```

## File: skill/usage-guard/scripts/join.sh
size: 211
sha: d3391364630341b3dca545a1e538dd8698dc1c22
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/scripts/join.sh

```text
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=resolve-guard.sh
source "${SCRIPT_DIR}/resolve-guard.sh"

resolve_guard_bin
exec $GUARD_BIN arm --join "$@"
```

## File: skill/usage-guard/scripts/resolve-guard.sh
size: 1628
sha: f88b8383908a6b92d2cb622e523fc54c1c255b1c
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/scripts/resolve-guard.sh

```text
#!/usr/bin/env bash
# Sourced by skill scripts. Sets GUARD_BIN to the CLI wrapper or "python3 -m usage_guard".

_resolve_guard_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

_resolve_guard_fail() {
  local stale="${1:-}"
  echo "usage-guard: cannot find the usage_guard package." >&2
  echo "  Re-run ./install.sh from your usage-guard clone, then: usage-guard doctor" >&2
  if [ -n "$stale" ]; then
    echo "  Stale install path: ${stale}" >&2
  fi
  return 1
}

# Sets GUARD_BIN. Exits 1 with a helpful message if nothing resolves.
resolve_guard_bin() {
  GUARD_BIN=""

  if [ -n "${USAGE_GUARD_BIN:-}" ]; then
    if command -v "$USAGE_GUARD_BIN" >/dev/null 2>&1 || [ -x "$USAGE_GUARD_BIN" ]; then
      GUARD_BIN="$USAGE_GUARD_BIN"
      return 0
    fi
  fi

  if command -v usage-guard >/dev/null 2>&1; then
    GUARD_BIN="usage-guard"
    return 0
  fi

  local wrapper="${HOME}/.local/bin/usage-guard"
  if [ -x "$wrapper" ]; then
    GUARD_BIN="$wrapper"
    return 0
  fi

  local repo_root=""
  local repo_root_file="${HOME}/.usage-guard/repo-root"
  if [ -f "$repo_root_file" ]; then
    IFS= read -r repo_root < "$repo_root_file" || true
    if [ -n "$repo_root" ] && [ -d "${repo_root}/usage_guard" ]; then
      export PYTHONPATH="${repo_root}:${PYTHONPATH:-}"
      GUARD_BIN="python3 -m usage_guard"
      return 0
    fi
  fi

  local dev_root
  dev_root="$(cd "${_resolve_guard_lib}/../../.." && pwd)"
  if [ -d "${dev_root}/usage_guard" ]; then
    export PYTHONPATH="${dev_root}:${PYTHONPATH:-}"
    GUARD_BIN="python3 -m usage_guard"
    return 0
  fi

  _resolve_guard_fail "$repo_root"
  exit 1
}
```

## File: skill/usage-guard/scripts/status.sh
size: 197
sha: 2ccc7cc61f440990eccf464254572ec43d2f4b0d
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/skill/usage-guard/scripts/status.sh

```text
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=resolve-guard.sh
source "${SCRIPT_DIR}/resolve-guard.sh"

resolve_guard_bin
$GUARD_BIN status
```

## File: README.md
upstream: https://github.com/shirley-xue-2025/usage-guard/blob/main/README.md

````text
# usage-guard

[![test](https://github.com/shirley-xue-2025/usage-guard/actions/workflows/test.yml/badge.svg)](https://github.com/shirley-xue-2025/usage-guard/actions/workflows/test.yml)

Opt-in proactive **usage guard** for long Claude Code sessions (macOS — Desktop Code tab and CLI). Monitors the account **5-hour window** (default pause at 90%) and, optionally, the **weekly limit** (default pause at 98%) — either can trigger a checkpoint before you hit the wall.

Arm with `/usage-guard` before long batch, subagent, or overnight work — especially when the shared window is already partly used. An external daemon reads your usage (zero session tokens), sets `PAUSE` before limits, sends macOS notifications, and you resume with `/usage-guard resume` after reset — without chat reminders that get queued behind subagents.

**Latest:** **v0.2.2** — fail-closed when blind (`UNKNOWN`), `valid_until` freshness, LaunchAgent KeepAlive, blind-alert backoff. See [CHANGELOG](CHANGELOG.md) / [release notes](docs/releases/v0.2.2.md).

## Who is this for?

- **Long Claude Code sessions** that burn the **5-hour window** quickly (batch jobs, subagents, `/loop`, multi-session arcs)
- Work that starts when usage is **already high** — arm gives account-level visibility, not just this chat's view
- **Weekly limit nearly full** while the current session still looks safe (e.g. 60% session, 97% weekly) — enable weekly monitoring in config
- **Subagent / batch** work where mid-session chat messages stay **queued**
- You want to **pause near 90%** (5h) or **98%** (weekly) and avoid **extra usage wallet** charges at 100%
- **macOS** — Claude Desktop **Code** tab or Claude Code **CLI**
- You can arm once per session (`/usage-guard`) — no per-project setup

> Also used on heavy model runs (e.g. Fable when available). Same 5-hour wall either way.

> **Proactive vs reactive:** [claude-auto-retry](https://github.com/cheapestinference/claude-auto-retry) resumes *after* you hit the wall. usage-guard tries to pause *before* it.

## Why this exists

On long runs, chat messages queue while subagents work — so "stop at 90%" reminders never land in time. Hitting 100% can burn **extra usage wallet**. Stop buttons may not fully halt subagents. Each chat only sees its own usage; the daemon reads **account-level** usage (same OAuth API as Desktop Settings): the shared **5-hour window** and optional **weekly** bar. A session that "looks" fine at 58% can already be at 94% on the 5h window — or at 97% weekly while the session meter still shows 60%. This tool uses an **external control file + upfront session contract** instead of mid-run chat.

## How it works

```
/usage-guard  →  arm daemon  →  ~/.usage-guard/control.json
                                      ↑
Session (cooperative)  ←── read state at safe checkpoints only
  - before each subagent batch
  - after each unit completes
  - on /loop guard ticks
```

| Layer | Role | Tokens |
|-------|------|--------|
| **Daemon** | OAuth usage poll (5h + weekly + extra wallet), adaptive schedule, notifications | 0 |
| **Skill** | Arm, checkpoint rules, `/loop` timetable | Minimal reads |

**Pause rule:** `PAUSE` when **either** limit hits its threshold (defaults: 5h ≥ 90%, weekly ≥ 98% if enabled). Resume when **both** are clear. See `pause_reason` in `control.json` (`five_hour`, `weekly`, or `both`).

**Consumer contract:** obey `state` (`RUN` / `PAUSE` / `COOLDOWN` / `UNKNOWN`). If `now > valid_until` (or `stale: true` / prefer `effective_state`), treat as `UNKNOWN` even when `state` still says `RUN` — the daemon may have died while numbers looked healthy. `state` never stays `RUN` while `telemetry_lost` is true.

`./install.sh` also installs a macOS LaunchAgent (`io.usage-guard.daemon`) with KeepAlive so a crashed daemon restarts; `disarm` exits cleanly and stays down.

## Install (macOS)

```bash
git clone https://github.com/shirley-xue-2025/usage-guard.git
cd usage-guard
chmod +x install.sh
./install.sh
export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc if needed
usage-guard doctor
```

### Updating

> **Active development** — we ship fixes frequently from real session dogfood.

```bash
cd usage-guard          # your clone
git pull
./install.sh            # refreshes skill + CLI (git pull alone is not enough)
usage-guard doctor      # checks credentials + shows update notice if available
```

`doctor` compares your installed version to the latest GitHub release (cached 24h). Set `USAGE_GUARD_NO_UPDATE_CHECK=1` to skip.

### One-time: enable usage reads (Desktop-only users)

OAuth tokens may not exist until Claude Code CLI login:

```bash
npm i -g @anthropic-ai/claude-code
claude login
usage-guard doctor   # expect ✓ Usage API
```

See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md). Release notes: [docs/releases/](docs/releases/).

## Use

### Desktop Code tab

1. Open your project in the **Code** tab
2. Run: `/usage-guard your long task description` (type manually if it does not appear in the slash picker)
3. Approve the arm script when prompted — arm waits for the first usage poll before returning
4. Let it run — watch Terminal: `usage-guard status`

### After reset (new session OK)

```
/usage-guard resume
```

### CLI

Same `/usage-guard` skill after install (shared `~/.claude/skills/`).

## Commands

```bash
usage-guard doctor          # credentials + usage API (5h, weekly, extra wallet)
usage-guard arm             # start daemon + session
usage-guard status          # state, %, weekly, checkpoint, pause_reason
usage-guard disarm          # stop daemon
usage-guard poll            # one-shot usage fetch
```

### Mock mode (no OAuth)

```bash
cd usage-guard
PYTHONPATH=. python3 -m usage_guard arm --mock-percent 91 --force
PYTHONPATH=. python3 -m usage_guard status
PYTHONPATH=. python3 -m usage_guard disarm
```

## Configuration

Optional `~/.usage-guard/config.json`:

```json
{
  "threshold_pause": 90,
  "threshold_warn": 85,
  "weekly_enabled": false,
  "weekly_threshold_pause": 98,
  "weekly_threshold_warn": 95,
  "weekly_pause_within_hours": 5,
  "cooldown_margin_seconds": 60
}
```

**Weekly limit (opt-in):** set `"weekly_enabled": true` to PAUSE when the account **weekly** utilization (Desktop → Settings → Usage → **"All models"**) reaches `weekly_threshold_pause` (default 98%), even if the 5-hour window is still low. Either limit can trigger PAUSE; both must clear before RUN resumes. Set `weekly_pause_within_hours` (e.g. `5`) so weekly only pauses when the weekly reset is that soon — if weekly is 99% but reset is days away, you stay `RUN` (5h guard still applies). Omit or set `null` to pause at threshold regardless of reset time. The OAuth API exposes one weekly number (`seven_day`) — not per-model Sonnet/Opus bars separately.

### Example — dogfood session (screenshot)

> **This image is from a real Claude Code session**, not part of this README.

Config in use: `weekly_enabled: true`, `weekly_threshold_pause: 98`, `weekly_pause_within_hours: 5`.

**What happened:** the 5-hour window had just reset (**4%**). Weekly was **99%**, so the guard entered `COOLDOWN` with `pause_reason: weekly` — the agent stopped dispatching new subagents even though the session window looked safe.

![Claude Code session: weekly COOLDOWN at 99% while the 5-hour window is at 4%](docs/assets/weekly-cooldown-dogfood-example.png)

<details>
<summary>Transcript (accessibility)</summary>

```text
Forced re-arm daemon to enable weekly polling

The force re-arm shows phase: cooldown even though the 5h window just
reset (4%, fresh) — weekly is now what's gating us.

That's exactly why watching weekly mattered — the weekly limit is at 99%
(over the 98% pause threshold), so the guard went to COOLDOWN
(pause_reason: weekly) even though the 5-hour window is fresh (4%).
Without weekly monitoring I'd have kept dispatching subagents straight
into the weekly cap.
```

</details>

## Honest limits

- **Cooperative** — session must follow skill rules; we brief up front
````
