Skip to content

README.AI.md

Latest commit

 

History

History
133 lines (101 loc) · 3.21 KB

README.AI.md

File metadata and controls

133 lines (101 loc) · 3.21 KB
Raw

README.AI

This file is the current AI-facing fact sheet for @minniexcode/codex-switch.

Current repository version: 0.3.0

Current fact sources:

  • docs/PRD/codex-switch-prd-v0.3.0.md
  • docs/Design/codex-switch-v0.3.0-design.md
  • docs/PRD/codex-switch-prd-v0.2.1.md
  • docs/Design/codex-switch-v0.2.1-design.md
  • docs/cli-usage.md

Product Positioning

codex-switch is a local-first CLI for managing and switching Codex and Claude Code provider routing. It manages local provider records, projects Codex model_provider sections, writes the active top-level model / model_provider route, switches Claude Code settings.json profiles, and maintains backups around mutating commands.

In 0.3.0, there are two managed workflows:

  1. Codex providers — OpenAI-compatible provider records projected into config.toml / auth.json.
  2. Claude Code providers (via --claude flag) — full settings.json profiles stored and switched atomically.

Primary Workflow (Codex)

codexs init
codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>]
codexs switch <provider>
codexs status
codexs doctor

--profile means managed model_provider id alias. It is not the legacy Codex top-level profile selector.

Claude Code Workflow

codexs add --claude <name> --from-file <settings.json>
codexs switch --claude <name>
codexs current --claude
codexs list --claude
codexs show --claude <name>
codexs remove --claude <name> --force

Claude providers store the entire settings.json as an opaque blob. Switching replaces the whole file atomically with backup/rollback.

Current Command Surface

Document only these current commands:

init
migrate
list [--claude]
show [--claude]
current [--claude]
status
config show
config list-profiles
add [--claude]
edit
switch [--claude]
remove [--claude]
import
export
backups list
rollback
doctor
setup

setup is deprecated and only points callers to init or migrate.

State Model

Tool home:

~/.config/codex-switch/
  codex-switch.json
  providers.json
  claude-providers.json
  backups/

Target Codex directory:

~/.codex/
  config.toml
  auth.json

Target Claude Code directory:

~/.claude/
  settings.json

Managed projection for current Codex versions is route-first:

  • top-level model
  • top-level model_provider
  • matching [model_providers.<id>]
  • API-key auth projection in auth.json

Do not present top-level profile or [profiles.*] as the current managed runtime path. They may be inspected for adoption or legacy diagnostics only.

Current Non-Goals

0.3.0 does not include:

  • Copilot SDK integration.
  • GitHub device-flow login.
  • HTTP proxy bridge or local bridge worker runtime.
  • Background runtime services, bridge logs, or bridge runtime state.
  • Built-in third-party router packaging.
  • Account systems or cloud sync.
  • Claude Code plugin marketplace management.
  • Generic "target" abstraction or pluggable provider type system.
  • Field-based Claude provider creation (only --from-file import is supported).

Verification Commands

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