CodexSwitch

README

CodexSwitch

Language: English | 简体中文

A local-only Codex auth switcher that keeps sessions shared.

CodexSwitch is a small native CLI for people who use multiple Codex accounts on one computer. It saves each login as a local profile, updates Codex's current login file, and keeps your Codex projects, sessions, history, plugins, skills, MCP settings, rules, and main configuration shared.

It is designed for one job: switch Codex login safely without creating separate local workspaces.

CodexSwitch is an independent project and is not affiliated with OpenAI.

Highlights

• Local-only by design: account files never leave your computer.
• Shared sessions by design: switching accounts does not isolate or duplicate Codex sessions.
• Safe login-file replacement: switches use backup, private permissions, verification, and atomic file replacement.
• Quota without waking idle accounts: quota summaries are read from local Codex session records, not fresh server polling.
• Readable daily view: the default command shows the current account, switchable accounts, subscription, 5h quota, weekly quota, and reset times.
• Scriptable output: core commands support stable --json output with token values redacted.

Install

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/ScWen7/CodexSwitch/main/install.sh | bash

Install a specific version or directory:

VERSION=v0.1.0 INSTALL_DIR=/usr/local/bin \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/ScWen7/CodexSwitch/main/install.sh)"

The installer downloads prebuilt release assets for macOS and Windows. If a matching asset is unavailable and Go is installed, it falls back to go install.

Windows users should run the installer from Git Bash or another bash-compatible shell.

Install from source:

go install github.com/ScWen7/CodexSwitch/cmd/codex-switch@latest

Quick Start

Prepare local directories:

codex-switch setup

Save the Codex account you are currently logged in with:

codex-switch profile init pro

Add another account:

codex-switch profile add plus

Switch accounts:

codex-switch switch plus

Open the daily view:

codex-switch

Example:

Current account
  pro
  │ Plan       pro
  │ 5h         83%        resets 6/21 21:19
  │ Week       74%        resets 6/25 09:18
  │ Recorded   6/21 17:48

Switchable
  plus
  │ Plan       plus
  │ 5h         26%        resets 6/21 14:30
  │ Week       60%        resets 6/26 18:12
  │ Recorded   6/21 17:50
  │ Switch     codex-switch switch plus

Notice
  Codex is running; switching will quit it first.

Safety Model

CodexSwitch treats every auth.json as a secret.

• Saved account files live under ~/.codex-switch/profiles/<name>/auth.json.
• The Codex login file remains ~/.codex/auth.json.
• Files containing account data, profile details, app state, backups, and logs are written with owner-only permissions.
• Switching creates a backup before replacing the Codex login file.
• Replacement uses a temporary file and rename so Codex does not see a partially written login file.
• After switching, CodexSwitch verifies that the selected account is in use.
• Token values are redacted from normal output, JSON output, errors, and logs.

CodexSwitch does not upload account files, sync profiles to a server, provide a team account pool, install a background service, or control Codex remotely.

Shared Sessions

CodexSwitch only switches the Codex login. It does not isolate, copy, or move:

• projects
• sessions
• history
• plugins
• skills
• MCP settings
• rules
• ~/.codex/config.toml

This is intentional. Use CodexSwitch when you want multiple local login profiles while keeping one continuous Codex workspace.

Quota And Reset Times

CodexSwitch is focused on the quota window model: subscription, 5h remaining quota, weekly remaining quota, and reset times.

The quota view is conservative:

• It reads local Codex session JSONL records that Codex already wrote during normal use.
• It does not request a fresh quota reading from Codex just to update the display.
• It attaches local quota records to saved profiles using CodexSwitch switch history.
• If a local session cannot be safely attributed to a profile, it is not used for that profile summary.

Local source:

~/.codex/sessions/**/*.jsonl
token_count.rate_limits

Why this matters: actively asking Codex for a fresh usage reading can start or extend the 5h window for an idle account. CodexSwitch treats that as a product red line, so normal user commands show the last locally recorded quota instead.

For the newest official reading, open Codex Settings > Usage or use /status inside the Codex session that is already active.

Commands

Daily commands:

codex-switch
codex-switch profiles
codex-switch quota
codex-switch switch <profile>
codex-switch status

Profile management:

codex-switch profile init <name>
codex-switch profile add <name>
codex-switch profile list
codex-switch profile inspect <name>
codex-switch profile rename <old> <new>
codex-switch profile remove <name>
codex-switch profile current

Safety and recovery:

codex-switch switchcheck <profile>
codex-switch doctor
codex-switch doctor --fix-permissions
codex-switch history
codex-switch backup list
codex-switch backup restore <id>

Machine-readable output:

codex-switch status --json
codex-switch switchcheck <profile> --json
codex-switch profile list --json
codex-switch profile inspect <profile> --json
codex-switch doctor --json

JSON output never includes raw token values or raw auth.json content.

Data Directory

New installs use:

~/.codex-switch/
  state.json
  profiles/<name>/auth.json
  profiles/<name>/metadata.json
  backups/auth.<timestamp>.json
  logs/switches.jsonl
  quota/observations.jsonl
  quota/state.json

Codex continues to use:

~/.codex/auth.json

Legacy compatibility: if ~/.codex-switch does not exist but ~/.codex-relay already exists, CodexSwitch continues to use ~/.codex-relay.

Release Assets

Prebuilt release assets are generated for macOS and Windows:

codex-switch_darwin_amd64.tar.gz
codex-switch_darwin_arm64.tar.gz
codex-switch_windows_amd64.zip
codex-switch_windows_arm64.zip

Build them locally:

VERSION=v0.1.0 ./scripts/build-release.sh

Do not commit dist/release/*. Upload those files as GitHub Release assets:

gh release create v0.1.0 dist/release/* \
  --repo ScWen7/CodexSwitch \
  --title v0.1.0 \
  --notes "Initial release"

Each archive includes codex-switch, README.md, README.zh-CN.md, and LICENSE.

Development

Run the standard checks:

go test ./...
go vet ./...
git diff --check

Build the local binary:

go build -o ./dist/codex-switch ./cmd/codex-switch

Run an isolated-home smoke test:

tmp_home="$(mktemp -d)"
HOME="$tmp_home" ./dist/codex-switch --version
HOME="$tmp_home" ./dist/codex-switch setup
HOME="$tmp_home" ./dist/codex-switch doctor --json
HOME="$tmp_home" ./dist/codex-switch status --json

Uninstall

Remove the binary:

rm -f "$HOME/.local/bin/codex-switch"

Remove CodexSwitch profile data:

rm -rf ~/.codex-switch

Only remove ~/.codex-relay after confirming you no longer need legacy profile data.