- A user has one live
CODEX_HOME. - Account switching projects only
auth.json. - Codex-owned sessions, databases, configuration, plugins, skills, and UI state are never copied between profile directories.
- The official
codex logincommand owns the login protocol. - Unknown authentication schemas and ambiguous token generations fail closed.
- The live
auth.jsonidentity is authoritative. Persisted active state is a recovery hint and must never override a different live account ID.
authschemavalidates the supported ChatGPT login shape while retaining the complete raw JSON document, including unknown fields.codexloginruns official login in a temporaryCODEX_HOMEconfigured for file storage, then imports the resulting document.secretstoreprotects a small random vault key with the operating-system credential store. WSL uses a Windows PowerShell bridge to protect the key with current-user DPAPI and store only ciphertext in HKCU.vaultencrypts all saved account profiles with XChaCha20-Poly1305.switcherobserves the live identity, classifies external-login and token drift, safely synchronizes known profiles, prepares a journal, performs compare-before-replace, and records the selected profile.codexusageruns the official Codex App Server in an isolated temporaryCODEX_HOME, optionally sends one minimal ephemeral request, and reads the stable account, rate-limit, and token-usage methods.accountusagequeries up to four profiles concurrently, reconciles credential refresh generations, and coordinates with switching through the same lock.usagecachestores credential-free successful snapshots separately from the encrypted vault.projectstatemaintains a credential-free shared local-project catalog, restores a missing desktop projection after account changes, reconciles canonical thread assignments through the official experimental App Server API, and advances the desktop checkpoint only after every assignment is confirmed.atomicfilepublishes complete files and refuses symlink destinations.doctorreports only redacted, non-secret local facts.
acquire lock
-> recover stale journal
-> read and hash live auth
-> identify the live account independently of recorded state
-> reconcile live refresh generation into vault
-> decrypt and validate target
-> if target is already live, repair state without replacing auth.json
-> otherwise verify Codex is stopped
-> persist prepared journal
-> compare live hash again
-> atomically replace auth.json
-> persist active state
-> remove journal
The journal contains only profile IDs, hashes, and timestamps. If the process stops after replacement but before state persistence, recovery compares the live file with both hashes and completes the state transition.
acquire shared operation lock
-> read the desktop legacy project and thread-assignment maps
-> resolve legacy project IDs to App Server project IDs
-> require Codex to be closed
-> initialize App Server with experimental API capability
-> validate every target with project/list
-> apply and confirm thread/metadata/update(projectId) idempotently
-> back up .codex-global-state.json
-> mark thread assignment migration complete and clear its pending queue
The existing legacy assignment map remains intact because current desktop
releases still use it for sidebar ordering and reconciliation. A failed or
interrupted run does not advance the checkpoint, so the repair can safely be
retried. --allow-running is an expert recovery override because an open
desktop process can overwrite its state file from memory.
read live auth and recorded state
-> match account_id plus workspace_id against encrypted profiles
-> prefer one exact credential-material match
-> classify in-sync, external login, refresh, unmanaged, or ambiguous
-> for sync: compare the live hash again
-> adopt only a provably newer live generation
-> persist the derived active pointer
Read-oriented commands use the observation immediately, so a stale recorded
profile never receives the active marker. Observation itself does not modify
state or credentials; the existing live usage-refresh path may still persist a
validated newer token generation. sync performs explicit reconciliation
writes under the shared lock. Unknown and multiple matches are never assigned
by email or alias, and conflicting token generations require --prefer-live.
acquire shared operation lock
-> decrypt and validate selected profile(s)
-> create one temporary CODEX_HOME per profile
-> write only that profile plus file-store config
-> initialize the official Codex App Server
-> read account/read, account/rateLimits/read, and account/usage/read in order
-> retain quota reset times and any earned-reset count and expiration metadata
-> stop the server and delete the temporary home
-> reconcile any newer credential generation, including one produced by a failed query
-> atomically save credential-free usage snapshots
The live account selection never changes. If Codex rotates a refresh token while answering the query, identity and generation checks run before the new document is saved. For an active profile, compare-before-replace protects the live projection from a concurrent Codex write. Transient failures are retried with backoff using the newest validated credential generation returned by the prior attempt. Multi-account refreshes are intentionally sequential so independent App Server processes do not compete for startup or authentication resources.
acquire shared operation lock
-> decrypt and validate exactly one selected profile
-> create a temporary CODEX_HOME and an unrelated empty workspace
-> run one non-interactive, ephemeral Codex turn with a fixed short prompt
-> disable user config and rules; explicitly keep file-backed auth for the temporary home
-> use low reasoning and a read-only sandbox
-> do not retry the turn
-> query the account usage through App Server in the same temporary home
-> reconcile any rotated credential generation and cache the new snapshot
-> delete both temporary directories
The wake path uses the same identity, generation, and active-file reconciliation
checks as a normal usage query. It does not project the target profile into the
shared CODEX_HOME and does not persist a Codex session. A successful turn is
real quota usage; the subsequent snapshot is the evidence available for whether
the service started or advanced a quota window.
CODEX_HOME resolution:
--codex-homeCODEX_HOME~/.codex
codex-switch data resolution:
--homeCODEX_SWITCH_HOME- the operating system's user configuration directory
Only tests and advanced portable installations should normally override these paths.
The usage cache is usage-cache.v1.json inside the resolved codex-switch data
directory. It contains no authentication documents.