Codex Auth v0.2 Released: API Usage and Automatic Account Switching

I’m thrilled to announce the release of the Codex Auth v0.2 beta! 🎉

In this version, we’ve completely refactored the underlying architecture to solve the issue where a single regular account might be bound to multiple different Team workspaces. At the same time, to address the unreliable local session file usage tracking from the previous version, we’ve introduced a brand-new API mode. Furthermore, we’ve added an experimental background service for automatic account switching.

⚠️ STRONGLY RECOMMENDED: Please backup before upgrading

Before upgrading, please make sure to back up your current ~/.codex/auth.json file. If you have previously added multiple accounts using codex-auth, please also back up your entire ~/.codex/accounts directory just in case.

✅ Upgrade and Experience Now

v0.2 is still in beta. We only recommend enabling the API usage query after updating; as for the background account switching feature, we suggest waiting for continuous iterative updates.

• Install the beta version

npm install -g @loongphy/codex-auth@next

• Enable API usage query

codex-auth config api enable

📖 About Codex Auth

If you’re not yet familiar with this project, Codex Auth is a local command-line tool designed specifically for managing and seamlessly switching between multiple Codex accounts. Its biggest highlight is its zero-intrusiveness: you don’t need to modify any of Codex’s configuration files, nor do you need to deploy any extra proxy services. You can easily manage and switch accounts with just simple command-line operations. Repository: https://github.com/Loongphy/codex-auth

Codex Auth is perfectly compatible with the three mainstream Codex usage scenarios:

• Native Codex-CLI command-line invocation (when using the official codex-cli, you need to exit and restart after switching accounts, or use the modified version codext). For more details, see Building a Smoother Codex than the Official One: Automated Skills Sync with Upstream.
• Independently running Codex App
• Built-in invocation via the VSCode Extension

Here are the key highlights of this update.

💡 Core Features

1. API Usage Query

Initially, we had no intention of introducing any API calls to this fully localized tool, to avoid the risk of being monitored by OpenAI and causing account bans. However, tracking usage via local files (rollout-*.jsonl) has recently become highly unreliable, often resulting in rate_limits: null situations (for details, see OpenAI Codex Issue #14880).

For accuracy, we referred to the quota retrieval method of Codex-CLI and introduced support for real-time usage via API!

• How to enable: This feature is disabled by default. You can manually turn it on by executing codex-auth config api enable to enjoy precise quota monitoring.
• Future plans: This mode is planned to be the default usage synchronization method in v0.3.

2. Smart Background Auto-Switching 🧪 Experimental Feature

In high-frequency daily use cases, manually switching accounts after entirely depleting a quota often disrupts your state of flow. To solve this problem, v0.2 introduces a brand-new background daemon mechanism.

This process can continuously monitor your current usage status in the background. When your remaining quota drops below a set threshold, it will automatically switch to the most optimal available account for you.

The default setting triggers a switch when the remaining quota drops to 10% within a 5-hour window or 5% for the weekly quota.

Common Commands:

# Enable
codex-auth config auto enable

# Disable background switching (default)
codex-auth config auto disable

# Customize warning thresholds
codex-auth config auto --5h 15 --weekly 10

3. A Boon for Multi-Subscription Users: Account Grouping

This is a fundamental architectural upgrade. Previously, we used email addresses as the primary key to store account information, but this could not satisfy complex scenarios like “a single email under multiple workspaces or different subscription plans (e.g., Team, Free/Plus/Pro coexisting).”

In v0.2, when you run list or switch, the program will automatically group and collapse multiple subscription plans under the same email alias. This makes it much more visually intuitive and clear, while still retaining the flexibility of independent switching.

Other New Commands

We have also greatly enhanced the routine maintenance commands, ensuring your environment remains stable and controllable under various extreme edge cases:

• codex-auth status: View the background service status, auto-switch toggle, and API usage mode with one click.
• codex-auth daemon --watch|--once: Run in the foreground or test the background switching logic.
• codex-auth clean: A general cleanup command (not recommended for execution), used to remove out-of-date authorization snapshots and old backup files.
• codex-auth import --purge: An exclusive command for disaster recovery. By utilizing existing authorization snapshot files, you can rebuild the registry from scratch. If things don’t work correctly after an update, you can try using this command.

📦 For Contributors: Introducing PR Preview Deployments

To speed up the review and testing of community contributions, we have introduced pkg.pr.new support in our CI workflow.

Now, every Pull Request will automatically build and publish platform-specific preview packages, whilst still retaining the smart feature of parsing on-demand dependencies based on OS/CPU. You can even intuitively see the preview build source by using --version: codex-auth 0.1.5 (preview pr-6 b6bfcf5)

Want to quickly help test a PR? Just execute something like this:

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

Want to test a build from a specific commit in that PR? Use something like:

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

If you encounter any issues while using it, please feel free to join us at our GitHub Repository to communicate or submit an Issue!