Claude OAuth 429: no actionable guidance shown when token is rate-limited

[h3x89]

Summary

When the Claude OAuth token hits a 429 rate limit error, CodexBar shows no actionable guidance — just a generic error or silent failure. The fix is non-obvious and requires CLI steps outside the app.

Root cause chain

1. PTY reader fails silently — after a CodexBar update (or Claude Code CLI update), the new PTY-based session probe (binary=claude, 5s timeout) starts and stops without returning data
2. Fallback to OAuth API — CodexBar falls back to OAuth API for usage polling
3. Stale token spam — if the token is expired/stale, CodexBar keeps retrying the OAuth API silently
4. 429 accumulates — Anthropic rate-limits the token bucket; new requests hit 429 even after re-auth
5. No user guidance — the app shows — in menu bar or a generic OAuth error with no indication of what to do

Log evidence

Claude CLI session started binary=claude
Claude CLI session reused
Claude CLI session stopping
# → no "claude-usage success"
# then after switching to OAuth API:
Claude OAuth error: HTTP 429 – rate_limit_error

Fix (requires CLI — not discoverable from the app)

1. Change Usage Source: CodexBar Preferences → Providers → Claude → Usage Source: OAuth API
2. Re-authenticate to get a fresh token bucket:

   claude logout && claude login

3. Force CodexBar to pick up the new keychain token: click 🔄 refresh on the Claude provider in CodexBar (Keychain prompt policy = "Only on user action" prevents automatic pickup)

What would help

When a 429 is detected on the Claude OAuth endpoint, show an actionable inline message, e.g.:

Rate limited by Anthropic API. Your token may be exhausted from repeated retries. Fix: run claude logout && claude login in Terminal, then click Refresh here.

Or at minimum a "Re-authenticate" button that triggers the CLI logout/login flow.

Environment

• macOS (Apple Silicon)
• CodexBar post-2026-03-18 update
• Claude Code CLI 2.1.x
• Claude provider: OAuth source

Related

• This is a follow-up to the PTY reader regression introduced ~2026-03-18 — the silent retry behavior makes the 429 hard to diagnose without reading raw log files at ~/Library/Logs/CodexBar/CodexBar.log