rate-limit-management

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:

• Send user a Telegram status message:

  Rate limit at [N]%. Going dark until reset. Will notify when back online. Resets at [time].
  

• Stop processing. Do not respond to new messages.
• Update heartbeat to "paused — rate limit"
• Wait for reset signal (see Recovery below)

---

Recovery

Reset condition: Utilization drops below 20% (confirmed via usage check).

On recovery:

• Resume normal operations
• Restore all suspended crons
• Notify user via Telegram:

  Rate limit reset. Back online. Resuming normal operations.
  

• Update heartbeat to "online"

---

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.