App Routing & Non-Destructive Config Takeover

Modern AI coding agents (such as Claude Code, Codex, OpenCode, and Gemini CLI) each maintain their own configuration ecosystems, CLI flags, and dotfile formats:

• Claude Code stores preferences in ~/.claude.json;
• Codex reads settings from ~/.codex/config.toml;
• Gemini CLI relies on ~/.gemini/settings.json;
• OpenCode executes on annotated opencode.jsonc.

Manually hunting down and editing these disparate configuration files is error-prone. A single misplaced comma or mismatched field breaks JSON parsers and crashes your CLI tool.

Magpie AI's App Routing engine solves this through centralized gateway management combined with surgical, non-destructive AST mutation, enabling zero-friction model takeovers and hot swapping across all your agents.

How Application Routing Works#

When you assign a model to an assistant (e.g. running magpie claude deepseek/deepseek-v4-pro), Magpie coordinates two actions under the hood:

┌────────────────────────────────────────────────────────┐
│            Developer Executes Switch Command:          │
│            magpie claude deepseek/deepseek-v4-pro      │
└──────────────────────────┬─────────────────────────────┘
                           │
             ┌─────────────┴─────────────┐
             ▼                           ▼
┌────────────────────────┐  ┌────────────────────────────┐
│ 1. Surgical AST Update │  │ 2. Dynamic Gateway Route   │
│                        │  │                            │
│ - Locates ~/.claude.json│  │ - 127.0.0.1:3425           │
│ - Mutates ANTHROPIC_URL│  │ - Directs Claude Code      │
│ - Preserves comments   │  │   traffic to DeepSeek V4   │
│ - Atomic file writes   │  │ - Full protocol translation│
└────────────────────────┘  └────────────────────────────┘

1. Surgical AST (Abstract Syntax Tree) Mutation

Naive config switchers blindly overwrite entire configuration files from static templates, obliterating your custom developer comments, custom MCP arguments, or project-specific ignore lists.

Magpie AI features dedicated AST parsers for JSON, JSONC, YAML, and TOML:

• Targeted Tree Navigation: Navigates directly to the specific model identifier or Base URL node;
• Preserves Surrounding Context: Retains 100% of your personal comments, formatting styles, and non-model settings;
• Atomic File Writes: Writes edits to a temporary buffer and swaps files atomically, preventing file corruption during concurrent accesses.

2. Conflict-Free Local Port Multiplexing

All managed coding agents target Magpie's local gateway at http://127.0.0.1:3425. The gateway identifies incoming agent signatures from HTTP headers, dynamically translating and routing traffic to the assigned backend model. Multiple agents run concurrently on your machine without port conflicts.

Managed Dotfile Configurations#

Here is how Magpie adjusts agent configuration nodes:

Claude Code (~/.claude.json)

• Before (Stock Official Endpoint):
  json

  {
    "model": "claude-3-5-sonnet-20241022"
  }
  

• After Routing (Pointed to Local Gateway):
  json

  {
    "env": {
      "ANTHROPIC_BASE_URL": "http://127.0.0.1:3425"
    },
    "model": "deepseek/deepseek-v4-pro"
  }
  

Codex (~/.codex/config.toml)

• Before:
  toml

  # Custom team flags
  timeout = 60
  base_url = "https://api.openai.com/v1"
  

• After Routing (Developer comments completely preserved):
  toml

  # Custom team flags
  timeout = 60
  base_url = "http://127.0.0.1:3425/v1"
  model = "kimi/kimi-k2.5"
  

Gemini CLI (~/.gemini/settings.json)

• After Routing: Redirects endpoints to http://127.0.0.1:3425/gemini, adapting Google's JSON formats automatically.

Routing Commands#

1. Create or Update a Route

# Assign specific models to specific assistants
magpie claude deepseek/deepseek-v4-pro
magpie codex kimi/kimi-k2.5
magpie opencode openai/gpt-4o

# Route an assistant through a virtual failover pool
magpie claude group/opus-anywhere

2. Inspect Active Routes

magpie ls

Displays a clean summary table listing all managed agents, their bound models, route endpoints, and connection status.

3. Detach Routes & Restore Defaults (Reset)

To disconnect from the local gateway and return to vanilla factory settings:

# Restore Claude Code to official settings
magpie reset claude

# Revert all agents back to official defaults
magpie reset --all

Magpie cleanly purges injected gateway URLs and restores stock official configurations with zero leftover artifacts.

Multi-Agent Coexistence Best Practices#

Thanks to isolated per-agent routing:

1. Parallel Agent Execution: Run claude (powered by DeepSeek V4) for full-repo refactoring in Terminal 1, while executing codex (powered by GPT-4o) for frontend styling in Terminal 2—both running at full throttle simultaneously.
2. Instant Hot Swapping: Switch models via the macOS menu bar popover anytime; subsequent conversational loops pick up new configurations immediately without editor restarts.

FAQ#

Q: Will requests from multiple agents clash when pointed to 127.0.0.1:3425?

A: No. Magpie's local gateway identifies incoming agent signatures based on HTTP headers (such as specific User-Agents and header signatures), routing traffic for Claude Code, Codex, and OpenCode to their own designated backends with full isolation.

Q: Does upgrading an assistant break Magpie's routing?

A: Generally no. Updating an assistant (such as updating @anthropic-ai/claude-code) updates the executable binary without modifying user dotfiles like ~/.claude.json. As long as the Base URL remains intact, routing through Magpie continues smoothly.

Q: What if a dotfile gets corrupted by accident?

A: Run magpie reset [agent-name] (e.g. magpie reset claude). Magpie purges custom routing attributes and rebuilds a clean, valid configuration template conforming to official vendor defaults.