Codex CLI Home Switcher

Windows PowerShell switcher for isolated Codex CLI profiles via separate CODEX_HOME directories — OpenAI, DeepSeek, and other compatible providers.

中文说明：README.zh-CN.md

Giving this repository to an AI agent? Start with AGENT_START_HERE.md. The agent must ask what you want and obtain confirmation before changing anything.

Why this exists

Codex stores configuration, authentication, sessions, logs, and skills under CODEX_HOME. Pointing different child processes at different homes keeps provider setups separate without rewriting a known-good configuration.

This is independent from interface language:

Choice	What it controls	Example
CODEX_HOME	Provider/config/auth/session boundary	openai vs deepseek
CLI command	Interface implementation/language	codex vs codex-zh

You can therefore use the switcher alone, the Chinese UI alone, or both together. For the optional Chinese UI, see codex-cli-zh-cn.

Safety properties

• Does not read, copy, merge, or migrate auth.json, config.toml, sessions, logs, or skills.
• Sets CODEX_HOME only for the selected child process.
• Shows the profile name, CLI command, CODEX_HOME, and working directory before launch.
• Refuses unknown profiles and missing home directories.
• Installer never overwrites an existing profile configuration.
• Official codex remains installed and unchanged.

Quick start for people

Requirements: Windows PowerShell 5.1 or PowerShell 7, an existing Codex CLI installation, and Git.

git clone https://github.com/LH-03/codex-cli-home-switcher.git
cd codex-cli-home-switcher
Get-Content .\scripts\install.ps1
.\scripts\install.ps1 -IncludeDeepSeek -AddToPath

Omit -IncludeDeepSeek if you only want the default OpenAI home. Existing home directories are referenced, not created or modified.

Open a new terminal, then run:

codex-home doctor
codex-openai
codex-deepseek resume --last

If codex-zh is installed, the same homes can be used with:

codex-zh-openai
codex-zh-deepseek resume --last

Configuration

The default file is %LOCALAPPDATA%\codex-cli-home-switcher\profiles.json:

{
  "profiles": {
    "openai": { "home": "%USERPROFILE%\\.codex" },
    "deepseek": { "home": "%USERPROFILE%\\.codex-deepseek" }
  }
}

Use any provider name and any absolute home. Set CODEX_HOME_SWITCHER_CONFIG to use a different JSON file.

Commands

codex-home list
codex-home show <profile>
codex-home run <profile> [--cli <command-or-path>] [--] [codex arguments...]
codex-home doctor
codex-home config-path

Manual setup

Prefer transparent PowerShell commands or functions? Read MANUAL_SETUP.md. It also explains why Codex's --profile setting is not the same thing as a separate CODEX_HOME.

Related projects

• codex-cli-zh-cn: optional Simplified Chinese Codex CLI/TUI.
• Ducksss/codex-profiles: a related profile manager oriented toward Bash/macOS/Linux workflows.
• OpenAI Codex: upstream Codex CLI.

Security

Never commit a real Codex home, API key, token, auth.json, or provider configuration. See SECURITY.md.

MIT licensed. This is an unofficial community project and is not affiliated with or endorsed by OpenAI or DeepSeek.