Magpie AI Feature Overview & Architecture

Magpie AI (developed by yetone) is an open-source model router and unified control center crafted specifically for modern AI coding agents. Its guiding principle is simple and powerful: "Every agent's model. One place."—empowering developers to easily assign any leading language model to Claude Code, Codex, OpenCode, Gemini CLI, Cursor, or Copilot from a single, centralized workstation.

Unlike fragile config switchers that overwrite your custom dotfiles or bulky Electron apps, Magpie AI is engineered in Go (with a tiny ~25MB binary footprint) and offers a cohesive four-in-one interface suite: macOS Menu Bar app, interactive Terminal TUI, full-featured CLI commands, and a high-performance local API gateway (127.0.0.1:3425).

This overview breaks down Magpie AI's user interfaces, core functional modules, and underlying architectural mechanics.

Four Cohesive Interface Modes#

Whether you prefer swift menu bar clicks, terminal keyboard navigation, or automated script orchestration, Magpie AI adapts seamlessly:

1. macOS Menu Bar & System Tray

On macOS, Magpie AI lives as a neat status icon in your menu bar (and in the system tray on Windows and Linux):

• One-Click Hot Switching: Open a compact popover displaying all detected AI agents alongside their currently active models. Click a dropdown to swap an agent's backend provider or model in under a second.
• Gateway Status Indicator: At-a-glance health and port status for the local translation gateway (127.0.0.1:3425).
• Live Quota Summary: Quickly glance at your daily token consumption and remaining account quotas without launching a full browser window.

2. Terminal Interactive Dashboard (TUI)

For engineers who live in tmux, Alacritty, or remote SSH sessions, Magpie AI delivers an ultra-responsive terminal user interface:

# Launch the terminal dashboard
magpie tui

• Split-Pane Layout: The left column lists all detected coding agents and configured providers; the right pane shows active routing groups, live model parameters, and real-time token metrics.
• Keyboard-First Navigation: Move effortlessly with j/k or arrow keys, cycle panels with Tab, confirm model bindings with Enter or Space, and exit anytime with q.
• Real-Time Request Stream: Inspect live outbound API calls, translation latencies, and HTTP response codes as your agents write code.

3. Full-Featured Command Line (CLI)

Magpie AI adheres to UNIX design principles—simple, composable, and scriptable:

# List all detected agents and their active backend models
magpie ls

# Bind a model to an agent in one line
magpie claude deepseek/deepseek-v4-pro
magpie codex moonshot/kimi-k2.5

# Add an upstream provider's API key
magpie provider add deepseek sk-xxxxxxxxxxxxxxxxxxxx

# Connect an existing browser subscription (ChatGPT Plus / Claude Pro)
magpie accounts add claude

# Check remaining quotas across all providers and accounts
magpie quota

# Reset an agent back to its stock factory configuration
magpie reset claude

4. Native Desktop Window (Wails & Webview)

When you need an expanded view, Magpie AI opens a clean native window powered by Go and system Webviews (avoiding hundreds of megabytes of Electron memory bloat, idling at just 25MB~40MB RAM):

• Agents Dashboard: View cards for all detected developer assistants, file paths, and live connection states.
• Providers Inventory: Centralize official keys, third-party proxies, and session tokens in one secure vault.
• Routing Groups: Visually assemble multi-account fallback pools and rate-limit mitigation strategies.
• Audit Logs: Deep dive into raw payload translations, token breakdown distributions, and error traces.

Core Architecture & Key Capabilities#

┌────────────────────────────────────────────────────────┐
│             AI Coding Agents (Clients)                 │
│      Claude Code    │     Codex     │    OpenCode      │
└─────────────────────┴───────────────┴──────────────────┘
                           │
    (Surgical AST writes)  │  (API request traffic)
                           ▼
┌────────────────────────────────────────────────────────┐
│        Magpie AI Local Gateway (127.0.0.1:3425)        │
│  ├─ Protocol Translation (Anthropic Messages ↔ OpenAI) │
│  ├─ Routing Groups (group/[id] with silent 429 retry)  │
│  ├─ Local Privacy Masking (In-flight regex redaction)  │
│  └─ Quota Tracker & Real-Time Token Auditing           │
└──────────────────────────┬─────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│                 Upstream Model Providers               │
│    Anthropic   │    DeepSeek   │   Kimi   │   OpenAI   │
└────────────────┴───────────────┴──────────┴────────────┘

1. In-Flight Protocol Translation Gateway

Different AI agents demand different API protocols (for example, Claude Code strictly communicates via Anthropic Messages API, whereas most alternative cost-effective providers serve OpenAI chat/completions endpoints).

Magpie AI's built-in Go gateway (127.0.0.1:3425) bridges this divide transparently:

• Bidirectional Schema Translation: Converts Anthropic Messages payloads into OpenAI or Gemini formats and back on the fly.
• Streaming Event Re-chunking (SSE): Perfectly reconstructs Server-Sent Events, preserving reasoning/thinking blocks (such as DeepSeek R1 and Kimi K2.5) directly into the agent's expected thinking protocol.
• Tool Calling Pass-Through: Flawlessly maps Anthropic Tool Use schemas to OpenAI Function Calling formats, ensuring file read/write, bash execution, and MCP commands never break.

2. Surgical AST Configuration Engine

Standard tools often overwrite entire configuration files with generic templates, accidentally destroying your custom comments, custom flags, or specific indentation rules in ~/.claude.json or ~/.codex/config.toml.

Magpie AI features an internal AST (Abstract Syntax Tree) engine:

• Parses JSON, JSONC, YAML, and TOML data structures cleanly;
• Surgically mutates only the targeted model and Base URL nodes;
• Retains 100% of your developer comments, formatting styles, and custom parameters;
• Employs atomic writes to eliminate corruption during concurrent operations.

3. Virtual Routing Groups & Automated Failover

With magpie group, you can group multiple keys or alternative models under a single virtual endpoint (group/opus-anywhere). When an upstream provider hits an HTTP 429 rate limit or connection timeout, Magpie AI switches to the next account or fallback model within milliseconds—allowing background agent loops to run uninterrupted.

Recommended Learning Path#

To get the most out of Magpie AI, follow these foundational guides:

1. Installation Guide: Deploy Magpie AI using the official curl script or Homebrew;
2. Configure Your First Provider: Add API keys via CLI or the menu bar interface;
3. Provider & Model Switching: Experience running Claude Code on DeepSeek V3/R1 with maximum efficiency;
4. Routing Groups & Failover: Build automated resilience against rate limits and service outages;
5. Prompt Privacy Sanitization: Activate in-flight secret redaction before data leaves your machine.

FAQ#

Q: Are changes synchronized across the Menu Bar, TUI, and CLI?

A: Yes, fully in real time. All interfaces interact with the same underlying Go runtime and local state. A model switched inside the terminal TUI instantly updates the menu bar dropdown, and routes altered via CLI reflect immediately in the graphical console.

Q: How much system memory does the local gateway consume?

A: It is extremely lightweight. Written in Go rather than resource-heavy Electron, the daemon typically idles at just 25MB~40MB of RAM with near-zero CPU usage, causing virtually no performance impact on your workstation.

Q: Will Magpie overwrite my custom comments or dotfile formatting?

A: Never. Magpie's internal AST (Abstract Syntax Tree) engine mutates only the targeted Base URL and model properties. Any developer comments, custom environment flags, or personal formatting inside your files remain 100% intact.