| name | rate-limit-management |
| effort | low |
| description | Framework protocol for responding to Claude Max API usage thresholds. Three-tier wind-down and recovery. Agent-specific behavior belongs in deployment config, not here. |
| triggers | ["rate limit","usage check","usage high","wind down","resume after rate limit","check usage"] |
Rate Limit Management Protocol
Framework-level protocol. Defines tiers and check mechanism only.
Agent-specific behavior at each tier belongs in your deployment's CLAUDE.md or config.json.
Usage Check Command
cortextos bus check-usage-api [--warn-7day N] [--warn-5h N] [--chat-id ID] [--force]
Reads Claude Max utilization from the Anthropic OAuth usage API. Outputs JSON with five_hour and seven_day utilization fields.
Options:
| Flag | Default | Description |
|---|
--warn-7day N | 80 | Send Telegram alert if 7-day utilization >= N% |
--warn-5h N | 90 | Send Telegram alert if 5-hour utilization >= N% |
--chat-id ID | $CTX_TELEGRAM_CHAT_ID | Telegram chat ID for alerts |
--force | false | Bypass 3-minute result cache |
Cache: Results are cached for 3 minutes at $CTX_ROOT/state/usage/api-cache.json to avoid hitting the API hard limit (~5 requests per token before 429).
Requirements: macOS Keychain with Claude Code credentials. The script reads the OAuth access token from the Claude Code-credentials Keychain entry.
Three-Tier Protocol
Tier 1 — Wind-Down (>= 85% utilization)
Signal: Usage is high but work can still complete safely.
Agent behavior:
- Finish the current task or message response
- Do not accept new autonomous tasks
- Do not initiate new research, builds, or multi-step work
- Respond to direct user messages normally
- Check usage every 5 minutes until dropping below 85% or escalating to Tier 2
Cron behavior: Suspend scheduled/proactive cron work. Keep inbox-check and heartbeat crons running.
Tier 2 — Minimal (85-95% utilization)
Signal: Usage is critically high. New work risks hitting the hard limit mid-task.
Agent behavior:
- Suspend all proactive and scheduled work
- Respond only to direct messages from the user
- Keep responses short; do not start multi-step work
- Do not fire background tasks, KB queries, or large LLM calls
- Report status to user via Telegram if transitioning into this tier from normal operations
Cron behavior: Suspend all crons except heartbeat.
Tier 3 — Dark (>= 95% utilization)
Signal: Approaching or at hard limit. Further work risks broken mid-task state.
Agent behavior:
Recovery
Reset condition: Utilization drops below 20% (confirmed via usage check).
On recovery:
Recommended Cron: Usage Check
Check usage every 15 minutes and apply tier logic:
{
"name": "usage-check",
"interval": "15m",
"prompt": "Run cortextos bus check-usage-api and apply the rate limit protocol from .claude/skills/rate-limit-management/SKILL.md based on current utilization."
}
Configurable thresholds: The --warn-7day and --warn-5h flags on check-usage-api are independent early-warning alerts sent to Telegram. They fire below the tier thresholds defined above and serve as a heads-up before tier behavior kicks in.
Recommended warn thresholds:
--warn-7day 75 — early warning at 75% (10 points before Tier 1)--warn-5h 85 — 5-hour window warning at 85%
What Belongs Here vs. Deployment Config
This skill defines:
- The tier thresholds (85 / 95 / 20%)
- The check mechanism (
check-usage-api)
- The generic behavior description for each tier
- The cron pattern
Your deployment config should define:
- Which specific crons to suspend at each tier
- Whether to notify an agent, the user, or other agents on tier transitions
- Whether to pause only the rate-limited agent or also send signals to other agents
- Any org-specific escalation steps
Quick Reference
| Utilization | Tier | Behavior |
|---|
| < 85% | Normal | Full operations |
| 85-94% | Wind-Down | Finish current task; no new autonomous work |
| 85-95% | Minimal | Direct messages only; no scheduled work |
| >= 95% | Dark | Go silent; notify user; wait for reset |
| < 20% (after reset) | Recovery | Resume all operations; notify user |
Framework protocol — no AscendOps-specific content. Agent behavior at each tier is deployment-defined.
