feat: Inform the user that they hit a rate limit issue

I've been playing around with Squad for a few hours today, via the squad cli, and all the sudden I started receiving this message:

❌ Something went wrong processing your message.
Try:
• Try again
• Run 'squad doctor' for diagnostics

I've run squad doctor and there was nothing reported. I opened up Squad via GitHub Copilot and the first command I ran Ralph, what is the team status, I received the following error from Copilot:

✗ Sorry, you've hit a rate limit that restricts the number of Copilot model requests you can make within a specific time period. Please try again in 2 hours. Please review our Terms of Service
(https://docs.github.com/site-policy/github-terms/github-terms-of-service). (Request ID:
DB0C:117B08:179DE8:1B1D3E:69BC6F71)

🏗️ Squad Triage — Flight (Lead)

Issue: #464 — feat: Inform the user that they hit a rate limit issue
Assigned to: Flight (Lead)
Reason: No specific domain match — assigned to Lead for further analysis

@copilot evaluation: No strong capability match — routed to squad member.

Team roster:

Flight (Lead) → label: squad:flight
Procedures (Prompt Engineer) → label: squad:procedures
EECOM (Core Dev) → label: squad:eecom
FIDO (Quality Owner) → label: squad:fido
PAO (DevRel) → label: squad:pao
CAPCOM (SDK Expert) → label: squad:capcom
CONTROL (TypeScript Engineer) → label: squad:control
Surgeon (Release Manager) → label: squad:surgeon
Booster (CI/CD Engineer) → label: squad:booster
GNC (Node.js Runtime) → label: squad:gnc
Network (Distribution) → label: squad:network
RETRO (Security) → label: squad:retro
INCO (CLI UX & Visual Design) → label: squad:inco
GUIDO (VS Code Extension) → label: squad:guido
Telemetry (Aspire & Observability) → label: squad:telemetry
VOX (REPL & Interactive Shell) → label: squad:vox
DSKY (TUI Engineer) → label: squad:dsky
Sims (E2E Test Engineer) → label: squad:sims
Handbook (SDK Usability) → label: squad:handbook
Ralph (Work Monitor) → label: squad:ralph
@copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

📋 Assigned to INCO (CLI UX & Visual Design)

Issue: #464 — feat: Inform the user that they hit a rate limit issue

INCO will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
INCO, work on issue #464

📋 Assigned to EECOM (Core Dev)

Issue: #464 — feat: Inform the user that they hit a rate limit issue

EECOM will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
EECOM, work on issue #464

📊 Rate Limit Detection Research — Issue #464

Executive Summary

Brady's question: "is there a way the squad could continually check the user's rate limit and quota and let them know when they're closing in on trouble?"

Answer: Partial yes. We can detect rate limit errors today, but proactive quota monitoring requires Copilot API header exposure.

1. GitHub API Rate Limit Headers ✅ Available

The GitHub API (including Copilot) exposes these standard headers on every response:

X-RateLimit-Limit: Your quota (e.g., 5000 requests/hour for authenticated)
X-RateLimit-Remaining: Requests left in the current window
X-RateLimit-Reset: UNIX timestamp when window resets
Retry-After: If you hit 429, when to retry

Status: Publicly documented behavior. GitHub API Rate Limits

2. Copilot SDK Layer

The @github/copilot-sdk CopilotClient wraps API responses, but the current adapter (packages/squad-sdk/src/adapter/client.ts) does not expose response headers to Squad.

Finding: The SDK abstracts away the HTTP layer — headers are consumed internally but not bubbled up.

3. Rate Limit Error Handling ✅ Already Implemented

Squad already detects rate limit errors! Evidence:

File: packages/squad-sdk/src/adapter/errors.ts (lines 332–341)

if (message.includes('rate limit') || message.includes('429') || message.includes('quota')) {
  const retryMatch = message.match(/retry after (\d+)/i);
  const retryAfter = retryMatch ? parseInt(retryMatch[1]!, 10) : undefined;
  return new RateLimitError(
    `Rate limit exceeded: ${message}`,
    fullContext,
    retryAfter,
    originalError
  );
}

RateLimitError class: Marked as RECOVERABLE with retryAfter support.

Current behavior: When a 429 or rate limit error is caught, it's categorized and includes the retry delay. However, the CLI doesn't surface this to users effectively.

4. What the User Experienced

Brady hit a rate limit and received this error in Copilot:

✗ Sorry, you've hit a rate limit that restricts the number of Copilot model requests you can make within a specific time period. Please try again in 2 hours...

In Squad CLI, this error came back as:

❌ Something went wrong processing your message.

Problem: The error handler caught it, but the CLI didn't propagate the rate limit reason to the user.

5. Remote Bridge Rate Limiting ✅ Already Implemented

Squad's WebSocket server has HTTP rate limiting (30 requests/minute per IP), but this is separate from Copilot API rate limits.

6. What's Missing for Proactive Quota Monitoring

To continuously check and warn about approaching limits, we'd need:

Header Exposure from SDK:
The @github/copilot-sdk would need to expose X-RateLimit-* headers via the CopilotSession API.
⚠️ Blocker: This is not currently exposed — requires upstream SDK change.
Polling Mechanism:
Squad could periodically call a lightweight API endpoint to check remaining quota before spawning agents.
⚠️ Issue: No lightweight "check quota only" endpoint exposed by Copilot API.

What We Can Do Today (Quick Wins)

Option A: Better Error Message (Easy — ~1–2 hours)

Catch RateLimitError in CLI and display a user-friendly warning instead of generic "something went wrong"
File: packages/squad-cli/src/cli/shell/error-messages.ts

Option B: Track Quota in Telemetry (Medium — ~3–4 hours)

Hook into Copilot SDK's session events to track usage patterns
Log rate limit events via existing telemetry system
File: Enhance packages/squad-sdk/src/runtime/streaming.ts

Option C: Escalate to SDK Team (Blocked)

Request GitHub Copilot SDK team expose X-RateLimit-* headers via CopilotSession

Recommendation

Immediate: Implement Option A for quick UX win
- Users get clear "You hit a rate limit" feedback instead of generic error
- Low effort, high impact
Medium-term: Implement Option B to track quota across sessions
- Integrate with telemetry system (already built)
Escalation: Contact Copilot SDK team if header exposure is needed

Status: Research complete. Blocker: Copilot SDK doesn't expose response headers. Workaround: Better error messaging today, header exposure request to upstream SDK team.

fix: surface rate limit errors with recovery options (#464)

Scribe: Wave 1 decisions merged (#329/#344/#500)

fix: hard-fail on Node <22.5.0 with clear message (#502) (#506)

fix: surface rate limit errors with recovery options (#464)

fix: surface rate limit errors with recovery options (#464) (#505)

docs: log session 2 — wave 1+2 results, 4 PRs merged

fix: unify status vocabulary and context-aware thinking labels (githu…

Navigation Menu

Repository navigation

feat: Inform the user that they hit a rate limit issue #464

🏗️ Squad Triage — Flight (Lead)

@copilot evaluation: No strong capability match — routed to squad member.

📋 Assigned to INCO (CLI UX & Visual Design)

📋 Assigned to EECOM (Core Dev)

📊 Rate Limit Detection Research — Issue #464

Executive Summary

1. GitHub API Rate Limit Headers ✅ Available

2. Copilot SDK Layer

3. Rate Limit Error Handling ✅ Already Implemented

4. What the User Experienced

5. Remote Bridge Rate Limiting ✅ Already Implemented

6. What's Missing for Proactive Quota Monitoring

What We Can Do Today (Quick Wins)

Option A: Better Error Message (Easy — ~1–2 hours)

Option B: Track Quota in Telemetry (Medium — ~3–4 hours)

Option C: Escalate to SDK Team (Blocked)

Recommendation

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat: Inform the user that they hit a rate limit issue #464

Description

Activity

github-actions commented on Mar 20, 2026

🏗️ Squad Triage — Flight (Lead)

@copilot evaluation: No strong capability match — routed to squad member.

github-actions commented on Mar 20, 2026

📋 Assigned to INCO (CLI UX & Visual Design)

github-actions commented on Mar 20, 2026

📋 Assigned to EECOM (Core Dev)

bradygaster commented on Mar 22, 2026

📊 Rate Limit Detection Research — Issue #464

Executive Summary

1. GitHub API Rate Limit Headers ✅ Available

2. Copilot SDK Layer

3. Rate Limit Error Handling ✅ Already Implemented

4. What the User Experienced

5. Remote Bridge Rate Limiting ✅ Already Implemented

6. What's Missing for Proactive Quota Monitoring

What We Can Do Today (Quick Wins)

Option A: Better Error Message (Easy — ~1–2 hours)

Option B: Track Quota in Telemetry (Medium — ~3–4 hours)

Option C: Escalate to SDK Team (Blocked)

Recommendation

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions