@minniexcode/codex-switch

@minniexcode/codex-switch is a local-first CLI for managing and switching Codex provider and model-provider routing safely.

It keeps codex-switch tool state separate from the target Codex runtime, so provider management, backup flow, and runtime projection stay explicit instead of relying on manual file edits.

Chinese version: README.CN.md

Version

Current package version: 0.1.3

This is the current stable documentation line. 0.1.3 is the Copilot login hotfix release, repairing the managed SDK client construction against the current official Copilot SDK runtime while keeping the stream_idle_timeout_ms = 300000 Copilot projection unchanged.

Install

npm install -g @minniexcode/codex-switch

Run without a global install:

npx @minniexcode/codex-switch --help

Built CLI entrypoint:

codexs --help

Primary Workflows

Direct provider workflow:

codexs init
codexs add my-provider --model gpt-5.5 --base-url https://gateway.example.com/v1 --api-key sk-xxx
codexs switch my-provider
codexs status
codexs doctor

GitHub Copilot workflow:

codexs init
codexs login copilot
codexs add copilot-main --copilot --model gpt-4.1
codexs switch copilot-main
codexs status
codexs doctor

Notes:

• init prepares the codex-switch tool home and managed state.
• login copilot handles upstream Copilot onboarding and auth readiness.
• add --copilot does not perform login for you; it assumes Copilot login is already ready.
• Copilot support is an experimental local bridge. The managed installer defaults to @github/copilot-sdk@1.0.2, Copilot runtime paths require Node.js >=20, and runtime checks separately reject older or prerelease SDK installs while validating API shape when the client or session is used.
• switch projects the selected provider into the target Codex runtime as top-level model plus model_provider.
• status is the main read command after switching.
• doctor is the main repair-oriented diagnostic command.

Runtime Routing Model

For Codex 0.134.0+, the active runtime route is selected through top-level model and model_provider in config.toml.

codex-switch treats that route as the runtime contract:

• top-level model selects the active model id
• top-level model_provider selects the active provider route
• managed [model_providers.<id>] entries are the projected runtime provider definitions
• --profile is only an alias for the managed model_provider id, not the primary runtime selector

Direct-provider projection writes:

• top-level model
• top-level model_provider
• [model_providers.<id>]
• auth.json with OPENAI_API_KEY

Managed direct-provider projection does not keep env_key or env_key_instructions in the generated runtime config. switch, add, and edit clean old legacy projection fields before writing the active route.

For managed OpenAI-compatible routes, the projected provider entry keeps the fixed runtime shape:

model = "gpt-5.5"
model_provider = "my-provider"

[model_providers.my-provider]
name = "my-provider"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

Managed Copilot projection additionally writes:

stream_idle_timeout_ms = 300000

Advanced Adopt Workflow

Use migrate only when you already have Codex runtime state that should be adopted into managed providers.json state:

codexs init
codexs migrate

migrate is an advanced adopt helper. It is not the default first step for a fresh install.

Command Surface

codexs init
codexs login copilot
codexs migrate
codexs list
codexs show <provider>
codexs current
codexs status
codexs config show [profile]
codexs config list-profiles
codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
codexs add <provider> --copilot --model <model>
codexs edit <provider>
codexs switch <provider>
codexs remove <provider> [--force] [--switch-to <provider>]
codexs import <file>
codexs export <file> [--force]
codexs bridge start [provider]
codexs bridge status [provider]
codexs bridge stop [provider]
codexs backups list
codexs rollback [backup-id]
codexs doctor

setup still exists only as a deprecated compatibility entry that points callers to init or migrate.

Runtime Model

Tool home:

~/.config/codex-switch/
  codex-switch.json
  providers.json
  backups/
  runtime/
  runtimes/

Target Codex runtime:

~/.codex/
  config.toml
  auth.json

Key points:

• providers.json is the managed provider registry and lives under the tool home.
• codex-switch.json stores tool-level metadata such as defaultCodexDir.
• config.toml remains the active runtime routing file in the target Codex directory.
• auth.json remains the active auth projection file in the target Codex directory.
• Direct providers rewrite OPENAI_API_KEY into the active runtime projection.
• Copilot providers keep upstream GitHub authentication in the official Copilot runtime while codex-switch manages local bridge state and routing.

Path controls:

• --codex-dir <path> targets a specific Codex runtime directory.
• CODEXS_CODEX_DIR provides the default target runtime when --codex-dir is not passed.
• CODEXS_HOME overrides the tool home location.

Automation Notes

This CLI supports both human TTY usage and non-interactive automation.

Global flags:

--json
--codex-dir <path>
--help
--version

Operational limits:

• login copilot requires a real TTY and does not support --json.
• migrate remains interactive when provider adoption requires human input.
• Automation should pass explicit arguments and prefer --json for stable parsing.

Local Development

npm run build
npm test
npx tsc --noEmit
node dist/cli.js --help
npm pack --dry-run

Documentation

• Chinese README
• AI README
• Detailed CLI Usage
• Testing Guide
• Product Overview
• PRD 0.1.0
• PRD 0.1.1
• PRD 0.1.2
• PRD 0.1.3
• Design 0.1.2
• Design 0.1.3

License

MIT