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: mcp-local-llm

How it works

Two components work together:

1. statusLine capture script (scripts/usage-capture.js)
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

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

Verify with:

claude mcp list
# → usage-guard: node /path/to/index.js - ✔ 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.

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.

License

MIT