XSwap

Account switcher for Codex.

A terminal account manager for the official OpenAI Codex CLI, written in Go. Use xswap to manage isolated accounts, watch quotas, and select the account used by newly launched Codex processes.

Features

• Responsive Bubble Tea terminal panel with thin quota bars and reset timing.
• Browser or device-code login in a separate home for each account.
• Manual selection and parallel runs without copying tokens between accounts.
• Project-local account selection and confirmed conversation handoff between accounts.
• Live quota watching through the official Codex app server.
• Opt-in background auto-switch with fresh-quota checks and a cooldown.
• Offline xswap doctor diagnostics for CLI integration, profiles, settings, and monitor health.
• Enable/disable controls and account removal with local archival.
• One Go executable, with no Python or third-party Go runtime dependencies.

XSwap supports Codex on macOS, Linux, and Windows. Claude support is a future improvement. This is an independent community project, not an official OpenAI or Anthropic product. codex-swap remains a compatibility alias.

Install

Prerequisite: the official Codex CLI. Building from source also requires Go 1.26+; release binaries do not require Go.

Recommended on macOS or Linux with Homebrew:

brew install BryanPinheiro77/tap/xswap
xswap install
xswap

Homebrew manages the installed files. XSwap still detects new releases and shows Update version…; after confirmation it refreshes Homebrew and runs brew upgrade xswap. Before removing the formula, run xswap uninstall to restore the original Codex command, followed by brew uninstall xswap.

From a source checkout on macOS/Linux:

make install
xswap

Source builds report dev as their version and still detect published releases, so Update version… appears in the panel once a newer stable release exists. Installing it replaces the built executable with the official release binary.

On Windows PowerShell:

go build -trimpath -o xswap.exe ./cmd/xswap
.\xswap.exe install

The installer creates the xswap, codex-swap, and codex commands using platform-specific links or wrappers. The codex wrapper supervises each newly launched terminal session and calls your original CLI with the selected home; it does not modify the Codex package. Your existing login stays available as default. On macOS/Linux, xswap install adds its private command directory to your shell PATH; on Windows, it places the XSwap command directory first in your user PATH. Open a new terminal after installation. Opening the xswap panel before codex is not required.

GitHub Releases provide macOS, Linux, and Windows archives for arm64/amd64. On macOS/Linux, extract the matching archive into a permanent directory, run ./xswap install, and keep the executable there. On Windows, extract the .zip, run .\xswap.exe install in PowerShell, then open a new terminal. The installer adds %LOCALAPPDATA%\XSwap\bin to your user PATH.

Quick start

xswap add                     # Creates account-1, account-2, etc. and opens login
xswap add work                # Or choose your own account name
xswap add work --label Work   # Optional private-friendly display name
xswap rename work --label Personal
xswap switch work
codex

xswap project use work         # Pin new Codex processes in this repository
xswap project switch work      # Copy project conversations and resume managed sessions

xswap watch                   # Watch every account
xswap limits --all            # One-time quota query
xswap run default -- --version
xswap doctor                  # Check installation and account-manager health

No prior login or logout is needed: add logs in directly inside a new profile. The menu offers global and project switching, watching, auto-switch status, adding, enable/disable, removal, theme, and quit. Arrow keys navigate; Enter selects; Esc goes back. Interactive login, update, removal, and continuation actions temporarily receive the terminal and return to the same panel when they finish.

Switch account… changes the global default for new Codex processes and does not move conversations. Inside a project, Continue sessions with another account… immediately lists that project's conversations. From the user home, it first lists only existing projects found in Codex session metadata; XSwap does not scan every directory on the computer. Each row counts unique conversations across every registered account. After choosing a project, the session picker shows that complete deduplicated list and identifies each conversation's source account. Titles prefer the first real user request; an agent session without one shows its parent conversation's request when that parent is available in the same account, or Agent session otherwise. Every conversation is selected initially. Use Space to toggle one conversation, a to select or clear all. If a conversation changed independently in multiple accounts, the picker marks it as diverged. Deselect it to continue with the other conversations, or press Enter and explicitly choose which account's history to keep. Then choose the destination account. The final review shows the selected conversations, how many managed sessions will restart, and how many open sessions require manual resume. When resolving a divergence would replace a different destination history, XSwap first moves that history to a private archive under ~/.codex-swap/session-conflicts and reports its path. An open source conversation started outside the XSwap wrapper can still be copied after confirmation. XSwap cannot restart that process, so close the old Codex process before sending another message and run codex resume in the project to continue with the destination account. XSwap refuses the transfer if another active copy, including the destination copy, could be overwritten. Other projects and unselected conversations are left alone.

When codex resume opens Codex's own conversation picker, XSwap tracks which writer locks were active before the picker started. A single newly active conversation is attached to its supervisor immediately and can restart automatically during a later handoff, even if other conversations are opened afterward. If several conversations are already possible matches, XSwap refuses to guess which process owns one. The selected conversation can still be copied, but the panel marks it supervised · manual resume if transferred; close its old process and use codex resume with the destination account.

Project selection is stored in .xswap-account at the repository root; the nearest file wins in nested directories. XSwap adds it to the repository's local .git/info/exclude, preventing accidental commits without changing the project's .gitignore. Original conversation files remain in the source profile. Selected conversations may come from multiple source accounts and are copied into the chosen destination together. XSwap copies no authentication, config, cache, or unselected session data during a handoff. The CLI command xswap project switch NAME selects every conversation in the project for non-panel workflows.

A confirmed project handoff also makes the destination the account used by future codex processes in that project. A handoff from the user home updates the global account for future processes in unpinned directories. Switch account… changes only that global default: already running Codex sessions keep their current account and are not moved.

When run directly from the user home, the project picker also includes a Home entry when standalone conversations exist there. Choosing Home updates the global account for unpinned directories instead of creating a broad ~/.xswap-account file. Filesystem-root handoffs are refused.

Auto-switch

xswap auto on
xswap auto on --threshold 80
xswap auto view
xswap auto --once --dry-run
xswap auto off

Auto-switch starts off. At the default 90% usage threshold, it selects an eligible account with the most remaining main Codex quota. It requires five percentage points of improvement and a five-minute cooldown. Disabled accounts, stale or missing quotas, expired windows, and failed reads cannot become targets.

Automatic and global manual switching affect newly started Codex processes. Use the separate confirmed project-switch action when running managed sessions must be transferred and resumed. The monitor continues after the panel closes. After reboot, opening xswap or codex restarts it if enabled.

On macOS and Linux, xswap service install optionally registers a user service that starts the enabled monitor after login and restarts it after a failure. Use xswap service status, xswap service logs, and xswap service uninstall to inspect or remove it. Installing the service does not enable auto-switch; run xswap auto on when you want rotation. Windows keeps the existing detached monitor behavior. See the usage guide.

Account controls

xswap disable work            # Exclude from automatic rotation
xswap enable work             # Include again
xswap remove work             # Confirm removal and archive local data

Disabling keeps credentials, history, and manual selection available. Disabling the active account holds its selection during automatic checks. Removal moves the profile to a private local archive; it does not erase credentials. Switch away before removing the active account. default is protected.

Data and compatibility

State lives in ~/.codex-swap. default uses ~/.codex; named accounts use isolated profiles/NAME directories. Config is copied at creation, skills are linked, and history/caches remain separate. Later config changes and plugin installations are not synchronized. Existing local prototype profiles are preserved.

An explicitly exported CODEX_HOME overrides the codex wrapper's selection. xswap run NAME always uses that profile. Do not share manager data: it contains credentials and private account information.

Codex package updates continue updating the official CLI normally. XSwap keeps its wrapper in a separate command directory that takes precedence in new terminals, so those updates cannot displace account selection. If that shell integration is removed or changed, the panel shows Repair Codex integration…. xswap uninstall stops auto-switch and removes the wrapper without deleting profiles or the official CLI. Claude is not supported in this version.

Development

make check
make build
xswap version

Tests use temporary homes and a fake app server, not real credentials. xswap doctor works offline and returns exit code 0 when healthy, 1 when it finds warnings, and 2 when a required component fails. It does not change account selection or settings and never prints credentials, prompt history, or quota payloads.

• Usage
• Architecture
• Contributing
• Security policy
• Code of conduct
• Changelog
• Release process
• GitHub setup and branch protections

The interface and primary documentation use English. Brazilian Portuguese documentation will be added after repository publication.

Licensed under MIT.

Updates

GitHub releases provide macOS, Linux, and Windows binaries for ARM64 and AMD64.

Run xswap version to see the installed version. XSwap checks published stable releases in the background when the panel opens, with a 15-minute cache. Update version… appears only when a newer release is available. Downloads and installation require your confirmation; updates are never installed silently.

xswap update --check
xswap update

Published release binaries include their GitHub repository. Before the first release, source builds can configure it with xswap update --repo OWNER/xswap --check. No update is available until a stable release has been published. Offline checks leave the update menu hidden.

For Homebrew installations, the same menu action confirms and runs brew update followed by brew upgrade xswap, then restarts XSwap through its stable Homebrew path. Standalone installations validate SHA-256 checksums and platform compatibility before replacing the executable safely. Account profiles and settings are preserved. For standalone installations, the previous executable is saved at ~/.codex-swap/previous-xswap. Updates replace the binary, not a source checkout. Source developers can rerun the platform installation command above. Existing processes continue running their original executable; restart an enabled auto-switch monitor with xswap auto off followed by xswap auto on after updating.