Multi-Workspace Support, Auto-Switching, and Usage API Integration

[Loongphy]

This PR introduces significant architectural improvements to codex-auth, moving from email-keyed storage to account_id identity. It also adds a background auto-switch daemon and an API-based usage refresh mode to address reliability issues with local session files.

🚀 Key Features

1. Reliable Usage Tracking (API Mode)
   Added support for fetching ChatGPT usage directly via the /backend-api/wham/usage endpoint.

• Why: Local rollout/session files (rollout-*.jsonl) now frequently return rate_limits: null, making local-only usage tracking unreliable.
• Reference: OpenAI Codex Issue #14880
  (rate_limits is always null in rollout session files openai/codex#14880)
• Status: Currently disabled by default (config api disable). Planned as default for v0.3.

2. Intelligent Auto-Switching
   A background daemon that monitors usage and automatically switches to the best available account when thresholds are met.

• Configurable Thresholds: Default is 10% for 5h quota and 5% for weekly quota.
• Platform Support: Integrated with systemd (Linux/WSL), LaunchAgent (macOS), and Scheduled Tasks (Windows).

3. Grouped Account Display & Identity Migration

• Account-ID Registry (Schema v3): Migrated the registry from email-based keys to unique account_id keys. This allows a single email to own multiple workspaces or plans (e.g., Team, Pro, Plus) simultaneously.
• Grouped UI: The list and switch commands now group multiple plans under the same email header while keeping them individually selectable.

4. Robust Login Recovery
   If the embedded codex login process fails to start, the tool now provides clear, actionable instructions for manual recovery.

🛠 New & Updated Commands

• status: View the state of auto-switch, background services, and usage refresh mode.
• config:
  • config auto enable|disable: Toggle background switching.
  • config auto --5h <%> [--weekly <%>]: Tune switch thresholds.
  • config api enable|disable: Toggle between API-based and Local-only usage refresh.
• daemon --watch|--once: Run or test the background switching logic.
• clean: Maintenance command to remove stale auth snapshots and old backups.
• import --purge: Rebuilds the registry from existing snapshot files (useful for manual recovery).
• switch []: Enhanced matching by alias or email fragment.

📦 Registry Migration (Technical Note)

• Upgrades registry.json to Schema Version 3.
• Auto-migrates legacy v2 (email-keyed) registries on first run.
• Includes automatic backup logic for registry.json and auth.json during transitions.

📦 PR Preview Packages

• Added .github/workflows/preview-release.yml so each pull request publishes installable preview packages through pkg.pr.new.
• Preview installs keep the existing root-package plus platform-package layout, so the root package still resolves the matching optional dependency for Windows x64, macOS x64, macOS arm64, or Linux x64.
• Preview installs now surface their source build in --version, for example: codex-auth 0.1.5 (preview pr-6 b6bfcf5).
• Example preview smoke test: npx https://pkg.pr.new/@loongphy/codex-auth@6 --version.

🔗 Related Issues

• Closes 有个AccessDenied错误 #8: Added extra information prompts and status indicators to improve user feedback during usage tracking.

✅ Verification & Testing

• Functional Test: zig build run -- list (Verified registry migration and grouped display).

• Unit/BDD Tests: zig test src/main.zig -lc (Covered 5h/weekly scoring, migration logic, and API parsing).

• Cross-Platform: Verified service installation on Linux (systemd) and Windows (task scheduler).

• PR Preview Publish: Verified the Preview Release workflow can publish pkg.pr.new packages for PR Multi-Workspace Support, Auto-Switching, and Usage API Integration #6 and that preview installs expose the preview identifier in codex-auth --version.

Note

Add multi-workspace support, auto-switching daemon, and usage API integration to codex-auth

• Introduces account_key (derived from chatgpt_user_id::chatgpt_account_id) as the primary account identity across the registry, CLI, and file paths, replacing email-based keying throughout.
• Adds a background auto-switch daemon (src/auto.zig) with cross-platform file locking, configurable usage thresholds, and status/config auto/config api CLI commands.
• Adds a usage API integration (src/usage_api.zig) that fetches live RateLimitSnapshot data from the ChatGPT usage endpoint for the active ChatGPT account.
• Migrates the registry from schema v2 (email-keyed) to v3 (account_key-keyed) with automatic on-load migration, atomic writes, and a new import --purge mode that rebuilds the registry from existing snapshots.
• Adds a Windows-specific codex-auth-auto.exe helper binary (src/windows_auto_main.zig) built and packaged alongside the main binary.
• Accounts with the same email are now grouped hierarchically in all list/switch/remove UIs via src/display_rows.zig, with non-selectable header rows and stable numbered selection.
• Risk: Registry schema v3 is not backward-compatible with v2 readers; existing installs are migrated automatically on first load, but downgrading will require import --purge to recover.

^{Macroscope summarized b0c95f3.}

[pkg-pr-new]

Open in StackBlitz

@loongphy/codex-auth-darwin-arm64

npx https://pkg.pr.new/@loongphy/codex-auth-darwin-arm64@6

@loongphy/codex-auth-darwin-x64

npx https://pkg.pr.new/@loongphy/codex-auth-darwin-x64@6

@loongphy/codex-auth-linux-x64

npx https://pkg.pr.new/@loongphy/codex-auth-linux-x64@6

@loongphy/codex-auth-win32-x64

npx https://pkg.pr.new/@loongphy/codex-auth-win32-x64@6

@loongphy/codex-auth

npx https://pkg.pr.new/@loongphy/codex-auth@6

commit: b0c95f3