Home
Tutorials
Install Now
GitHub
简体中文
Getting Started

Getting Started with Magpie AI

Understand what Magpie AI manages before you move into installation and routing.

What is Magpie AI

Magpie AI (created by yetone and open-sourced on GitHub) is a unified model router and local gateway designed for modern AI coding agents. Its vision is focused and clean: "Every agent's model. One place."—freeing developers from hunting through nested dotfiles to assign any language model to any coding assistant.

Whether you rely on:

  • Claude Code (Anthropic's official agentic CLI)
  • Codex (OpenAI coding assistant)
  • Gemini CLI (Google's developer tool)
  • OpenCode / OpenClaw / Cursor / Copilot, and more

Magpie AI offers a cohesive control plane spanning a macOS Menu Bar app, Terminal TUI, full CLI suite, and a high-throughput local gateway (127.0.0.1:3425).

What Problems Does It Solve

Software engineers using CLI assistants encounter familiar friction points:

1. Configuration Scattered Across Disparate Files

Every assistant uses its own paths (~/.claude.json, ~/.codex/config.toml, ~/.gemini/settings.json, etc.). Manually editing dotfiles is tedious and risks destroying personal comments or breaking JSON parsers.

2. Blocked from Using Cost-Effective Models

Claude Code natively speaks only Anthropic's protocol, preventing direct connection to budget-friendly models like DeepSeek or Moonshot/Kimi. Basic proxies fail because they mangle Tool Use and Thinking blocks.

3. Rate Limits (HTTP 429) Aborting Long Agent Loops

During multi-hour codebase refactors or automated testing, hitting an upstream rate limit crashes active agent sessions, losing live conversational context.

4. Excessive Commercial API Invoicing

Developers often maintain active ChatGPT Plus or Claude Pro subscriptions, yet are forced to spend extra budget on separate commercial API tokens for CLI tools.

3-Minute Quickstart

Follow these four steps to achieve your first working setup:

Step 1: Install Magpie AI

Run the official one-liner script in your terminal (macOS & Linux):

bash
curl -fsSL https://usemagpie.ai/install.sh | sh

macOS users can also install via Homebrew Cask:

bash
brew install --cask magpie-app

Verify your installation:

bash
magpie --version

Step 2: Add Your First Provider

Register an API key or mount an existing web subscription:

bash
# Add DeepSeek official API key
magpie provider add deepseek sk-xxxxxxxxxxxxxxxxxxxxxxxx

# Or mount an existing Claude Pro web session
magpie accounts add claude

Step 3: Bind an Agent to a Model

Bind Claude Code to your newly configured DeepSeek model in one command:

bash
magpie claude deepseek/deepseek-v4-pro

Magpie updates ~/.claude.json via surgical AST modification, directing traffic to http://127.0.0.1:3425.

Step 4: Launch Your Coding Assistant

Open a fresh terminal window and launch Claude Code:

bash
claude

Assign a real coding task:

text
> Refactor utils.ts to improve error handling and generate unit test suites covering edge cases

Claude Code will run fully powered by DeepSeek. File inspections, bash executions, and MCP tools function seamlessly—with API token costs reduced by up to 90%!

Choose Your Preferred Interface

  • Terminal Native: Run magpie tui for an interactive dashboard with arrow-key switching, live request monitoring, and quota metrics.
  • Menu Bar User: Click the Magpie icon in your macOS menu bar to swap models via dropdowns in seconds.
  • Script Automator: Use magpie ls to inspect bindings, and swap entire setups using magpie save <profile> / magpie use <profile>.

Next Steps & Deep Dives

FAQ

Q: Why does Claude Code report "Connection Refused" after setup?

A: This indicates that the local gateway service is not active. Run magpie ls to inspect gateway status, or launch it with magpie daemon start (or simply launch the desktop menu bar application).

Q: Do I need commercial API keys to use Magpie AI?

A: Not necessarily. In addition to commercial API keys, Magpie AI supports Shared Subscriptions. Run magpie accounts add claude or magpie accounts add chatgpt to mount existing Claude Pro or ChatGPT Plus web plans and reuse their quota in your CLI assistants.

Q: How do I restore an assistant back to its default vendor settings?

A: Run magpie reset [agent-name] (e.g. magpie reset claude) to immediately remove gateway bindings and restore factory configuration. To revert all tools at once, use magpie reset --all.