Codex Pool Manager is a macOS app for operating a pool of Codex/OpenAI OAuth accounts from one control panel.

It helps you:

• track quota and remaining usage per account,
• switch the active auth account quickly,
• auto-rotate accounts with an intelligent policy,
• monitor status from Desktop Widget and Menu Bar,
• keep backup/export flows for recovery.

Languages: 繁體中文 · 简体中文 · 日本語 · 한국어 · Français · Español

1. Screenshots
2. Key Features
3. How Intelligent Switching Works
4. Widget + Menu Bar
5. In-app Update Checks
6. Authentication and Account Import
7. Workspaces
8. Install
9. Build From Source
10. Release DMG Pipeline
11. Project Structure
12. Testing
13. Troubleshooting
14. Security and Privacy Notes
15. Contributing

All screenshots below use mock or non-sensitive test data.

• Add, edit, duplicate, and remove accounts.
• Group accounts and manage groups (Add, Rename, Delete).
• Group deletion removes all accounts in that group.
• Sort and layout controls for large pools.
• Minimal layout uses adaptive card sizing so column count responds to window width.
• Dedup-aware pool statistics (Accounts, Available, Pool Usage) to avoid counting duplicated identities multiple times.

• Intelligent: auto-selects the best account based on remaining capacity and policy thresholds.
• Manual: sticks to the account you manually choose.
• Focus: pins to the current account and avoids intelligent auto-rotation.

• Sync usage from Codex/OpenAI endpoints for all eligible accounts.
• Handles sync exclusions (missing token, missing account id, API/network errors).
• Shows last successful sync time and sync error details.
• Includes raw usage JSON and switch logs for diagnostics.

• In-app OAuth sign-in and direct import.
• Manual flow: copy authorization URL, paste callback URL, then import.
• Local auth discovery from common local paths.
• Import local OAuth sessions/accounts into managed pool.

• Native macOS notifications for key events (sync failure/recovery, low usage, auto-switch outcomes).
• Menu Bar extra that shows live remaining usage summary.
• macOS Widget extension for quick status glance.

• Export JSON snapshot.
• Export refetchable snapshot (sensitive; includes fields needed for re-fetch workflows).
• Import JSON snapshot for migration/recovery.

• Dark mode + light mode.
• Language switching via app settings.
• Locale-aware time formatting for app/widget texts.

• Dedicated Schedule workspace for reset timeline planning across accounts.
• Daily/weekly usage analytics to identify consumption patterns.
• Coverage view to highlight potential uncovered windows between account resets.
• Per-account trend lines, threshold events, and anomaly summaries.
• Export analytics as JSON/CSV for reporting or external analysis.

• Dedicated OpenAI Reset Alert workspace for paid-account reset tracking.
• Monitors weekly reset and 5-hour reset targets together.
• Flags early reset signals when resets move earlier than expected (within configurable tolerance).
• Optional desktop notifications and event history for auditability.
• Daily notification cap to reduce noisy false positives during unstable API periods.

This section explains the exact runtime behavior so release users understand what to expect.

Only accounts that are not excluded from sync/scheduling are considered for automatic switching.

Examples of exclusion reasons:

• missing API token,
• missing ChatGPT account id,
• sync error status.

• Non-paid account: intelligent remaining is based on weekly remaining ratio (remainingUnits / quota).
• Paid account (default): intelligent remaining uses the 5-hour remaining percentage.
• Paid account special case: if weekly remaining is already 0%, weekly remaining is treated as source of truth (account is effectively exhausted).

From eligible accounts, the engine chooses the best candidate by highest intelligent remaining ratio.

Accounts with weekly remaining <= 0 are not eligible candidates.

In Intelligent mode, switching happens only when all are true:

1. there is a valid candidate;
2. current active account is low enough (below intelligent switch threshold);
3. candidate is better than current;
4. cooldown interval has elapsed.

When switching into Focus, current account is pinned to prevent unexpected jumps. No intelligent auto-switch is performed in focus mode.

There are two different thresholds:

• Intelligent switch threshold: controls when switching is allowed.
• Low remaining usage alert threshold: controls when warning/notification is shown.

These are intentionally independent.

• Widget reads snapshot from local bridge endpoint exposed by the main app.
• If no snapshot is available, widget shows a friendly empty-state prompt.
• Timeline refresh policy:
  • around every 60s when snapshot exists,
  • around every 10s when snapshot is missing.

• Menu bar title contains compact status (remaining %, paid 5h left, update age).
• Menu content shows active account details, reset times, and update age.
• Refreshes periodically (every ~15s) and supports manual refresh.

• Checks GitHub latest release metadata and compares against current app version.
• Supports normalized version parsing (for example v1.8.0 and 1.8.0).
• Auto-selects preferred installer by architecture (Apple Silicon / Intel) when available.
• Provides Install now, Manual download, and Skip this version actions in update dialog.

The app scans local auth JSON from common locations:

• ~/.codex/auth.json
• ~/.config/codex/auth.json
• ~/.openai/auth.json

By default, the app supports public client flow and also allows your own OAuth client parameters.

If browser callback cannot complete directly in-app:

1. click Copy URL and Manual sign in;
2. complete sign-in in browser;
3. paste callback URL into the callback field;
4. click Import.

The UI is organized into workspaces for clearer operational boundaries.

• OAuth sign-in panel
• Advanced OAuth parameters
• Local OAuth account scanning/import

• mode selector (Intelligent, Manual, Focus)
• intelligent switch threshold
• low-usage alert threshold
• launch target selection for Switch and launch
• smart recommendation panel

• reset timeline overview across managed accounts
• daily/weekly usage analytics summaries
• coverage gap hints for planning account usage
• per-account trend lines and threshold/anomaly events
• analytics export (Copy JSON, Export CSV, Export JSON)

• paid-account reset target tracking
• early-reset tolerance configuration
• early-reset signal detection summary and records
• optional desktop alerting + event list management

• launch behavior
• auto-sync toggle + interval
• language
• appearance (system/dark/light)

• backup/export/import controls
• diagnostics surface for raw data/log verification

Release assets provide two architecture-specific DMGs:

• CodexPoolManager-<version>-apple-silicon.dmg
• CodexPoolManager-<version>-intel.dmg

Pick the one matching your Mac architecture.

See next section.

• macOS
• Xcode 16+

cd /path/to/AIAgentPool
open CodexPoolManager.xcodeproj

In Xcode:

1. Select the CodexPoolManager scheme.
2. Choose your local Mac destination.
3. Build and Run.

If you also need widget testing, make sure widget-related targets are signed with the same team where required.

Automated DMG packaging + notarization is configured in:

• .github/workflows/release-dmg.yml
• scripts/build_and_notarize_dmg.sh

• Builds both arm64 and x86_64 variants.
• Uses release version/tag for artifact naming (not commit hash).
• Signs with Developer ID Application certificate.
• Notarizes and staples each DMG.
• Uploads DMGs to both workflow artifacts and GitHub Release assets.

• APPLE_CERTIFICATE_P12_BASE64
• APPLE_CERTIFICATE_PASSWORD
• KEYCHAIN_PASSWORD
• APPLE_TEAM_ID
• APPLE_API_KEY_ID
• APPLE_API_ISSUER_ID
• APPLE_API_PRIVATE_KEY_BASE64

For detailed setup docs, see RELEASE_DMG.md.

AIAgentPool/
├─ CodexPoolManager/                 # Main macOS app target
├─ CodexPoolWidget/                  # Widget extension target
├─ CodexPoolWidgetHost/              # Companion host target for widget bridging/testing
├─ Domain/Pool/                      # Core state, switching rules, snapshot model
├─ Features/PoolDashboard/           # UI + flow coordinators
├─ Infrastructure/Auth/              # OAuth, auth file access/switch services
├─ Infrastructure/Usage/             # Usage sync client/service
├─ CodexPoolManagerTests/            # Unit tests
├─ CodexPoolManagerUITests/          # UI tests
├─ .github/workflows/release-dmg.yml # Release workflow
└─ scripts/build_and_notarize_dmg.sh # Local/CI DMG script

Run tests in Xcode, or via command line:

xcodebuild \
  -project CodexPoolManager.xcodeproj \
  -scheme CodexPoolManager \
  -destination 'platform=macOS' \
  test

Build release configuration:

xcodebuild \
  -scheme CodexPoolManager \
  -destination 'platform=macOS' \
  -configuration Release \
  build

Localization sanity checks:

for f in CodexPoolManager/en.lproj/Localizable.strings \
         CodexPoolManager/zh-Hans.lproj/Localizable.strings \
         CodexPoolManager/zh-Hant.lproj/Localizable.strings; do
  plutil -lint "$f"
done

• Confirm network/API availability.
• Check Sync Error callout for details.
• Ensure active accounts have valid token and account id.
• Try manual sync again after a short interval.

• Open CodexPoolManager once (widget bridge is published by main app).
• Wait a few seconds and refresh widget.
• Verify local firewall/network rules do not block localhost loopback.

• Use Choose auth.json and grant permission manually.
• Verify auth data exists in one of the known candidate paths.

• Check whether current remaining is below switch threshold.
• Check cooldown interval.
• Check candidate account eligibility and remaining values.
• In focus mode, intelligent switching is intentionally disabled.

• Refetchable exports may contain sensitive values.
• Do not share raw logs or exports publicly without redaction.
• Use secure storage for internal snapshots.
• OAuth/client credentials should be handled according to your security policy.

Issues and PRs are welcome.

Recommended PR scope:

• one behavior change per PR,
• include test coverage for domain or coordinator logic,
• include before/after screenshots for UI changes.

If this project helps your Codex account operations, consider starring the repository.