claude-usage-guard

An MCP server that exposes Claude Code's real-time rate limit usage so that an orchestrator (Leader agent) can check remaining capacity before launching subtasks — and pause when approaching limits rather than failing mid-workflow.

The problem

Claude Code enforces two rate limit windows: a 5-hour session window and a 7-day weekly window. When running multi-agent workflows, an orchestrator has no native way to know how much quota remains before launching a batch of subtasks. The workflow can stall mid-execution when the limit is hit, leaving work in an incomplete state.

Related MCP server: headroom

How it works

Two components work together:

1. statusLine capture script (scripts/usage-capture.cjs)
Registered as Claude Code's statusLine command. Receives the internal JSON that Claude Code passes after each response — which includes the parsed anthropic-ratelimit-* headers — and persists the rate limit data to ~/.claude/usage_state.json.

2. MCP server (index.js)
Exposes a single tool check_usage_limits that reads ~/.claude/usage_state.json and returns structured data the orchestrator can reason over.

Note: The rate_limits field is only available for Claude.ai Pro/Max subscribers (not direct API key users), and only after the first API response in a session.

Installation

Requirements: Node.js 18+, Claude Code CLI

Option A — npm (recommended)

npm install -g claude-usage-guard

Register the MCP server at user scope:

claude mcp add --transport stdio --scope user usage-guard -- claude-usage-guard

Then add the statusLine entry to ~/.claude/settings.json:

"statusLine": {
  "type": "command",
  "command": "claude-usage-guard-statusline"
}

If Claude Code can't find the command (e.g. you use nvm and its bin dir isn't on Claude Code's PATH), use the absolute path printed by which claude-usage-guard / which claude-usage-guard-statusline instead.

Option B — git clone + setup script

git clone https://github.com/ecerutti/claude-usage-guard.git
cd claude-usage-guard
bash setup.sh

The setup script:

• Installs npm dependencies

• Copies the capture script to ~/.claude/scripts/

• Registers the MCP server at user scope (claude mcp add --scope user)

Then add the statusLine entry to ~/.claude/settings.json manually (the setup script prints the exact snippet to add). To remove everything later, run bash uninstall.sh.

Verify

claude mcp list
# → usage-guard: ... - ✔ Connected

Tool output

check_usage_limits takes no parameters and returns:

{
  "session_used_pct": 42.5,
  "session_resets_at": "2026-06-25T18:30:00.000Z",
  "session_resets_in_seconds": 5700,
  "weekly_used_pct": 15.3,
  "weekly_resets_at": "2026-07-02T04:00:00.000Z",
  "weekly_resets_in_seconds": 601500,
  "data_freshness": "fresh",
  "captured_at": "2026-06-25T16:45:00.000Z"
}

Each window field can be null independently if not yet available.

Using in an orchestrator prompt

Add this to your Leader agent's CLAUDE.md or system prompt:

Before launching any subtask (Task tool or parallel agents), call check_usage_limits.

Decision rules:
- data_freshness "unavailable" → proceed with caution, no usage data yet
- session_used_pct > 80 → do NOT launch heavy tasks; check session_resets_in_seconds,
  wait that duration (Bash sleep or schedule a wakeup), then re-check before continuing
- Otherwise → proceed normally

Always note remaining capacity in your task plan so you can resume pending work
after a reset if you need to pause mid-workflow.

Before relying on this in a long/unattended session, read LESSONS.md. It covers gotchas the rules above don't: re-checking cadence once you're above 80% (not just before launches), what data_freshness: "unavailable" actually means near the reset boundary, why a hard-limit hit with no pending wakeup leaves the session fully idle, and what this tool does (and doesn't) tell you when a different model/account takes over mid-session.

Design decisions

• No recommendation field. The tool exposes raw data only. The orchestrator model reasons over it directly — pre-baked thresholds would be wrong for different workloads.

• Fail-open. If data is unavailable, the tool returns null fields rather than blocking — the orchestrator decides what to do with missing information.

• statusLine is the only reliable source. Scraping claude.ai is blocked by Cloudflare. The rate_limits field in the statusLine JSON is the only official, non-fragile way to access this data from outside the API layer.

Contributing

Contributions are welcome! See CONTRIBUTING.md for how to set up the project, run the tests (npm test), and open a pull request. For security issues, see SECURITY.md.

License

MIT © Esteban Cerutti