Rate Limit Management

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:

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 Dane, 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

Framework protocol — no AscendOps-specific content. Agent behavior at each tier is deployment-defined.