Codex provider

Codex has three automatic usage data paths (OAuth API, web dashboard, CLI RPC) plus a manual CLI PTY diagnostic parser and a local cost-usage scanner. The OAuth API is the default app source when credentials are available; web access is optional for dashboard extras.

Data sources + fallback order

App default selection (debug menu disabled)

1. OAuth API (auth.json credentials).
2. CLI RPC through codex app-server.
3. If OpenAI web extras are enabled and a matching OpenAI web session is available (Automatic or Manual cookies), dashboard extras load as a separate follow-up refresh and the source label becomes primary + openai-web.

Usage source picker:

• Preferences → Providers → Codex → Usage source (Auto/OAuth/CLI).

CLI default selection (--source auto)

1. OpenAI web dashboard (when available).
2. Codex CLI RPC through codex app-server.

OAuth API (preferred for the app)

• Reads OAuth tokens from ~/.codex/auth.json (or $CODEX_HOME/auth.json).
• Refreshes access tokens when last_refresh is older than 8 days.
• Calls GET https://chatgpt.com/backend-api/wham/usage (default) with Authorization: Bearer <token>.

OpenAI web dashboard (optional, off by default)

• Enable it in Preferences -> Providers -> Codex -> OpenAI web extras.
• It exists for dashboard-only extras such as code review remaining, usage breakdown, and credits history.
• It is intentionally opt-in because it loads chatgpt.com in a hidden WebView and can materially increase battery or network usage.
• OpenAI web battery saver is a separate toggle. When enabled, routine background/settings-driven refreshes are reduced, but explicit manual refreshes still run.
• OpenAI web battery saver currently defaults to off.
• Preferences → Providers → Codex → OpenAI cookies (Automatic or Manual).
• URL: https://chatgpt.com/codex/settings/usage.
• Uses an off-screen WKWebView with a per-account WKWebsiteDataStore.
  • Store key: deterministic UUID from the normalized email.
• WebKit store can hold multiple accounts concurrently.
• Cookie import (Automatic mode, when WebKit store has no matching session or login required):
  1. Safari: ~/Library/Cookies/Cookies.binarycookies
  2. Chrome/Chromium forks: ~/Library/Application Support/Google/Chrome/*/Cookies
  3. Firefox: ~/Library/Application Support/Firefox/Profiles/*/cookies.sqlite
  • Domains loaded: chatgpt.com, openai.com.
  • No cookie-name filter; we import all matching domain cookies.
• Cached cookies: Keychain cache com.steipete.codexbar.cache (account cookie.codex, source + timestamp). Reused before re-importing from browsers.
• Manual cookie header:
  • Paste the Cookie: header from a chatgpt.com request in Preferences → Providers → Codex.
  • Used when OpenAI cookies are set to Manual.
• Account match:
  • Signed-in email extracted from client-bootstrap JSON in HTML (or __NEXT_DATA__).
  • If Codex email is known and does not match, the web path is rejected.
• Web scrape payload (via OpenAIDashboardScrapeScript + OpenAIDashboardParser):
  • Rate limits (5h + weekly) parsed from body text.
  • Credits remaining parsed from body text.
  • Code review remaining (%).
  • Usage breakdown chart (Recharts bar data + legend colors).
  • Credits usage history table rows.
  • Credits purchase URL (best-effort).
• Errors surfaced:
  • Login required or Cloudflare interstitial.

Codex CLI RPC (automatic CLI source)

• Launches local RPC server: codex -s read-only -a untrusted app-server.
• JSON-RPC over stdin/stdout:
  • initialize (client name/version)
  • account/read
  • account/rateLimits/read
• RPC reads are bounded: initialization has a longer startup budget, and normal requests have a shorter per-method timeout. On timeout, CodexBar terminates the child codex app-server process so the stdout reader unwinds instead of leaving refresh stuck indefinitely.
• Provides:
  • Usage windows (primary + secondary) with reset timestamps.
  • Credits snapshot (balance, hasCredits, unlimited).
  • Account identity (email + plan type) when available.
• App-server errors are terminal for the CLI strategy, except when Codex includes a recoverable wham/usage JSON body in the error text.

Codex CLI PTY diagnostics (/status)

• Manual/debug parser only; automatic background refresh and CodexBarCLI usage --source cli do not launch bare Codex TUI.
• Kept for explicit diagnostics/parser coverage because bare codex TUI can start interactive auth and open browser tabs.
• Parses rendered /status output:
  • Credits: line
  • 5h limit line → percent + reset text
  • Weekly limit line → percent + reset text
• Detects update prompts and surfaces a "CLI update needed" error.

Account identity resolution (for web matching)

1. Latest Codex usage snapshot (from RPC, if available).
2. ~/.codex/auth.json (JWT claims: email + plan).
3. OpenAI dashboard signed-in email (cached).
4. Last imported browser cookie email (cached).

Credits

• Web dashboard fills credits only when OAuth/CLI do not provide them.
• CLI RPC: account/rateLimits/read → credits balance.
• CLI PTY diagnostics can still parse Credits: from saved/manual /status output.

Cost usage (local log scan)

• Source files:
  • Native Codex logs:
    • ~/.codex/sessions/YYYY/MM/DD/*.jsonl
    • ~/.codex/archived_sessions/*.jsonl (flat; date inferred from filename when present)
    • Or $CODEX_HOME/sessions/... + $CODEX_HOME/archived_sessions/... if CODEX_HOME is set.
  • Supported pi sessions:
    • ~/.pi/agent/sessions/**/*.jsonl
• Scanner:
  • Native Codex logs parse event_msg token_count entries and turn_context model markers; when both are present, turn_context is authoritative for the model bucket.
  • pi sessions count assistant-message usage rows and attribute openai-codex assistant usage to Codex.
  • pi assistant usage is bucketed by assistant-turn timestamp, so mixed-model pi sessions can contribute to multiple days/models correctly.
• Cache:
  • Native + merged provider cache: ~/Library/Caches/CodexBar/cost-usage/codex-v2.json
  • pi session cache: ~/Library/Caches/CodexBar/cost-usage/pi-sessions-v1.json
• Window: last 30 days (rolling), with a 60s minimum refresh interval.

Key files

• Web: Sources/CodexBarCore/OpenAIWeb/*
• CLI RPC + diagnostic PTY parser: Sources/CodexBarCore/UsageFetcher.swift, Sources/CodexBarCore/Providers/Codex/CodexStatusProbe.swift
• Cost usage: Sources/CodexBarCore/CostUsageFetcher.swift, Sources/CodexBarCore/PiSessionCostScanner.swift, Sources/CodexBarCore/PiSessionCostCache.swift, Sources/CodexBarCore/Vendored/CostUsage/*