Token Management

This page defines how the AI team reacts when work cannot continue due to Claude PAYG limits, OpenAI token exhaustion, or Astrakion internal token limits.

Bring-Your-Own-Key Model (PAYG)

You provide:

  • OpenAI API Key — Used by Astra (PO) and Orion (QA)
  • Claude API Key — Used exclusively by Kade (Dev)

Astrakion does not track LLM usage, quotas, billing, or consumption. Astrakion only detects when a provider refuses a request.

Global Rule: Work continues at full speed until a provider refuses a request.

Service Limitation Types

A. Claude PAYG Rate & Usage Limits

Triggered by: Rate-limit exceeded, tokens-per-minute reached, retry-after windows, weekly coding caps, or temporary service interruptions.

Impact:

  • Kade (Dev) → stops
  • Astra (PO) → continues analysis-only (if OpenAI available)
  • Orion (QA) → continues (uses OpenAI only)

GitHub Label: blocked: rate limit

Resumes automatically when Claude becomes available.

B. OpenAI PAYG Token or Billing Failures

Triggered by: Balance exhausted, billing disabled, quota exceeded, account suspension, invalid API key.

Impact:

  • Astra (PO) → stops
  • Orion (QA) → stops
  • Kade (Dev) → stops (cannot progress without QA)

GitHub Label: blocked: tokens

Resumes when you restore billing or update the OpenAI key.

C. Astrakion Internal Token Limits

Each billing user receives a monthly pool of Astrakion Tokens, shared across all repositories. Only code-impacting work (Kade + Orion) consumes tokens. Refinement and analysis-only tasks do not consume tokens.

Impact:

  • Kade (Dev) → stops
  • Orion (QA) → stops
  • Astra (PO) → continues refinement & analysis

GitHub Label: blocked: astrakion tokens

Work resumes when monthly tokens reset or extra usage is purchased.

Service Availability Matrix

Condition Astra (PO) Kade (Dev) Orion (QA)
Claude rate-limited / down continues (analysis) stops continues
OpenAI out of tokens / billing stops stops stops
Astrakion tokens exhausted continues (analysis) stops stops
Both Claude + OpenAI down stops stops stops
All services available continues continues continues

Automatic Resume Logic

Work resumes automatically when:

  • Claude availability returns
  • OpenAI billing/quota issues resolve
  • Monthly Astrakion Tokens reset
  • Extra usage tokens become available

Astra automatically removes block labels, restores workflow, and reassigns blocked issues.

Performance Metrics Logged

For every interruption, Astrakion logs:

  • Limitation type
  • Start/end timestamps
  • Total blocked time
  • Issues impacted

Astrakion never tracks provider token usage — only downtime events.

Operating Philosophy

"The team never pre-throttles or slows work. Work proceeds at full speed until a provider refuses a request."