shirley-xue-2025/usage-guard

README preview

# 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.0](https://github.com/shirley-xue-2025/usage-guard/releases/tag/v0.2.0) — weekly limit monitoring (opt-in), extra usage wallet in status, install-path fixes.

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

View full repository on GitHub →