feat: Rate-limit detection for OpenAI/Codex

[lis186]

Problem

ccxray detects Claude rate-limit headers for quota ticker display. Codex traffic is primarily WebSocket, so rate-limit detection likely needs ws-proxy frame parsing or WS upgrade response header extraction, not just the HTTP-path ratelimit-log.js.

Scope

• Identify where OpenAI rate-limit info appears (WS upgrade response headers? per-frame metadata?)
• Extend rate-limit detection to cover WS transport
• Feed into quota-ticker UI

Before / After UI

BEFORE:
┌─────────────────────────────────────────────────────────┐
│  ccxray dashboard — quota ticker                        │
│                                                         │
│  Claude (opus-4):                                       │
│  ████████████░░░░░░░░  60,000 / 80,000 tokens           │
│  resets 2026-06-05T10:00:00Z                            │
│  ✓ "Can parallelize — 75% remaining"                    │
│                                                         │
│  Codex (o3):                                            │
│  ░░░░░░░░░░░░░░░░░░░░  — / — tokens                    │
│  (no rate-limit info available)                         │
│  ⚠ No data                                             │
└─────────────────────────────────────────────────────────┘

AFTER:
┌─────────────────────────────────────────────────────────┐
│  ccxray dashboard — quota ticker                        │
│                                                         │
│  Claude (opus-4):                                       │
│  ████████████░░░░░░░░  60,000 / 80,000 tokens           │
│  resets 2026-06-05T10:00:00Z                            │
│  ✓ "Can parallelize — 75% remaining"                    │
│                                                         │
│  Codex (o3):                                            │
│  ██████████████░░░░░░  7,200 / 10,000 RPM              │
│  resets 2026-06-05T09:01:00Z                            │
│  ✓ "Healthy — 72% remaining"                           │
└─────────────────────────────────────────────────────────┘

Architecture

Detection surface by provider

Claude (HTTP) — working today:

Claude Code
  → POST /v1/messages
  → Anthropic API responds with HTTP headers:
      anthropic-ratelimit-tokens-limit: 80000
      anthropic-ratelimit-tokens-remaining: 60000
      anthropic-ratelimit-tokens-reset: 2026-06-05T10:00:00Z
  → server/ratelimit-log.js captures headers from proxyRes
  → SSE broadcast to dashboard
  → public/quota-ticker.js renders progress bar

Codex (WS) — needs investigation:

Codex CLI
  → POST /v1/responses (Upgrade: websocket)
  → OpenAI API responds with 101 Switching Protocols
      ┌─────────────────────────────────────────────────┐
      │ WS upgrade response headers?                    │
      │   x-ratelimit-limit-requests: 10000             │
      │   x-ratelimit-remaining-requests: 7200          │
      │   x-ratelimit-reset-requests: 1s                │
      │   (unconfirmed — needs wire capture)             │
      └─────────────────────────────────────────────────┘
  → Per-frame metadata in WS messages?
      ┌─────────────────────────────────────────────────┐
      │ response.usage.rate_limit_info? (unconfirmed)   │
      │ response.done event metadata? (unconfirmed)     │
      └─────────────────────────────────────────────────┘
  → server/ws-proxy.js would need to extract from one or both
  → Feed into server/ratelimit-log.js (same capture/sample pattern)
  → public/quota-ticker.js renders (same UI, different labels)

Key question: WHERE does OpenAI expose rate-limit info for WebSocket connections?

• WS upgrade (101) response headers?
• Per-response metadata in WS frames?
• Separate REST endpoint (e.g. /v1/rate_limits)?

Files involved:

File	Role
server/ratelimit-log.js	Capture + sample rate-limit data (currently HTTP-only)
server/ws-proxy.js	WS transport proxy — extraction point for Codex
public/quota-ticker.js	Dashboard UI rendering
server/config.js	UPSTREAM_PROFILES — could gain rateLimitSource field

Value

For users

• Know when approaching Codex rate limits before hitting them
• Pace adjustment recommendations ("Can parallelize" / "Slow down") work for Codex too
• Unified rate-limit visibility across both providers in one dashboard

For developers

• UPSTREAM_PROFILES could gain a rateLimitSource field per provider family
• ratelimit-log.js already has the capture/sample pattern — extend to WS frames
• Clean separation: detection (server) vs rendering (client) already exists

Side Effects

• WS upgrade headers may not contain rate-limit info (needs wire capture investigation first)
• OpenAI rate-limit semantics may differ from Anthropic:
  • Per-minute (RPM/TPM) vs Anthropic's per-day with rolling window
  • Org-level vs project-level vs user-level limits
  • Separate limits for requests vs tokens vs images
• quota-ticker.js assumptions about token windows (5h rolling) may not apply to OpenAI
• ChatGPT-OAuth vs API-key Codex users may have different rate-limit visibility

Open Questions

• Does Codex CLI itself surface rate-limit info anywhere (env var, stderr, config)?
• Is there a /v1/rate_limits endpoint for OpenAI API key users?
• For ChatGPT-OAuth Codex users, are rate limits even exposed via headers/frames?
• Do WS upgrade 101 responses carry the same x-ratelimit-* headers as regular REST responses?
• Should we do a wire capture (CCXRAY_WS_DEBUG=1) to observe actual headers/frames?

[lis186]

🔬 Scope revision after data verification — honest, executable spec

TL;DR: Investigation expanded this from "detect Codex rate limits" into a per-account, multi-provider usage view. Before committing to an "actionable recommendations" dashboard, I verified each proposed lever against ccxray's actual logs. Three rounds of verification killed the prescriptive direction: the data does not support "you should downgrade / you broke your cache" advice. Final scope is descriptive per-account rate-limit display + the one genuinely-actionable lever (Codex weekly-limit pacing). This comment is a self-contained handoff — a future session can execute from it directly.

---

What was verified (and why it changed the scope)

All numbers from the real ~/.ccxray/logs/index.ndjson (28,968 entries, 7,336 turns in last 7d: 7,196 anthropic + 137 openai) and ~/.codex*/sessions/*.jsonl.

Verification 1 — "downgrade routine Opus work" lever → mostly invalid.
Opus = $746 of ~$875 7d spend. But breaking it down by toolCalls:

• routine-only turns (Bash/Read/Grep): $103 (14%) ← the only clearly-downgradeable slice
• has-reasoning turns (Edit/Write/Agent): $563 (75%) ← legit Opus work
• no-tool (pure thinking): $80 (11%)

The "62% of spend is on Opus = biggest lever" framing was misleading. Only ~14% is obviously routine.

Verification 2 — "cache breakage attribution" lever → 67% not user-actionable.
Strict breakage detection (cache_read < 5k despite mid-session prior turn, cache_creation > 20k), gap-first attribution, 7d:

• sysHash change: 123 (67%)
• model change mid-session: 28 (15%) ← clean, actionable
• idle gap > 1h (TTL): 31 (17%) ← unavoidable (stepped away)
• toolsHash: 0, unattributed: 1

Then I diffed the actual stored system prompts (shared/sys_*.json) across a sysHash breakage. The only difference was a single token:

< x-anthropic-billing-header: ... cch=471b9;
> x-anthropic-billing-header: ... cch=472cd;

cch= is a Claude-Code-internal billing/cache-cohort token. When Anthropic rotates it, ccxray's sysHash changes and cache breaks server-side, regardless of anything the user does. So the dominant "cache broke" cause is not a lever — it's Anthropic rotating their own cache key. Only the 15% model-switch slice is cleanly actionable.

Conclusion: The "decision-support / give advice" direction is not supported by the data. Biggest spends and biggest cache breaks are mostly outside the user's control. Reverting to show the data honestly + the one lever that survived.

---

Final honest scope

IN:

1. Per-account rate-limit capture (0-to-N accounts per provider) — the core of this issue.
2. Codex weekly-limit (secondary window) front and center — per OpenAI, the 7-day secondary window is the real binding wall for heavy users, hit before the 5h primary. Surface it more prominently than the 5h window.
3. The one surviving lever: when Codex approaches a limit → suggest "switch to a mini model (~3.3× longer)" / "switch account" / "wait". OpenAI-endorsed.
4. Descriptive layers (no prescription): per-account live %, per-provider 7d token-burn sparkline, cache-hit-ratio trend. Let the user judge.
5. One small Claude signal: mid-session model-switch count (28/wk, cleanly attributable) shown as an informational hint, not a headline.

OUT (data doesn't justify):

• ❌ "Downgrade your routine Opus work" prescriptive chart (only $103/wk, crude classification).
• ❌ Per-turn "cache breakage attribution" chart (67% = Anthropic cch= rotation, not actionable).
• ❌ ROI badge + 26-week calendar heatmap on Usage page (require plan-price config; removing eliminates the need to configure anything).
• ❌ Hardcoded plan-name table (see caveats).

---

Implementation spec

Phase 1 — Server: per-account capture (foundation)

Branch feat/per-account-rate-limits is currently clean off main — nothing is built yet (the session-start working-tree changes were discarded; HEAD == main).

New server/account-key.js (~60 LOC), 3 exports:

• deriveAccountKey(provider, headers):
  • Codex: headers['chatgpt-account-id'] → openai::<uuid>
  • Claude/API-key: sha256(x-api-key || bearer).slice(0,12) → anthropic::<hash>
  • no credential → null
• normalizeAnthropicRateLimits(parsedRL, accountKey): usedPercent = (limit-remaining)/limit*100; keep absolute tokensLimit/tokensRemaining; secondary: null.
• normalizeCodexRateLimits(event, accountKey): use used_percent/window_minutes/resets_at (epoch→ISO); planType = event.plan_type; tokensLimit/Remaining: null.

Normalized shape (the contract for UI + multi-account):

{ accountKey, provider, updatedAt, planType, displayName,
  primary:   { windowMinutes, usedPercent, resetAt, tokensLimit, tokensRemaining },
  secondary: { windowMinutes, usedPercent, resetAt } | null }

server/store.js: replace singleton rateLimitState with rateLimitAccounts = new Map(); add setAccountRateLimit(key,state) / getAccountRateLimit(key) / getAllAccountRateLimits(). Keep getRateLimitState() returning the most-recently-updated account for backward compat.

server/forward.js (~line 492, Claude HTTP path): after collectRatelimitHeaders, derive key from ctx.clientReq.headers, normalize, store.setAccountRateLimit.

server/ws-proxy.js (~line 498, Codex WS path): codex.rate_limits is currently in WS_SKIP_EVENTS and discarded. Extract it before the skip check: if (parsed.type === 'codex.rate_limits') { deriveAccountKey('openai', ctx.req.headers) → normalizeCodexRateLimits → store.setAccountRateLimit }. Keep it in WS_SKIP_EVENTS (don't push to responseEvents).

Account display name: at spawn, read process.env.CLAUDE_CONFIG_DIR / CODEX_HOME, take basename → titleCase (~/.claude-personal → "Personal"). Fallback provider + hash[:4] ("Claude a1b2"). Expose via /_api/settings or new endpoint. Future: user override.

server/ratelimit-log.js: add optional accountKey to appendSample (append-only, fire-and-forget). NB: ~/.ccxray/ratelimit-samples.jsonl does not exist yet — this feature starts accumulating it.

docs/wire-protocol-reference.md: document the verified codex.rate_limits payload (below) and promote confidence.

Phase 2 — API + UI (Usage page becomes the per-account view)

server/routes/costs.js: /_api/costs/current-block add accounts map (filter stale > 10min). Fix the over-strict display gate: if accounts has fresh data, return active:true even without a JSONL block.

Usage page (public/cost-budget-ui.js, index.html, style.css): remove Zone 2 (ROI) + Zone 3 (heatmap). Replace with a per-account list. Each account row: displayName + status dot (● live / ○ cached) + plan + two bars — for Codex, primary(5h) and secondary(7d, emphasized); for Claude, primary(5h live) + a clearly-labeled "estimated" 7d token-burn bar from JSONL. Render accounts.map(...) so length-1 today extends to N.

Topbar: account pills replacing the single quota ticker (worst-case-first / highest usedPercent). Keep ticker as fallback when Usage page not visible.

Multi-account extensibility

Everything keyed by accountKey; aggregation fns take optional account filter; UI iterates accounts[] (length 1 today). Hard limitation: index.ndjson has no accountKey field today, so 7-day history cannot be split by account retroactively — only by provider. To get per-account history, add accountKey to the index going forward (new data only). Codex personal/work session dirs are symlinked together, so only plan_type distinguishes them in session JSONL.

---

Verified codex.rate_limits payload (from real WS capture + session JSONL)

{ "type": "codex.rate_limits", "plan_type": "prolite",
  "rate_limits": {
    "primary":   { "used_percent": 0,  "window_minutes": 300,   "resets_at": 1779963904 },
    "secondary": { "used_percent": 5,  "window_minutes": 10080, "resets_at": 1780214220 } },
  "additional_rate_limits": { "<model>": { "primary": {...}, "secondary": {...} } } }

(session JSONL uses resets_at; the live WS event uses reset_after_seconds + reset_at — handle both.)

Caveats for whoever implements (all verified or authoritative)

1. Weekly (secondary) is the real wall — surface more prominently than 5h. (OpenAI official.)
2. Don't hardcode a plan-name table. The wire sends plan_type: "prolite" on this machine, but OpenAI's public lineup is Free/Go/Plus/Pro/Business (no "ProLite"). Display whatever the wire reports; do not map.
3. Codex meter has a known bug (resets_at moves backward / used_percent jumps — Codex weekly usage meter switches to inconsistent reset window openai/codex#23190). Sanity-check: if resets_at decreases between polls, label "meter anomaly", don't alarm.
4. Claude has no rate-limit % history — no ratelimit-samples.jsonl, headers not stored per-entry. Claude's 7d bar must be token-burn labeled "estimated", never a fabricated quota %.
5. Account name is best-effort from spawn env; not available for traffic ccxray didn't launch.

Files

server/account-key.js (new), store.js, forward.js, ws-proxy.js, index.js, ratelimit-log.js, routes/costs.js, public/cost-budget-ui.js, index.html, style.css, docs/wire-protocol-reference.md.

Verification (per CLAUDE.md: smoke test, isolated home/port)

CCXRAY_HOME=/tmp/ccxray-rl-$$ ccxray --port 5602 --no-browser

• Claude turn → getAllAccountRateLimits() has anthropic::xxx
• Codex session → openai::uuid, correct planType, secondary window populated
• Usage page (browser-harness): per-account rows, Codex weekly bar emphasized, Claude 7d labeled "estimated", 0-account → hidden
• ratelimit-samples.jsonl gains accountKey

Sources

Anthropic: Manage costs, Prompt caching, Models/usage/limits. OpenAI: Using Codex with your plan, Codex pricing. Meter bug: openai/codex#23190.

[lis186]

Plan 修訂 (2026-06-11) — 讀本地為主 + 統一 adapter 架構

原 proxy-capture plan 在真流量 POC 中發現三個致命限制，已全面重新設計。完整 plan：~/.claude-personal/plans/jolly-dancing-thacker.md。

核心架構轉向

• proxy-capture → 讀本地為主（proxy 降為 Phase 2 可選即時補充層）
• 統一 schema + adapter 模式：每個 provider 寫各自的 adapter（Codex 讀 session JSONL → 統一快照；Claude 攔 statusline → 統一快照），reader 永遠只做 glob + JSON.parse，不因新 agent 而修改

兩階段拆分

• Phase 1：多 provider × 單帳號（Codex 讀 ~/.codex/sessions/，Claude 出 statusline 攔截器寫 ~/.ccxray/usage-status/）
• Phase 2：多 provider × 多帳號（Codex 列舉 ~/.codex-*/，Claude 全 *.json；UI 加標籤）

Onboarding（兩層引導）

• Layer 1 CLI：ccxray claude 啟動偵測「有用 Claude 但無 statusline」→ 首次 y/n 互動確認 → 之後只印提醒一次
• Layer 2 Dashboard：Usage 頁偵測同條件 → 顯示 in-page 引導 → 安裝後消失
• 觸發條件：「有 Claude 流量但無安裝 statusline」，不是「沒有 Claude 帳號」（只用 Codex 的使用者不會被提示）

POC 驗證結論（保留在 reflog）

• proxy-capture 真流量打通 ✅ 但先天做不到 parity
• Codex 本地 ~/.codex-personal rate_limits = buddy app 逐字符合 ✅
• Claude 額度只從 statusline stdin 流出（不持久化本地）✅
• OAuth Claude 不回 ratelimit headers ✅
• Codex token_count event type ≠ codex.rate_limits、plan_type 巢狀 ✅

不碰的熱路徑

forward.js、ws-proxy.js、store.js、account-key.js 全不碰——零 hub crash 風險。