usage-gate

usage-gate

A Claude Code plugin that automatically switches sub-agent models from opus to sonnet/haiku when your Anthropic API usage approaches rate limits. Fully configurable via interactive setup command.

How It Works

You submit a prompt
  ↓
usage-tracker.js fetches real-time usage from Anthropic API
  → Caches result (60s TTL)
  → Shows usage warning if approaching threshold
  ↓
Claude wants to spawn a sub-agent (Task tool)
  ↓
model-gate.js checks cached usage
  → Usage < threshold  →  ALLOW (opus OK)
  → Usage >= threshold →  AUTO-SWITCH model via updatedInput
  ↓
Task executes with fallback model (sonnet/haiku) — no retry needed

Installation

claude plugin add /path/to/usage-gate

Or from GitHub:

claude plugin add github:jung-wankim/usage-gate

Configuration

Quick Setup (Recommended)

Use the interactive setup command:

/usage-gate:setup

This will guide you through:

1. Enable/Disable - Turn usage-gate on or off
2. 5H Threshold - Set 5-hour usage limit and fallback model
3. 7D Threshold - Set 7-day usage limit and fallback model

All settings are saved to ~/.claude/settings.json automatically.

Manual Configuration

You can also manually set thresholds via environment variables in your Claude Code settings:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_USAGE_GATE_ENABLED": "true",
    "CLAUDE_OPUS_LIMIT_5H": "90",
    "CLAUDE_FALLBACK_MODEL_5H": "sonnet",
    "CLAUDE_OPUS_LIMIT_7D": "90",
    "CLAUDE_FALLBACK_MODEL_7D": "sonnet",
    "CLAUDE_USAGE_CACHE_TTL": "60"
  }
}

Variable	Default	Description
CLAUDE_USAGE_GATE_ENABLED	true	Enable/disable the usage gate
CLAUDE_OPUS_LIMIT_5H	90	5-hour usage threshold (%)
CLAUDE_FALLBACK_MODEL_5H	sonnet	Model to use when 5H limit exceeded (sonnet or haiku)
CLAUDE_OPUS_LIMIT_7D	90	7-day usage threshold (%)
CLAUDE_FALLBACK_MODEL_7D	sonnet	Model to use when 7D limit exceeded (sonnet or haiku)
CLAUDE_USAGE_CACHE_TTL	60	API cache TTL (seconds)

Configuration Strategies

Conservative (Recommended - Early switch, maximize cost savings):

• 5H: 70% → sonnet
• 7D: 70% → sonnet

Balanced:

• 5H: 80% → sonnet
• 7D: 80% → sonnet

Aggressive (Use opus as much as possible):

• 5H: 90% → sonnet
• 7D: 90% → sonnet

Very Aggressive (Almost no limits):

• 5H: 95% → haiku
• 7D: 95% → haiku

Status Line

usage-gate includes a persistent status line that displays gate status under the Claude Code prompt.

Standalone Mode

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/plugins/cache/usage-gate/usage-gate/1.0.0/statusline/index.js"
  }
}

Chain Mode (with claude-dashboard)

Run alongside another statusline plugin by setting USAGE_GATE_CHAIN_CMD:

// ~/.claude/settings.json
{
  "env": {
    "USAGE_GATE_CHAIN_CMD": "node ~/.claude/plugins/cache/claude-dashboard/claude-dashboard/1.3.0/dist/index.js"
  },
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/plugins/cache/usage-gate/usage-gate/1.0.0/statusline/index.js"
  }
}

Output example (chain mode):

🤖 Opus │ ░░░░░ │ 30% │ 60K/200K │ $1.25 │ 5h: 26% │ 7d: 80%   ← claude-dashboard
⏱ 3분 │ 🔥 2/min                                                  ← claude-dashboard
Gate ACTIVE │ 5h 25%/70% │ 7d 80%/70% →S                          ← usage-gate

Status Indicators

Display	Meaning
Gate standby (green)	Gate enabled, usage below all thresholds
Gate ACTIVE (orange/red)	Usage exceeded a threshold, auto-switching active
Gate OFF	Gate disabled via settings
→S	Fallback to Sonnet
→H	Fallback to Haiku

Slash Commands

• /usage-gate:setup - Interactive configuration - Set thresholds, fallback models, and enable/disable the gate

Requirements

• Claude Code with plugin support
• Node.js (bundled with Claude Code)
• macOS, Linux, or Windows

No additional dependencies needed. Uses only Node.js built-in modules.

Authentication

The plugin retrieves your OAuth token automatically:

1. Environment variable: ANTHROPIC_ACCESS_TOKEN (all platforms)
2. macOS Keychain: Reads from Claude Code-credentials (automatic)
3. Windows Credential Manager: Reads from stored credentials (automatic)
4. Credential files: ~/.claude/credentials.json or ~/.config/claude/credentials.json (Linux)

How the Gate Works

When usage exceeds the threshold, the hook automatically injects the fallback model into the Task parameters using updatedInput. No blocking, no retry — the model is switched transparently in a single call.