Provider & Model Switching

After registering multiple model providers and accounts in Magpie AI, switching between them according to your development context becomes second nature:

• Tackling complex system architecture or intricate algorithms: engage Claude 3.5 Sonnet or DeepSeek R1;
• Writing boilerplate scripts, generating unit tests, or drafting documentation: swap to economical DeepSeek V3 or Kimi K2.5;
• Experiencing upstream latency spikes or rate limits: instantly pivot to a hot-standby route.

Magpie AI makes model swapping instant—without having to manually edit nested .json or .toml dotfiles, and without needing to restart your editor or terminal.

This guide explains how to switch models via the CLI, the menu bar, or the terminal TUI, and breaks down the non-destructive mechanics behind the scenes.

Method 1: Instant CLI Shorthand (Fastest)#

For terminal-first engineers, Magpie AI provides concise command shortcuts. Simply type magpie <agent> <provider/model>:

# Switch Claude Code to DeepSeek V4 Pro
magpie claude deepseek/deepseek-v4-pro

# Switch Codex to Kimi K2.5
magpie codex kimi/kimi-k2.5

# Switch OpenCode to OpenAI GPT-4o
magpie opencode openai/gpt-4o

# Route Claude Code through an automated failover group
magpie claude group/opus-anywhere

Magpie updates the configuration via AST mutation in milliseconds and confirms the change:

✓ Switched Claude Code to deepseek/deepseek-v4-pro (via 127.0.0.1:3425)

Launch claude in your terminal, and all prompts will immediately route through Magpie's local translation gateway to DeepSeek.

Method 2: macOS Menu Bar & System Tray#

When working inside an IDE like VS Code or Cursor:

1. Click the Magpie status icon in your macOS menu bar (or system tray on Windows/Linux);
2. The dropdown popover displays all detected agents (Claude Code, Codex, Gemini CLI, etc.);
3. Locate the target agent and open its model selector dropdown;
4. Click the desired provider or model.

The menu bar immediately updates the checkmark (✓). You can switch active backends without moving away from your active code file.

Method 3: Terminal TUI Keyboard Navigation#

For full-screen terminal multiplexers or remote SSH development:

1. Type magpie tui in your terminal;
2. Use Tab to focus on the left-hand Agents pane, moving with arrow keys or j/k;
3. Press Enter to reveal available models and upstream providers;
4. Highlight your chosen model and press Space or Enter to confirm the binding;
5. Press q to exit the TUI with changes immediately applied.

Verifying Active Bindings#

Regardless of the method used, run magpie ls to audit all active agent routes:

magpie ls

Sample output:

AGENT          STATUS     PROVIDER / MODEL              ROUTE
Claude Code    ACTIVE     deepseek/deepseek-v4-pro      http://127.0.0.1:3425
Codex          ACTIVE     kimi/kimi-k2.5                http://127.0.0.1:3425
Gemini CLI     ACTIVE     zhipu/glm-4-plus              http://127.0.0.1:3425
OpenCode       STOCK      anthropic/claude-3-5-sonnet   direct (official)

This table gives you immediate visibility into which tools are routed through the local gateway and which remain connected directly to official APIs.

Under the Hood: Non-Destructive AST Mutation#

How does Magpie AI execute model swaps reliably?

• AST-Level Targeted Edits: When switching models, Magpie's internal Go parser reads the agent configuration (such as ~/.claude.json or ~/.codex/config.toml) and surgically alters only the relevant ANTHROPIC_BASE_URL or model nodes.
• Preserving Comments & Custom Keys: Any personal comments, custom env flags, or formatting rules inside your dotfiles remain 100% intact.
• Instant Hot Application: Most modern CLI agents read endpoints at the beginning of each conversational loop, meaning switches take effect immediately without requiring editor restarts.

Factory Reset#

If you want to disconnect Magpie and restore an agent to its out-of-the-box factory configuration, run:

# Revert Claude Code back to official defaults
magpie reset claude

# Revert all managed agents back to default
magpie reset --all

Magpie cleanly removes local gateway bindings and restores official upstream endpoints with zero lingering artifacts.

FAQ & Tips#

Q: Why is my terminal still using the old model after switching?

A: If a CLI agent caches environment variables inside an open interactive session, exit that specific session (type /exit or restart that shell tab). New sessions will immediately load the updated gateway configuration.

Q: Can I use different models for different project workspaces?

A: Yes! Use Magpie's profile system (e.g., magpie use work vs magpie use personal). Learn more in the Profiles & Customization Guide.

Q: Will switching models wipe my active multi-turn conversation context?

A: No. Conversation history and session memory are managed locally by the agent itself (e.g., inside .claude/ session files). Magpie manages only the upstream endpoint routing. Subsequent turns seamlessly preserve your existing repository context.