codex-switch manages multiple Codex login snapshots behind short aliases and swaps the active login by rotating ~/.codex/auth.json.

The tool is intentionally narrow:

• Only ~/.codex/auth.json is rotated between aliases.
• Other Codex state such as config, history, logs, and related files remain shared in ~/.codex.
• Mutating commands refuse to run while a Codex process is active.

For normal CLI use, install with pipx so codex-switch and codex-switchd are on your PATH without activating a virtual environment:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install --editable .

On PEP 668 managed systems such as Ubuntu 24.04, install pipx with your OS package manager first:

sudo apt install -y pipx
pipx ensurepath
pipx install --editable .

If you are developing on the repository and want the traditional editable environment with test dependencies, use a local virtual environment instead:

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'

Captures a fresh codex login session into a named snapshot. The existing active login is restored after capture. Use --device-auth when you need the Codex device-code flow instead of the default browser login.

Lists configured aliases. The active alias is marked with *. Plain list shows cached account plan type plus remaining 5-hour and weekly usage when telemetry is available. Missing usage values render as ?.

Pass --refresh to re-probe aliases whose telemetry is missing or older than the 15-minute freshness window before printing the list. Refresh probes run in isolated temporary Codex homes built from each alias snapshot, so they do not rotate your live ~/.codex/auth.json.

Display mode is controlled by ~/.codex-switch/config.json:

{
  "list_format": "labelled"
}

Accepted values are labelled and table. Missing or invalid config falls back to labelled.

Copies the stored snapshot for <alias> into ~/.codex/auth.json and marks that alias active.

Shows the active alias, whether its snapshot exists, whether ~/.codex/auth.json exists, and whether the live auth file has drifted from the stored snapshot.

Deletes a stored alias snapshot. Removing the active alias is refused.

Initializes automation state storage and daemon directories under ~/.codex-switch/.

Manages a user-level systemd service for codex-switchd. enable writes ~/.config/systemd/user/codex-switchd.service, reloads the user daemon, and enables the service to start automatically on login. disable stops and disables that service.

Manages the background codex-switchd process used for automation monitoring. When the user-level systemd service is installed, these commands use systemctl --user.

Shows automation readiness for the active alias, including latest telemetry source and whether a soft-switch trigger is armed.

Shows the latest telemetry source timestamp for each configured alias.

Shows recent recorded switch events from the local automation database.

Attempts codex resume <thread_id> when automation is in failed_resume handoff state and clears the handoff record on success.

Check the current state first:

codex-switch status
codex-switch list
codex-switch list --refresh

If codex-switch shows active alias: none but your live ~/.codex/auth.json already exists, bootstrap that current login once before adding the others:

python3 - <<'PY'
from dataclasses import replace

from codex_switch.accounts import AccountStore
from codex_switch.manager import utc_now
from codex_switch.paths import resolve_paths
from codex_switch.state import StateStore

paths = resolve_paths()
accounts = AccountStore(paths.accounts_dir)
state = StateStore(paths.state_file)
current = state.load()

accounts.assert_missing("alpha")
accounts.write_snapshot_from_file("alpha", paths.live_auth_file)
state.save(replace(current, active_alias="alpha", updated_at=utc_now()))
PY

Example first-time setup:

codex-switch add beta --device-auth
codex-switch add gamma
codex-switch add delta
codex-switch add epsilon
codex-switch use epsilon
codex-switch list

Labelled output:

  beta -- plus -- 5h left: ? -- weekly left: ?
  delta -- 5h left: ? -- weekly left: ?
* epsilon -- 5h left: ? -- weekly left: ?
  gamma -- pro -- 5h left: ? -- weekly left: ?

Table mode config:

{
  "list_format": "table"
}

Switch accounts when you hit limits:

codex-switch use alpha
codex-switch use beta
codex-switch status

Start automation daemon management:

codex-switch daemon install
codex-switch daemon enable
codex-switch daemon status

Disable the login-time service again if you no longer want automatic startup:

codex-switch daemon disable
codex-switch daemon status

Inspect automation telemetry and decisions:

codex-switch auto status
codex-switch auto source
codex-switch auto history --limit 10

Remove an alias you no longer need:

codex-switch remove epsilon

codex-switch does not create isolated Codex homes. It only rotates ~/.codex/auth.json so account login can change while the rest of the Codex directory stays shared.

codex-switch list --refresh is the exception for telemetry probing: it stages each alias in an isolated temporary Codex home so usage can be refreshed without mutating the live auth file.

For safety, mutating commands such as add, use, and remove refuse to run while Codex is active.