usage-guard

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 "${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