claude-usage-guard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esteban Cerutti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# claude-usage-guard
+
+[![CI](https://github.com/ecerutti/claude-usage-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/ecerutti/claude-usage-guard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+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.
+
+## 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)
+
+```bash
+npm install -g claude-usage-guard
+```
+
+Register the MCP server at user scope:
+
+```bash
+claude mcp add --transport stdio --scope user usage-guard -- claude-usage-guard
+```
+
+Then add the `statusLine` entry to `~/.claude/settings.json`:
+
+```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
+
+```bash
+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
+
+```bash
+claude mcp list
+# → usage-guard: ... - ✔ Connected
+```
+
+## Tool output
+
+`check_usage_limits` takes no parameters and returns:
+
+```json
+{
+  "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"
+}
+```
+
+| Field | Description |
+|---|---|
+| `session_used_pct` | % of 5-hour window consumed (0–100) |
+| `weekly_used_pct` | % of 7-day window consumed (0–100) |
+| `*_resets_in_seconds` | Seconds until that window resets |
+| `data_freshness` | `"fresh"` <60s · `"stale"` 60–300s · `"unavailable"` >300s or no data |
+| `captured_at` | ISO 8601 timestamp of last capture |
+
+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.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](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](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Esteban Cerutti

package/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { buildUsageReport } from './lib/usage.js';
+
+const STATE_FILE = join(homedir(), '.claude', 'usage_state.json');
+
+function checkUsageLimits() {
+  let raw = null;
+  try {
+    raw = JSON.parse(readFileSync(STATE_FILE, 'utf-8'));
+  } catch {
+    // Missing or unreadable state file → buildUsageReport returns the
+    // "unavailable" shape (all fields null). Fail-open by design.
+  }
+  return buildUsageReport(raw);
+}
+
+const server = new Server(
+  { name: 'usage-guard', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: 'check_usage_limits',
+    description: 'Returns current Claude Code rate limit usage. session_used_pct and weekly_used_pct are 0-100. data_freshness is "fresh" (<60s), "stale" (60-300s), or "unavailable" (>300s or no data).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  }],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== 'check_usage_limits') {
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(checkUsageLimits(), null, 2),
+    }],
+  };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/lib/usage.js

@@ -0,0 +1,55 @@
+// Pure, side-effect-free helpers for turning a captured usage_state.json
+// snapshot into the structured report exposed by the MCP tool. Kept separate
+// from index.js so the transformation logic can be unit-tested without I/O.
+
+export const FRESH_THRESHOLD = 60; // seconds
+export const STALE_THRESHOLD = 300; // seconds
+
+export function toISOLocal(epochSeconds) {
+  return new Date(epochSeconds * 1000).toISOString();
+}
+
+export function secondsUntil(epochSeconds, now = Date.now()) {
+  return Math.max(0, Math.floor(epochSeconds - now / 1000));
+}
+
+export function getFreshness(capturedAt, now = Date.now()) {
+  const ageSeconds = (now - new Date(capturedAt).getTime()) / 1000;
+  if (ageSeconds < FRESH_THRESHOLD) return 'fresh';
+  if (ageSeconds < STALE_THRESHOLD) return 'stale';
+  return 'unavailable';
+}
+
+function unavailableReport() {
+  return {
+    session_used_pct: null,
+    session_resets_at: null,
+    session_resets_in_seconds: null,
+    weekly_used_pct: null,
+    weekly_resets_at: null,
+    weekly_resets_in_seconds: null,
+    data_freshness: 'unavailable',
+    captured_at: null,
+  };
+}
+
+// raw: parsed contents of usage_state.json, or null/undefined when the file
+// is missing or unreadable. Returns the report shape the MCP tool emits.
+export function buildUsageReport(raw, now = Date.now()) {
+  if (!raw) return unavailableReport();
+
+  const freshness = getFreshness(raw.captured_at, now);
+  const fh = raw.five_hour;
+  const sd = raw.seven_day;
+
+  return {
+    session_used_pct: fh?.used_percentage ?? null,
+    session_resets_at: fh?.resets_at ? toISOLocal(fh.resets_at) : null,
+    session_resets_in_seconds: fh?.resets_at ? secondsUntil(fh.resets_at, now) : null,
+    weekly_used_pct: sd?.used_percentage ?? null,
+    weekly_resets_at: sd?.resets_at ? toISOLocal(sd.resets_at) : null,
+    weekly_resets_in_seconds: sd?.resets_at ? secondsUntil(sd.resets_at, now) : null,
+    data_freshness: freshness,
+    captured_at: raw.captured_at ?? null,
+  };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "claude-usage-guard",
+  "version": "1.0.0",
+  "description": "MCP server that exposes Claude Code's real-time rate limit usage so orchestrators can check remaining capacity before launching subtasks.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "claude-usage-guard": "index.js",
+    "claude-usage-guard-statusline": "scripts/usage-capture.cjs"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "scripts/usage-capture.cjs",
+    "setup.sh",
+    "uninstall.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "rate-limit",
+    "usage",
+    "orchestrator",
+    "agents"
+  ],
+  "author": "Esteban Cerutti <esteban.cerutti@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ecerutti/claude-usage-guard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ecerutti/claude-usage-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ecerutti/claude-usage-guard/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  }
+}

package/scripts/usage-capture.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+const { writeFileSync } = require('fs');
+const { homedir } = require('os');
+const { join } = require('path');
+
+const chunks = [];
+process.stdin.on('data', (chunk) => chunks.push(chunk));
+process.stdin.on('end', () => {
+  let input = {};
+  try {
+    input = JSON.parse(Buffer.concat(chunks).toString());
+  } catch {}
+
+  const rateLimits = input.rate_limits;
+
+  if (rateLimits) {
+    const state = {
+      captured_at: new Date().toISOString(),
+      five_hour: rateLimits.five_hour ?? null,
+      seven_day: rateLimits.seven_day ?? null,
+    };
+    try {
+      writeFileSync(join(homedir(), '.claude', 'usage_state.json'), JSON.stringify(state, null, 2));
+    } catch {}
+  }
+
+  const fh = rateLimits?.five_hour;
+  const sd = rateLimits?.seven_day;
+
+  const parts = [];
+  if (fh != null) parts.push(`5h: ${Math.round(fh.used_percentage)}%`);
+  if (sd != null) parts.push(`7d: ${Math.round(sd.used_percentage)}%`);
+
+  process.stdout.write((parts.length ? `usage: ${parts.join(' | ')}` : '') + '\n');
+});

package/setup.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ "${1:-}" = "--reinstall" ]; then
+  echo "Reinstalling: running uninstall first..."
+  bash "$SCRIPT_DIR/uninstall.sh" || true
+  echo ""
+fi
+
+# Detect node with absolute path (handles nvm, asdf, and non-standard installs)
+NODE_BIN=$(command -v node 2>/dev/null || command -v nodejs 2>/dev/null || true)
+if [ -z "$NODE_BIN" ]; then
+  echo "Error: Node.js not found in PATH."
+  echo "Install it from https://nodejs.org or via nvm: https://github.com/nvm-sh/nvm"
+  exit 1
+fi
+NODE_BIN=$(realpath "$NODE_BIN")
+echo "Using Node.js: $NODE_BIN ($(${NODE_BIN} --version))"
+
+echo "Installing dependencies..."
+npm install --prefix "$SCRIPT_DIR"
+
+echo "Copying statusLine capture script..."
+mkdir -p ~/.claude/scripts
+cp "$SCRIPT_DIR/scripts/usage-capture.cjs" ~/.claude/scripts/usage-capture.cjs
+
+echo "Registering MCP server (user scope)..."
+claude mcp add --transport stdio --scope user usage-guard -- "$NODE_BIN" "$SCRIPT_DIR/index.js"
+
+echo ""
+echo "Done. One manual step remaining — add this to ~/.claude/settings.json:"
+echo ""
+echo '  "statusLine": {'
+echo '    "type": "command",'
+echo "    \"command\": \"$NODE_BIN $HOME/.claude/scripts/usage-capture.cjs\""
+echo '  }'
+echo ""
+echo "Then restart Claude Code. The tool check_usage_limits will be available."

package/uninstall.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -e
+
+echo "Uninstalling claude-usage-guard..."
+
+# 1. Remove MCP server registration
+if claude mcp remove usage-guard 2>/dev/null; then
+  echo "✓ MCP server removed"
+else
+  echo "  MCP server was not registered (skipping)"
+fi
+
+# 2. Remove statusLine from ~/.claude/settings.json
+SETTINGS="$HOME/.claude/settings.json"
+if [ -f "$SETTINGS" ]; then
+  NODE_BIN=$(command -v node 2>/dev/null || command -v nodejs 2>/dev/null || true)
+  if [ -n "$NODE_BIN" ]; then
+    NODE_BIN=$(realpath "$NODE_BIN")
+  fi
+  PYTHON_BIN=$(command -v python3 2>/dev/null || true)
+
+  if [ -n "$NODE_BIN" ]; then
+    "$NODE_BIN" -e "
+      const fs = require('fs');
+      const s = JSON.parse(fs.readFileSync(process.env.SETTINGS, 'utf-8'));
+      delete s.statusLine;
+      fs.writeFileSync(process.env.SETTINGS, JSON.stringify(s, null, 2) + '\n');
+    " SETTINGS="$SETTINGS" && echo "✓ statusLine removed from settings.json"
+  elif [ -n "$PYTHON_BIN" ]; then
+    SETTINGS="$SETTINGS" "$PYTHON_BIN" -c "
+import json, os
+path = os.environ['SETTINGS']
+with open(path) as f:
+    s = json.load(f)
+s.pop('statusLine', None)
+with open(path, 'w') as f:
+    json.dump(s, f, indent=2)
+    f.write('\n')
+" && echo "✓ statusLine removed from settings.json"
+  else
+    echo "! Could not auto-edit settings.json (no node or python3 found)"
+    echo "  Remove the \"statusLine\" key manually from: $SETTINGS"
+  fi
+else
+  echo "  settings.json not found (skipping)"
+fi
+
+# 3. Remove capture script (and any legacy .js copy from older versions)
+rm -f "$HOME/.claude/scripts/usage-capture.cjs" "$HOME/.claude/scripts/usage-capture.js"
+echo "✓ Capture script removed"
+
+# 4. Remove state file
+rm -f "$HOME/.claude/usage_state.json"
+echo "✓ State file removed"
+
+echo ""
+echo "Done. Restart Claude Code to apply changes."
+echo "You can now delete this repository directory if you no longer need it."