coding-agent-switch

简体中文

CLI-first switcher for coding agents, designed primarily for Linux/Unix environments.

Overview

coding-agent-switch focuses on two workflows:

1. Switch Codex between different OpenAI-compatible providers.
2. Optionally switch Claude Code between:
   • native: regular Claude
   • profile: a LiteLLM gateway backed by a Codex/OpenAI-compatible provider

The repository only contains templates and switching logic. It does not include secrets.

Why This Exists

Official Codex and Claude are great, but they can be expensive for daily usage. Many users also have access to third-party compatible providers and want one simple CLI to switch between them.

This tool keeps the core workflow simple:

• Codex profile switching is the primary feature.
• Claude gateway switching is optional and installed only when needed.
• Private provider profiles stay local and out of git.

Feature Overview

• Primary entrypoint: agent-switch
• Compatibility entrypoints: codex-switch, claude-switch
• Interactive menu: run agent-switch in a TTY
• Profile creation helper: add-profile
• Default install mode: Codex-only
• Optional gateway component: gateway/claude-gateway-switch
• Config templates: profiles/*/config.toml + auth.json.template
• Local private profiles: profiles-local/*

Repository Layout

coding-agent-switch/
├── bin/
│ ├── agent-switch
│ ├── add-profile
│ ├── claude-switch
│ └── codex-switch
├── install.sh
├── install-claude-gateway.sh
├── gateway/
│ ├── claude-gateway-switch
│ ├── lib/render_runtime.py
│ └── runtime/
├── lib/provider_balance.py
├── profiles/
│ └── provider/
├── profiles-local/
├── .env.example
└── .gitignore

Requirements

Default: Codex-only

• codex
• python3 3.10+

Optional: Claude gateway

• claude
• ./install-claude-gateway.sh to install LiteLLM dependencies

Installation

Run this in the repository root:

./install.sh

This will:

• create .env from .env.example if needed
• skip LiteLLM by default
• link agent-switch, codex-switch, and add-profile into ~/.local/bin

If you also want the Claude gateway:

./install-claude-gateway.sh

This installs LiteLLM dependencies and links claude-switch.

PATH Setup

Add ~/.local/bin to your shell PATH so you can run the commands directly.

For zsh:

echo'export PATH="$HOME/.local/bin:$PATH"'>>~/.zshrc
source~/.zshrc

For bash:

echo'export PATH="$HOME/.local/bin:$PATH"'>>~/.bashrc
source~/.bashrc

For fish:

set-U fish_user_paths $HOME/.local/bin $fish_user_paths

Verify:

command -v agent-switch
command -v codex-switch
command -v add-profile

If you enabled the Claude gateway:

command -v claude-switch

Quick Start

1. Install the tool:

cd coding-agent-switch
./install.sh

2. Put provider keys into per-profile auth.json files. Use .env only as a fallback.
3. Check available profiles:

agent-switch list

4. If needed, install the Claude gateway:

./install-claude-gateway.sh

Common Commands

0) Interactive Menu

agent-switch

Available in the menu:

• number keys
• ↑/↓
• Enter
• q

1) Create a Profile

Direct arguments:

add-profile --name pro \
--base-url https://api.example.com/v1 \
--api-key sk-xxxx \
--wire-api responses \
--requires-openai-auth true

Or provide a TOML snippet:

cat <<'EOF' | add-profile --api-key sk-xxxx --provider-snippet-file -[model_providers.pro]name = "pro"base_url = "https://api.example.com/v1"wire_api = "responses"requires_openai_auth = trueEOF

Interactive mode:

add-profile

Compatibility aliases:

agent-switch profile add --name pro --base-url https://api.example.com/v1 --api-key sk-xxxx
agent-switch profile create pro --base-url https://api.example.com/v1 --api-key sk-xxxx

2) Create Multiple Local Profiles

Examples:

agent-switch profile create provider-a \
--base-url https://api-a.example.com/v1 \
--env-key PROVIDER_A_API_KEY \
--api-key your_provider_a_key

agent-switch profile create provider-b \
--base-url https://api-b.example.com/v1 \
--env-key PROVIDER_B_API_KEY \
--api-key your_provider_b_key
agent-switch profile create provider-c \
--base-url https://api-c.example.com/v1 \
--env-key PROVIDER_C_API_KEY \
--api-key your_provider_c_key
agent-switch profile list

Recommended local auth file:

{
"OPENAI_API_KEY": "your_api_key_here"
}

.env values such as PROVIDER_A_API_KEY still work as a fallback, but they are not the preferred path.

3) Codex Provider Switching

Persistent switching is the main workflow.

agent-switch codex provider-a
agent-switch codex provider-b
agent-switch codex provider-c

Explicit equivalent:

agent-switch codex provider-a use
agent-switch codex provider-b use

Show resolved profile data:

agent-switch codex provider-a show
agent-switch codex provider-b env

One-off debugging run without changing ~/.codex:

agent-switch codex provider-a run -p "Reply with exactly OK."

Backup and restore native Codex auth/config:

agent-switch codex native export-auth official-main
agent-switch codex native restore-auth official-main

Logout and clean provider residue from current Codex config:

agent-switch codex logout

4) Claude Backend Switching

Make sure you have already run:

./install-claude-gateway.sh

Native Claude:

agent-switch claude native

Profile-backed Claude via LiteLLM:

agent-switch claude provider-a
agent-switch claude provider-b

Single prompt:

agent-switch claude provider-b -p "Reply with exactly OK."

5) Gateway Operations

agent-switch claude provider-b serve
agent-switch claude provider-b status
agent-switch claude provider-b logs
agent-switch claude provider-b stop

Configuration Model

Preferred secret handling:

• profiles/*/config.toml: base URL, model, env key
• profiles-local/*/config.toml: local private provider profiles
• profiles-local/*/auth.json: real API keys
• .env: compatibility fallback only

Example auth.json:

{
"OPENAI_API_KEY": "your_api_key_here"
}

Runtime lookup priority:

1. profiles-local/<name>/auth.json
2. provider-specific env key from config.toml
3. generic OPENAI_API_KEY

Native Codex auth snapshots are stored under:

profiles-local/<name>/codex-native/

Available commands:

• agent-switch codex native export-auth <name>
• agent-switch codex native restore-auth <name>

Existing files are backed up with .bak.YYYYMMDD-HHMMSS.

Prompt for AI Coding Assistants

Deploy coding-agent-switch on this machine:
1) Copy .env.example to .env and chmod 600
2) Create a profile with add-profile --name <name> --base-url ... --api-key ... (or agent-switch profile add ...)
3) Run ./install.sh for Codex-only mode
4) Run agent-switch list to verify profiles
5) Run agent-switch codex provider-a show or agent-switch codex provider-b show to verify profile resolution
6) Run agent-switch codex provider-a for persistent switching; use agent-switch codex provider-a run ... for one-off debugging
7) Only if Claude gateway is needed: run ./install-claude-gateway.sh, then use agent-switch claude provider-a prepare or agent-switch claude provider-b prepare
8) Do not commit .env, profiles-local/, profiles/*/auth.json, or gateway/runtime/

Security Notes

• Commit templates, not real keys or tokens.
• Keep auth.json, .env, and runtime logs local.
• Keep profiles-local/ out of git.
• Keep the gateway bound to loopback only.
• Validate with show or status before switching real traffic.

Positioning

This is a CLI-first tool. It is intended as a scriptable alternative or complement to GUI-oriented switchers such as cc switch, not as a GUI replacement.

Suggested Providers

If you are looking for compatible providers, here are some examples:

• FoxCode: https://foxcode.rjj.cc/auth/register?aff=4YNPP
• Codex For Me: https://codex-for.me/?invite=9608

Disclosure

If someone registers through the links above and later spends on those platforms, the project maintainer may receive referral rewards from the platform.