codex-auth-switcher

Switch between multiple Codex CLI accounts without splitting local chat/session history.

codex-auth-switcher keeps one shared CODEX_HOME (sessions/history/state stay intact) and switches only credentials.

Why this tool

Using separate CODEX_HOME directories per account fragments local context. This tool avoids that by storing per-account credential snapshots in a separate state directory and applying one profile at a time to the same CODEX_HOME.

Features

• Account profiles with fast switching
• Shared sessions/history/state across profiles
• Support for Codex auth storage modes: file, keyring, auto
• Profile-aware login and logout flows
• Manual and bulk token refresh (refresh, refresh --all, switch --refresh)
• Usage limits fetch per profile with clean window/reset display in local timezone, including a (current) marker on the active profile (limits, limits --all)
• Token health inspection (inspect)
• Health and repair diagnostics (doctor)
• Machine-readable output for scripting (--json)
• Shell completions for bash, zsh, fish

Requirements

• Go 1.26.0
• codex CLI installed and available on PATH

Install

make build-small

Or:

go install github.com/sasanktumpati/codex-auth-switcher@latest

Manual small build (without make):

CGO_ENABLED=0 go build -trimpath -ldflags='-s -w -buildid=' -o codex-auth-switcher .

Quick start

# 1) Create two profiles from current active Codex auth
codex-auth-switcher create personal
codex-auth-switcher create work

# 2) Switch profiles (shared CODEX_HOME remains unchanged)
codex-auth-switcher switch personal
codex-auth-switcher switch work --refresh

# 3) Verify
codex-auth-switcher list
codex-auth-switcher inspect work
codex-auth-switcher limits --all
codex-auth-switcher doctor --json

Diagnostics and scripting

# Inspect overall health
codex-auth-switcher doctor

# Use structured output in scripts
codex-auth-switcher list --json
codex-auth-switcher limits --all --json
codex-auth-switcher doctor --json

Commands

create <profile> [--empty]
delete <profile>
list
current
save [profile]
switch <profile> [--refresh]
login <profile>
logout <profile>
refresh [profile]
refresh --all
limits [profile] [--all]
limits --all
inspect [profile]
doctor
version
completion <bash|zsh|fish>
codex -- <codex args...>

Global options:

• --state-dir <path> (default: ~/.codex-auth-switcher)
• --codex-home <path> (default: $CODEX_HOME or ~/.codex)
• --json (structured output for supported commands)

Storage layout

Shared Codex data (not switched)

• CODEX_HOME/sessions/...
• CODEX_HOME/session_index.jsonl
• CODEX_HOME/history.jsonl
• CODEX_HOME/state-db_<version>.sqlite

Credentials

Codex active credentials are read/written according to Codex config mode:

• file: CODEX_HOME/auth.json
• keyring: OS keyring entry (Codex Auth, account derived from hashed CODEX_HOME)
• auto: keyring first, file fallback
• ephemeral: in-memory only (cannot be persisted by a profile switcher)

codex-auth-switcher profile snapshots:

• ~/.codex-auth-switcher/profiles/<name>.json
• ~/.codex-auth-switcher/active_profile

Profile credential snapshots are encrypted at rest. The encryption key is stored in the OS keyring when available, with a 0600 file fallback if the keyring is unavailable. New profile keys are also written to ~/.codex-auth-switcher/snapshot.key as a cross-platform recovery file, so profiles remain decryptable if macOS Keychain, Linux Secret Service, or Windows Credential Manager loses or denies access to the keyring entry.

Token behavior

Tokens are not permanent.

• Access tokens expire.
• Refresh tokens may also expire or be revoked.
• Refresh failure requires re-login.

This tool provides proactive refresh and retry-on-401 for usage requests, but it cannot make tokens never expire.

Shell completion

Bash

codex-auth-switcher completion bash > ~/.codex-auth-switcher.bash
echo 'source ~/.codex-auth-switcher.bash' >> ~/.bashrc
source ~/.codex-auth-switcher.bash

Zsh

codex-auth-switcher completion zsh > ~/.codex-auth-switcher.zsh
echo 'source ~/.codex-auth-switcher.zsh' >> ~/.zshrc
source ~/.codex-auth-switcher.zsh

Fish

codex-auth-switcher completion fish > ~/.config/fish/completions/codex-auth-switcher.fish

Project layout

• VERSION: embedded CLI version for releases/builds
• main.go: CLI parsing and command dispatch
• internal/doctor.go: consistency and safety diagnostics
• internal/manager.go: profile lifecycle and Codex passthrough
• internal/auth.go: auth mode handling, refresh, limits, inspect
• internal/storage.go: atomic persistence and utilities
• internal/completion.go: shell completion generation
• internal/limits_ui.go: clean limits rendering

Development

go test ./...
go build ./...
go vet ./...

References (Codex source)

• Auth storage modes (file, keyring, auto, ephemeral):
  • https://github.com/openai/codex/blob/main/codex-rs/core/src/auth/storage.rs#L31-L332
• CODEX_HOME resolution:
  • https://github.com/openai/codex/blob/main/codex-rs/utils/home-dir/src/lib.rs#L4-L61
• Session rollouts (CODEX_HOME/sessions/...):
  • https://github.com/openai/codex/blob/main/codex-rs/core/src/rollout/list.rs#L379-L420
• Session index (CODEX_HOME/session_index.jsonl):
  • https://github.com/openai/codex/blob/main/codex-rs/core/src/rollout/session_index.rs#L16-L64
• State DB path (CODEX_HOME/state-db_<version>.sqlite):
  • https://github.com/openai/codex/blob/main/codex-rs/state/src/runtime.rs#L1012-L1020
• Token refresh logic and expiry handling:
  • https://github.com/openai/codex/blob/main/codex-rs/core/src/auth.rs#L95-L140
  • https://github.com/openai/codex/blob/main/codex-rs/core/src/auth.rs#L614-L657
• OAuth refresh request details:
  • https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/oauth.rs#L447-L522
• Usage limits endpoint and auth headers:
  • https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/client.rs#L108-L178

Disclaimer

• Unofficial tool. Not affiliated with, endorsed by, or sponsored by OpenAI.
• Use at your own risk.
• You are responsible for complying with OpenAI terms, policies, and any applicable laws.
• Credentials are sensitive. Review code, protect your machine, and understand your threat model before use.