magpie/README.md

magpie

Every agent's model. One place.

Claude Code on Kimi, Codex on DeepSeek, Gemini CLI on GLM, OpenCode on your ChatGPT plan.
Switch them from the menu bar. One local gateway serves them all, and it moves to another account when a quota runs out.

Download · Docs · Reference · Discord · English · 简体中文

Why magpie

You probably use more than one coding agent. Each one keeps its model in its own file, in its own format, with its own keys and base URLs. Each one also has its own idea of which vendors it supports. A subscription you pay for works in one agent and nowhere else. When it runs out at 3 pm, you start editing config files.

magpie puts all of it in one place:

🎛 One screen for every agent Over 35 agents in one list. Click a model and pick another. magpie changes only that one key in the agent's own config file. Comments, ordering and formatting stay as they were.	🔌 One gateway for every API 127.0.0.1:3425 speaks OpenAI Chat, OpenAI Responses, Anthropic Messages and Gemini. It translates between them, streaming, tool calls and reasoning included.	🔀 Routing that keeps going Put several models from several providers in a routing group. When one hits a rate limit or runs out of quota, the next one answers. Your agent never sees the error.
🔑 Subscriptions you can share Your Claude, ChatGPT, Copilot, Gemini or Grok sign-in becomes a provider that every other agent can use. There is no key to copy.	🧩 Plugins OpenCode auth plugins and pi provider packages from npm run in magpie as they do in their own apps. Any plan a plugin signs in to works in every agent. A plugin can also be gateway middleware that reads and rewrites every request and reply.	📊 Usage and cost tracking See tokens, cache hits, cost at list price, balances and quota windows for every provider and account. You can also set a limit for each key.

Pick any model for any agent

Click a value and a filtered list opens. It holds every model of every provider you added, as provider/model. Pick one and the agent's config file is rewritten safely and atomically. Use Profiles to save the setup of every agent under one name ("Budget", "Focus") and switch them all at once.

magpie also lives in the menu bar. There is a tray panel on macOS, Windows and Linux, a full window, a TUI (magpie tui), a web UI (magpie web) and a plain CLI.

Add providers with one field

Pick a preset and paste a key. That's it. The model list comes from the vendor itself, with names and reasoning levels filled in from models.dev, so a model released this morning shows up on the next refresh. No model list is built into magpie.

Presets include Anthropic · OpenAI · Google Gemini · DeepSeek · Kimi · Zhipu GLM · MiniMax · StepFun · Qwen · Baidu Qianfan · Tencent Cloud · Huawei Cloud MaaS · Volcengine Ark · Mistral · Groq · xAI · OpenRouter · Together · Fireworks · SiliconFlow · NVIDIA NIM · ModelScope · Ollama · LM Studio … and any OpenAI-compatible or Anthropic-compatible URL.

Already set up somewhere else? Import reads the providers you set up in CC Switch, Claude Code, Codex and Alma. Add to magpie links let a provider's website hand its config to magpie in one click.

Routing that keeps going

A routing group is several models that an agent picks as one: group/daily-coding. The gateway spreads requests over every member's keys and accounts:

Mode	What it does
smart	Of the subscriptions with quota left, use the one whose allowance renews soonest, so less is lost at the reset
order	Use the first model until it can't answer, then the next
rotate	Move to the next member on each turn
usage	Use the least-used member first
pace	Use the account with the most of its week left per hour until its reset

Conversations stay with the account that answered them while the vendor's prompt cache is still worth keeping. Intent routing goes further: a small model you choose reads each new turn, so tests can go to the strong model and quick questions to the fast, cheap one. Groups can contain other groups. The Routing tab shows each decision live.

→ Intent routing, in depth

Sign in once, use it everywhere

An agent you're signed in to is a subscription with models behind it, so magpie offers it as a provider. Several accounts per subscription are supported, and magpie fails over between them.

• Claude: drives the real local claude binary and bridges your agent's tools over MCP
• Codex / ChatGPT: your ChatGPT plan's models in every other agent
• GitHub Copilot, Gemini (Code Assist), Antigravity, Grok (SuperGrok), Devin, Cursor and others
• Any OpenCode auth plugin or pi package from npm:

magpie plugin add opencode-gemini-auth   # an OpenCode plugin from npm
magpie plugin add pi-antigravity         # a pi package, the same way
magpie plugin login google-plugin        # its own sign-in flow, in magpie

magpie runs plugins on Bun, which it downloads the first time a plugin needs it. A plugin signs in, lists its models and makes each request. Agents use its models like any other provider's. Browse the community plugins at magpie-community/plugins, or write your own.

A plugin can also be gateway middleware: JavaScript run inside magpie's gateway on what every agent sends and gets back, whatever the provider. onRequest can rewrite a request or turn it away, onEvent sees each streamed event, and onResponse sees a whole reply. It runs in-process, so an event costs about a microsecond, and a hook that throws or runs too long leaves the request as it was.

// alias.middleware.js — magpie plugin add ./alias.middleware.js
export function onRequest(body, ctx) {
  if (body.model === "fast") return { ...body, model: "deepseek/deepseek-chat" };
}

Ready-made middleware, most of it what New API does for its channels, with the same JSON, is under Plugins › Discover › Gateway middleware:

Package	What it does
param-override	New API's param_override: set, delete, move or rewrite request fields, under conditions, or turn a request away
model-map	New API's model_mapping: send a model under another name; replies keep the name asked for
system-prompt	Your system prompt on every request, or some agents' or models'
word-guard	New API's sensitive-word filter: turn away or mask words in what users send, and in replies
think-tags	Take <think>…</think> out of replies, or put reasoning_content into them

magpie plugin add @magpie-community/middleware-model-map
magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}}'

See Gateway middleware.

Usage and cost tracking

• Tokens, cache reads and writes, reasoning tokens and calls, with cost at list price. You can set your own prices for each model.
• Balances and quota windows for every key, plan and subscription account (magpie quota). The reset reminder warns you before a window renews with much of it unused.
• Usage by session: each agent conversation with its cost and title, and a command to resume it.
• Usage by account and by upstream key, so you can check a vendor's bill line by line.
• OTLP export to your own observability stack.

Share one magpie

• Share it on your network. Turn on Share on local network, then create a named gateway key for each client, each with its own daily, weekly or monthly token and cost limit.
• Remote magpie. A laptop can use the providers, accounts and routing groups of the magpie on your desktop, while still wiring its own agents.
• Docker. Run ghcr.io/yetone/magpie on a server or a NAS, and manage it from the web UI.
• Sync. Back up to a file, or keep machines in sync over WebDAV (Nutstore, Nextcloud…) or S3.

Library: instructions, MCP servers and skills

Write your instructions, MCP servers and skills once. magpie writes them into each agent's own files in that agent's own format. It removes only what it wrote, so everything else in those files stays as it was.

Supported agents

Claude Code · Claude Desktop · Codex · Gemini CLI · OpenCode · OpenChamber · MiMo Code · Pi · Aside · OmO · Goose · Cursor CLI · Zed · VS Code Chat · JetBrains Air · Copilot CLI · Crush · DeepSeek Harness · Command Code · fx · oh-my-pi · Devin · Hermes Agent · Mister Morph · Kimi Code · Muse Code · Empryo · MiniMax Code · Droid · Cline · Qoder · Qoder CN · Grok Build · ZCode · WorkBuddy · T3 Code · OpenHanako · AtomCode · Alma

magpie shows only the agents installed on your machine. Anything else that takes a base URL can use the gateway too:

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1     OPENAI_API_KEY=magpie
export ANTHROPIC_BASE_URL=http://127.0.0.1:3425     ANTHROPIC_API_KEY=magpie
export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425 GEMINI_API_KEY=magpie

Quick start

1. Install. Download the app from usemagpie.ai, or run:

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

_{Mac builds are signed and notarised. Every build updates itself. Behind a firewall, use --proxy or --mirror. You can also use go install github.com/yetone/magpie@latest, or the Docker image.}

2. Add a provider. Open magpie, then go to Providers → Add provider. Pick a preset, or sign in with a subscription.

3. Pick a model for each agent on the Agents page. Start a new agent session and it uses the new model.

Or do the same from the terminal:

magpie provider add deepseek sk-…              # a preset needs only the key
magpie claude deepseek/deepseek-v4-pro          # Claude Code on DeepSeek
magpie codex moonshot/kimi-k2.5                 # Codex on Kimi
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=smart
magpie claude group/opus-anywhere               # fails over between subscriptions
magpie save work && magpie use work             # profiles
magpie quota                                    # what's left on every plan
magpie tui                                      # the whole thing, in a terminal

Documentation

• Get started: the guided tour
• Reference: every agent, provider option, gateway endpoint, CLI command and file
• Plugins: use plugins and write your own
• Intent routing: route each turn by what it asks for
• Import links: "Add to magpie" buttons for provider websites

Community

Questions, ideas or a model that won't show up? Join us on Discord or open an issue.

If magpie saves you from editing one more config file, a ⭐ helps others find it.

License

MIT