@siliconvalleyglobal/agent-rate-limit-monitor 🚦

Real-time rate-limit and quota monitor across AI providers (OpenAI, Anthropic, Gemini, DeepSeek).

agent-rate-limit-monitor gives developers and AI coding agents fast, glanceable visibility into remaining API request and token quotas — featuring a simple green/yellow/red traffic light indicator, terminal status table, live watch mode, script guardrails, and persistent caching.

💡 Key Features

• Traffic-Light Status Logic: Simple status indicator across all configured providers:
  • 🟢 GREEN: >50% quota remaining
  • 🟡 YELLOW: 15%–50% quota remaining
  • 🔴 RED: <15% quota remaining or HTTP 429 rate limit exceeded
• Pluggable Provider Adapters: OpenAI (OpenAIAdapter), Anthropic (AnthropicAdapter), Google Gemini (GeminiAdapter).
• Seamless Key Resolution: Automatically reads keys from agent-config-sync (~/.agent-config/config.json), local config (~/.agent-rate-limit-monitor/config.json), or environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY).
• Terminal CLI & Live Watch: status table readout and continuous watch mode (htop-style continuous refresh).
• Pre-Task Script Guardrails: status command exits with code 1 if any provider is in RED status — ideal for agent-rate-limit-monitor status || exit 1 before starting long agent runs.
• Persistent Caching: Caches last-known status in ~/.agent-rate-limit-monitor/cache.json for instant startup without waiting for network requests.

📦 Installation

# Install as a dependency
npm install @siliconvalleyglobal/agent-rate-limit-monitor

# Or install globally for CLI usage
npm install -g @siliconvalleyglobal/agent-rate-limit-monitor

🚀 Quickstart

1. CLI Usage

# Initialize configuration file ~/.agent-rate-limit-monitor/config.json
agent-rate-limit-monitor init

# Print current rate-limit status table
agent-rate-limit-monitor status

# Continuously watch rate-limit status (refresh every 60s)
agent-rate-limit-monitor watch --interval 60

# Diagnose key resolution and provider connectivity
agent-rate-limit-monitor doctor

2. Programmatic Library Usage

import { RateLimitMonitor } from '@siliconvalleyglobal/agent-rate-limit-monitor';

const monitor = new RateLimitMonitor();

// Fetch status across all configured providers
const { statuses, worstCaseState } = await monitor.fetchAllStatuses();

console.log(`Worst-case status: ${worstCaseState}`);
for (const [providerId, status] of Object.entries(statuses)) {
  console.log(`${status.providerName}: ${status.state} (${status.remainingPercentage.toFixed(1)}%)`);
}

🛡️ Supported Providers

| Provider | Adapter | Header / API Inspection | | :--- | :--- | :--- | | OpenAI | OpenAIAdapter | x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens | | Anthropic (Claude) | AnthropicAdapter | anthropic-ratelimit-requests-remaining, anthropic-ratelimit-tokens-remaining | | Google Gemini | GeminiAdapter | v1beta/models endpoint quota status |

📄 License

MIT © SVG Team