Accounts
An account is one OpenAI account, one ChatGPT Web account, or one custom-model account. It is never a mix. Each account keeps its own Codex home, auth, config, and local history, and each account gets exactly one Codex window. The Accounts tab lists them with a status word, a headroom meter, and one action: Open or Show.
Add an OpenAI account
- Open Accounts and click Add account.
- Choose Sign in with OpenAI and finish the sign-in in your browser.
- Give the account a label you will recognize later (Work, Personal, Client). Leave it empty to show the email only.
The account appears in the list as Ready. No window opens until you click Open.
Add a ChatGPT Web account
A ChatGPT Web account answers Codex tasks from your own ChatGPT session instead of the Codex models, so its turns spend the Chat allowance rather than the Codex allowance of any OpenAI account. CodexUse does that by reading the ChatGPT page, typing the turn, and sending it, which is not an official OpenAI integration and may not be permitted under your agreement with OpenAI.
Setup needs an OpenAI Tunnel, a secret API key with Tunnels Read and Use, a connector you create in ChatGPT Developer Mode, and one OpenAI account already signed in on this Mac. It has no headroom meter, because ChatGPT reports no remaining percentage for this route, so it stays out of percentage-based auto-roll and Account Pool. The full walkthrough and its limits are in ChatGPT Web accounts.
Add a custom-model account
- Add the provider first under Settings → Model Providers: a name, a base URL, a credential, and at least one published model. See custom model providers.
- Open Accounts, click Add account, and choose Use a custom model.
- Pick the provider, the published models, and a default model.
A custom-model account uses no OpenAI quota and has no headroom meter. Its status is Ready once the provider verifies, and Needs setup when the provider or its models are missing or conflict.
Status words
Every account shows one of seven words. The row, the detail header, the ⌘K palette, and the menu bar all use the same word.
| Status | Meaning | Action |
|---|---|---|
| Open | This account’s Codex window is running and idle. | Show |
| Busy | The window is running and generating a response. | Show |
| Ready | Signed in, no window running, headroom above your warning level. | Open |
| Low | Signed in, no window running, one of its usage windows is below your Warn below or Roll below level. | Open |
| Needs sign-in | The OpenAI login expired or was revoked. Sign in again; nothing else is deleted. | Sign in |
| Needs setup | A custom-model account whose provider or model list is missing or invalid. | Fix it in Model Providers |
| Opening… | CodexUse is starting the window. Lasts a few seconds. | Wait |
Open and Show
An account has one action, and which one you see depends on its status.
- Open starts the account’s Codex window with that account’s own Codex home. Every other account’s window keeps running and stays signed in.
- Show brings the running window to the front.
One account never gets two windows. If a window is already running, the action is Show, even from the ⌘K palette, the menu bar, or History. Press ⌘K anywhere in CodexUse to jump to an account or a run by name.
Outside windows
A Codex window that CodexUse did not open, for example one you started from Finder, shows an Outside CodexUse badge beside its status. CodexUse can see it but does not control it. Two ways to bring it under CodexUse:
- Quit that window yourself, then click Open.
- Turn on Take over outside windows in the Auto-roll menu. CodexUse then restarts an outside window under the right account when it needs to. Restarting that window loses unsaved work in it, so CodexUse asks before the first take-over.
Headroom
Headroom is the percent of quota left that the Codex app reports for each usage window: 5-hour, 7-day, and 30-day when your plan has one. CodexUse reads it after the account’s next Codex run and shows it under Quota left in the account detail. Use Check usage in the account menu to read it again now. CodexUse cannot add quota; it shows you where the quota is before a request fails.
Refill timers
Refill controls attempt a short background Codex request for an OpenAI account. OpenAI controls usage periods and when quota becomes available; CodexUse cannot speed up a refill or add quota. Read the reported refill time and the activity log for the result.
- Start refill timers automatically: after Auto-roll leaves an exhausted account, attempt a short background Codex request on that account. A rate limit can still prevent the request.
- Start refill timers now: attempt a short request for eligible signed-in OpenAI accounts. Excluded or known-exhausted accounts are skipped. Custom-model accounts may open their window instead.
Auto-roll Trial and Pro
Auto-roll moves the active account, the one the Codex CLI and the menu bar use next, to the next account in your priority order when headroom drops. It lives behind the Auto-roll button at the top of the Accounts tab and shows the current threshold or off.
- Roll below X%: roll when the active account drops below this level.
- Rejoin above Y%: reuse an account once it refills above this level.
- Warn below Z%: send a Mac notification when an account drops below this level. Turn the toggle on; the number alone does nothing.
- Priority order: in each account’s detail, Include in auto-roll adds it to the list; the arrows move it earlier or later.
- Recent rolls: the log of what Auto-roll did and why, including duplicate-account skips.
Auto-roll never moves an open conversation between windows, and it never opens a second window for the same account. Read Auto-roll guardrails for the confirm countdown and the failure cases.
Account settings overrides
All accounts share one set of Codex defaults in Settings: model, reasoning, approval, sandbox, and MCP servers. When one account needs different values, add an override for that account. An override replaces only the keys it defines. CodexUse protects auth and provider-routing values, so an override cannot point an account at a different login or provider. See Settings & config.
Rename or remove an account
The More account actions menu on the account detail has Rename and Remove account…. Removing an account deletes its saved login and CodexUse config for that account. It does not sign the account out on OpenAI’s side and does not touch other accounts. When a login expires, use Sign in instead; the account and its config stay.
Duplicate account warning
When two accounts resolve to the same OpenAI identity, CodexUse flags them, because they draw on the same headroom. Two entries for one identity do not give you more quota, and Auto-roll skips the duplicate. Read why duplicate accounts matter.
Account Pool
Account Pool exposes selected accounts through one local OpenAI-compatible API for other apps, with load balancing and failover. Turn an account on with Serve in Account Pool in its detail. The pool draws on the real headroom behind those accounts, and account limits still apply. See Account Pool.
Trial and Pro
- Trial: unlimited accounts, Auto-roll, and Account Pool for 7 days.
- After the trial, features lock until you buy Pro. Nothing is deleted.
What this does not claim
- CodexUse does not create extra Codex quota. It shows each account’s headroom and opens the right window.
- CodexUse does not merge cloud histories or move a conversation between accounts. History opens each task in the account that owns it.
- Hosted ChatGPT features such as dictation and browser remote control need an OpenAI account. They do not work in a custom-model account’s window.
- Taking over an outside window restarts it, and unsaved work in it is lost.