pi-codex-account-switcher

A Pi extension for switching between OpenAI Codex OAuth accounts and monitoring their remaining quota.

Install

pi install npm:pi-codex-account-switcher

Requires Pi 1.1.0 or newer. Restart Pi or run /reload after installation.

Do not keep an older standalone ~/.pi/agent/extensions/codex-account.ts enabled alongside this package. Both extensions would register the same command and footer status.

Setup

Log in to Codex with Pi, then save the active account. Without a name, the extension uses the email returned by OpenAI:

/login openai-codex
/codex-account save

A custom local name is also supported:

/codex-account save work

Accounts are identified by OpenAI accountId, not by their local filename. Saving without a name updates an existing entry for that account and preserves its custom name. Saving the same account with a different explicit name renames the existing entry instead of creating a duplicate. Historical duplicate entries are merged on save.

Repeat the login and save steps for each account. Credentials remain local under ~/.pi/codex-accounts/ and are not included in this package.

Usage

/codex-account

The chooser displays each account in this format:

xianyu 5h 83% • 7d 45% • reset 1 • 10d left
bpldbt 5h 92% • 7d 71% • reset 3 • 8h left (current)

After selecting an account, choose whether it applies to the current session only or to all sessions.

Additional commands:

/codex-account list
/codex-account status
/codex-account start-window
/codex-account reset
/codex-account delete [name]
/codex-account save [name]

• delete permanently removes a saved account credential after confirmation. Deleting the active global account or current session account is blocked until switched.
• start-window asks for confirmation, then sends one private minimal model request with the selected account. This consumes a small amount of quota and may start its five-hour usage window.
• reset consumes an available OpenAI quota reset credit after confirmation.
• status also shows the latest recorded Codex dispatch on the active session branch: the saved account name (or unknown saved account), masked account ID, model, and timestamp. The identity comes from the access token actually passed to the request layer, not the current chooser selection. Records survive /reload; no tokens, full account IDs, or prompts are stored, and records are excluded from model context. This is dispatch evidence, not server-side billing confirmation; recording failures can leave newer requests unrecorded. Private start-window probes and quota checks are excluded.
• Every interactive session shows a Codex accounts widget above the editor. It displays cached usage immediately, refreshes every saved account in the background, updates each row as it completes, and hides 15 seconds after all refreshes finish.
• The account chooser opens immediately with the last successful per-account quota cache (or placeholders), then replaces each row as its background refresh completes. A failed refresh keeps the cached values visible.
• At the start of every Codex turn, quota is refreshed immediately in the background; long-running turns refresh it again once per minute.
• Session-only selection is stored in the Pi session and does not rewrite the global auth.json account. It supplies the selected access token to both SSE and WebSocket model requests; unusable saved credentials stop the request instead of falling back to the global account.
• Saved OAuth credentials are refreshed automatically when the access token is close to expiry. If the usage API returns 401 / token_expired earlier, the extension refreshes that account's credentials and retries the read-only usage request once. Concurrent requests share the refreshed credentials; failed recovery attempts are throttled for five minutes. Credit-consuming requests are never replayed.
• Credential writes use a shared cross-process lock, so account refresh, save, and global switch operations cannot overwrite one another across Pi sessions.
• Subscription expiry is read from OpenAI's current account entitlement APIs, following Cockpit Tools' accounts/check → subscriptions fallback. Responses are accepted only for the saved accountId; ID-token metadata remains a fallback only.
• Subscription query results distinguish available metadata, a successful response with no expiry (sub --), and request or account-validation failures (sub error).

Footer format:

codex:xianyu • 5h 83%(2h 14m) • 7d 45%(5d 6h 57m) • reset 1

Security

This extension reads and updates Pi's local OpenAI Codex OAuth credentials to switch accounts. It contacts only OpenAI's ChatGPT usage and OAuth endpoints. Saved credentials and backups remain outside the npm package. Do not publish auth.json or ~/.pi/codex-accounts/.