usage-guard

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 / release notes.

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 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).