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:
- Enable/Disable - Turn usage-gate on or off
- 5H Threshold - Set 5-hour usage limit and fallback model
- 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:
- Environment variable:
ANTHROPIC_ACCESS_TOKEN (all platforms)
- macOS Keychain: Reads from
Claude Code-credentials (automatic)
- Windows Credential Manager: Reads from stored credentials (automatic)
- 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.
