Juggling multiple Codex accounts? codex-mp lets you save, name, and hot-swap file-backed login sessions from the command line — like browser profiles, but for your terminal.
Heads up: Codex supports multiple credential storage modes:
file,keyring,auto, andephemeral.codex-mpmanages file-backedauth.jsonsessions only. Setcli_auth_credentials_store = "file"in~/.codex/config.toml, then sign in again before saving profiles. Keyring-backed profile storage is intentionally out of scope for this release.
Install:
brew install BigCactusLabs/tap/codex-mpOr build from source with Go 1.25+: make build
Use it:
codex-mp init # one-time setup
codex-mp save work # snapshot current session as "work"
codex-mp save personal # log into another account, save it too
codex-mp use work # swap back instantly
codex-mp doctor # verify Codex is using file-backed auth
codex-mp ui # or pick from an interactive listThat's it. No repos touched, no tools reconfigured — just swaps files under your Codex state directory.
| Command | What it does |
|---|---|
codex-mp init |
Set up the profiles directory |
codex-mp save <name> |
Snapshot current session as a named profile |
codex-mp use <name> |
Switch to a saved profile |
codex-mp ui / pick |
Interactive profile selector (TUI) |
codex-mp list |
Show all saved profiles |
codex-mp who |
Print SHA-256 fingerprint of current auth |
codex-mp rename <old> <new> |
Rename a profile |
codex-mp delete <name> |
Delete a profile |
codex-mp path |
Show resolved Codex state paths |
codex-mp doctor |
Check Codex auth/profile compatibility |
codex-mp completion <shell> |
Generate shell completions (bash/zsh/fish/powershell) |
codex-mp --json <cmd> |
JSON output for scripting |
Your tokens never leave your machine and never get printed to the terminal.
- Local only — all data stays on disk, nothing phones home
- Atomic writes — temp file + rename, so a crash can't corrupt your auth
- Process locking — no concurrent-write races
- Strict permissions — directories
700, auth files600, fails closed if hardening fails - Fingerprints, not secrets —
codex-mp whoshows a SHA-256 hash, never the token itself
By default Codex state lives at ~/.codex. Override with CODEX_HOME:
CODEX_HOME=/custom/path/.codex codex-mp path~/.codex/
auth.json # active session
config.toml # set cli_auth_credentials_store = "file"
profiles/
work.json # saved profiles
personal.json
codex-mp tracks which profile is active and syncs the latest auth.json back before switching. This means rotated refresh tokens are preserved automatically — no stale-token surprises.
If Codex is configured with keyring, auto, or ephemeral, profile commands fail with remediation instead of guessing where credentials live. auto is rejected because Codex may use the OS keyring when available and fall back to auth.json only on failure; that ambiguity is not safe for a profile switcher.
brew install BigCactusLabs/tap/codex-mpHomebrew publishing is maintained locally, not through GitHub Actions.
For a release, bump VERSION, commit the release changes, then run ./scripts/publish_homebrew_release.sh.
The script tags the release if needed, uploads a stable tarball asset, updates BigCactusLabs/tap, and validates the formula with brew.
git clone https://github.com/BigCactusLabs/codex-multipass.git
cd codex-multipass
make build # requires Go 1.25+
# binary lands at ./codex-mpLegacy users: If you have automation calling
codex-switch, point it atbash/codex-switch— it delegates to the Go binary.
make build # build the binary
make test # integration tests against local binary
make unit-test # Go unit tests
shellcheck bash/codex-switch scripts/*.sh tests/*.shCI runs Go unit tests, smoke, battle, concurrency, and corrupt-storage tests plus shell and Go linting on every push.
Made by Big Cactus Labs 🌵