README
¶
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 |
🔌 One gateway for every API |
🔀 Routing that keeps going |
|
🔑 Subscriptions you can share |
🧩 Plugins |
📊 Usage and cost tracking |
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.
|
|
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
claudebinary 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.
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/magpieon 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
Documentation
Source Files
¶
- accounts_cli.go
- autostart_cli.go
- backup_cmd.go
- gateway_keys_cli.go
- groups_cli.go
- groups_rules_cli.go
- gui_on.go
- healthcheck_cli.go
- library_cli.go
- main.go
- model_cli.go
- plugins_cli.go
- providers_cli.go
- quota_cli.go
- quota_wait.go
- search_cli.go
- sessions_cli.go
- signals.go
- signals_unix.go
- update_cli.go
- usage_cli.go
- visible_cli.go
- web_cli.go
- webdav_cli.go
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
access
Package access keeps the named API keys issued by the gateway.
|
Package access keeps the named API keys issued by the gateway. |
|
agent
Package agent describes every coding agent magpie can drive: where its config lives, which fields matter (model, effort, …) and which values to offer.
|
Package agent describes every coding agent magpie can drive: where its config lives, which fields matter (model, effort, …) and which values to offer. |
|
agentenv
Package agentenv names the environment variables through which an agent really installed on this machine reaches magpie: the one list a test sandbox clears, so that a test meets only the agents it put there itself.
|
Package agentenv names the environment variables through which an agent really installed on this machine reaches magpie: the one list a test sandbox clears, so that a test meets only the agents it put there itself. |
|
appdir
Package appdir decides where magpie keeps its own files: the one place every other package asks (#508).
|
Package appdir decides where magpie keeps its own files: the one place every other package asks (#508). |
|
autostart
Package autostart opens magpie when the user logs in, in the tray with no window, so the gateway every agent is pointed at is there from the start.
|
Package autostart opens magpie when the user logs in, in the tray with no window, so the gateway every agent is pointed at is there from the start. |
|
awake
Package awake keeps the computer from going to sleep by itself while agents work through magpie's gateway (xiao_wang24004 on X: the computer went to sleep in the middle of an agent's task).
|
Package awake keeps the computer from going to sleep by itself while agents work through magpie's gateway (xiao_wang24004 on X: the computer went to sleep in the middle of an agent's task). |
|
backup
Package backup packs what the user set up in magpie into one file, sealed with a passphrase, to carry to another machine: the providers (their keys too, unless left out), the pictures picked for them, the settings, the profiles, every agent's model and the library (the instructions, MCP servers and skills magpie gives the agents).
|
Package backup packs what the user set up in magpie into one file, sealed with a passphrase, to carry to another machine: the providers (their keys too, unless left out), the pictures picked for them, the settings, the profiles, every agent's model and the library (the instructions, MCP servers and skills magpie gives the agents). |
|
budget
Package budget holds each gateway key to its own limit (#585): what a key has used in its window is summed from usage.jsonl, the records the Usage page shows, so it survives a restart; a request is let in only while the key has something left after what its requests in flight are expected to use, and those are settled with what the call recorded.
|
Package budget holds each gateway key to its own limit (#585): what a key has used in its window is summed from usage.jsonl, the records the Usage page shows, so it survives a restart; a request is let in only while the key has something left after what its requests in flight are expected to use, and those are settled with what the call recorded. |
|
catalog
Package catalog knows which models exist.
|
Package catalog knows which models exist. |
|
claudebridge
Package claudebridge contains the small stdio MCP helper used by magpie's Claude Subscription bridge.
|
Package claudebridge contains the small stdio MCP helper used by magpie's Claude Subscription bridge. |
|
codexcat
Package codexcat renders models the way Codex describes them: the entries of its models.json, for `model_catalog_json` and for the model list magpie hands Codex in place of the ChatGPT backend's.
|
Package codexcat renders models the way Codex describes them: the entries of its models.json, for `model_catalog_json` and for the model list magpie hands Codex in place of the ChatGPT backend's. |
|
davsync
Package davsync keeps magpie's setup the same on every computer through a WebDAV folder or an S3-compatible bucket.
|
Package davsync keeps magpie's setup the same on every computer through a WebDAV folder or an S3-compatible bucket. |
|
edit
Package edit provides format-preserving editors for the config files that coding agents keep: JSON/JSONC, TOML and YAML.
|
Package edit provides format-preserving editors for the config files that coding agents keep: JSON/JSONC, TOML and YAML. |
|
filememo
Package filememo keeps what was parsed from a file until the file changes, so a page that asks many times over reads it once.
|
Package filememo keeps what was parsed from a file until the file changes, so a page that asks many times over reads it once. |
|
fx
Package fx keeps the dollar-to-yuan rate the CNY currency preference (see internal/settings) converts list-price costs with.
|
Package fx keeps the dollar-to-yuan rate the CNY currency preference (see internal/settings) converts list-price costs with. |
|
gateway
Package gateway is the local LLM endpoint agents talk to.
|
Package gateway is the local LLM endpoint agents talk to. |
|
gui
Package gui hosts the desktop app: a tray panel and a regular window that share one small web UI.
|
Package gui hosts the desktop app: a tray panel and a regular window that share one small web UI. |
|
gui/genpurposes
command
genpurposes generates the browser's request-kind catalog from usage's catalog.
|
genpurposes generates the browser's request-kind catalog from usage's catalog. |
|
imagemcp
Package imagemcp is `magpie mcp image`: a stdio MCP server an agent is given, when it is picked for it in the Library, to make images with the model the Settings' Image generation names, and videos with a Grok subscription.
|
Package imagemcp is `magpie mcp image`: a stdio MCP server an agent is given, when it is picked for it in the Library, to make images with the model the Settings' Image generation names, and videos with a Grok subscription. |
|
library
Package library keeps what every agent should know, once: the instructions each reads before a conversation, the MCP servers it can call and the skills it can load.
|
Package library keeps what every agent should know, once: the instructions each reads before a conversation, the MCP servers it can call and the skills it can load. |
|
mcpauth
Package mcpauth signs magpie in to a remote MCP server that asks for an OAuth sign-in (Neon, Notion, Supabase…), once for every agent (#615).
|
Package mcpauth signs magpie in to a remote MCP server that asks for an OAuth sign-in (Neon, Notion, Supabase…), once for every agent (#615). |
|
mcpauth/mcpauthtest
Package mcpauthtest is a remote MCP server behind an OAuth sign-in, as Neon's or Notion's is, for the tests of magpie signing in to one (#615).
|
Package mcpauthtest is a remote MCP server behind an OAuth sign-in, as Neon's or Notion's is, for the tests of magpie signing in to one (#615). |
|
middleware
Package middleware runs the gateway middleware plugins declare: a module with onRequest, onEvent and onResponse hooks that the gateway calls on every request an agent sends it, every event of the reply's stream and every whole reply.
|
Package middleware runs the gateway middleware plugins declare: a module with onRequest, onEvent and onResponse hooks that the gateway calls on every request an agent sends it, every event of the reply's stream and every whole reply. |
|
netproxy
Package netproxy decides which proxy magpie's own requests to vendors go through.
|
Package netproxy decides which proxy magpie's own requests to vendors go through. |
|
omarchy
Package omarchy is what magpie knows of Omarchy (omarchy.org), the Hyprland desktop: whether it runs on one, and the look its current theme gives every surface, so magpie's windows can take that look there and nowhere else.
|
Package omarchy is what magpie knows of Omarchy (omarchy.org), the Hyprland desktop: whether it runs on one, and the look its current theme gives every surface, so magpie's windows can take that look there and nowhere else. |
|
plugin
Package plugin runs OpenCode's provider plugins for magpie.
|
Package plugin runs OpenCode's provider plugins for magpie. |
|
proc
Package proc makes the commands magpie runs: agents' CLIs, the probes that ask them what they have, the system's own tools.
|
Package proc makes the commands magpie runs: agents' CLIs, the probes that ask them what they have, the system's own tools. |
|
profile
Package profile stores named snapshots of every agent's settings, and of who gets what from the library, so a whole setup can be switched in one move.
|
Package profile stores named snapshots of every agent's settings, and of who gets what from the library, so a whole setup can be switched in one move. |
|
provider
Package provider holds the model vendors magpie can reach: where each one lives, which protocols it speaks, the API key the user typed in, and which of its models should show up in the agents' pickers.
|
Package provider holds the model vendors magpie can reach: where each one lives, which protocols it speaks, the API key the user typed in, and which of its models should show up in the agents' pickers. |
|
qoder
Package qoder speaks Qoder's inference API (api3.qoder.sh agent_chat_generation SSE) the way the Qoder desktop client does, so a Qoder subscription can serve every agent through magpie's gateway.
|
Package qoder speaks Qoder's inference API (api3.qoder.sh agent_chat_generation SSE) the way the Qoder desktop client does, so a Qoder subscription can serve every agent through magpie's gateway. |
|
redact
Package redact keeps secrets on the machine.
|
Package redact keeps secrets on the machine. |
|
sessions
Package sessions lists the agents' recent sessions from their own session files — Claude Code's projects/*/<id>.jsonl (and Qoder's, the same kind), Codex's rollout files, OpenCode's database (or its older JSON files) and ZCode's, Pi's session files and omp's, DeepSeek Harness's, Cline's, Grok Build's, WorkBuddy's, Droid's, Cursor CLI's and Alma's chat stores — with the tokens each spent, what that cost at the effective price, and the command that resumes it.
|
Package sessions lists the agents' recent sessions from their own session files — Claude Code's projects/*/<id>.jsonl (and Qoder's, the same kind), Codex's rollout files, OpenCode's database (or its older JSON files) and ZCode's, Pi's session files and omp's, DeepSeek Harness's, Cline's, Grok Build's, WorkBuddy's, Droid's, Cursor CLI's and Alma's chat stores — with the tokens each spent, what that cost at the effective price, and the command that resumes it. |
|
settings
Package settings keeps the few preferences the desktop app has: which palette to paint with, which language to speak, how the agents are arranged.
|
Package settings keeps the few preferences the desktop app has: which palette to paint with, which language to speak, how the agents are arranged. |
|
shortcut
Package shortcut puts magpie in the Start menu on Windows.
|
Package shortcut puts magpie in the Start menu on Windows. |
|
source
Package source chooses where magpie reads from, with a mirror as a fallback when the official address can't be reached.
|
Package source chooses where magpie reads from, with a mirror as a fallback when the official address can't be reached. |
|
stats
Package stats counts magpie's users: once a day a running magpie tells PostHog it is in use, under an id made up on this computer, with its version and system.
|
Package stats counts magpie's users: once a day a running magpie tells PostHog it is in use, under an id made up on this computer, with its version and system. |
|
steady
Package steady reads and replaces files that another process may be replacing at that moment.
|
Package steady reads and replaces files that another process may be replacing at that moment. |
|
testenv
Package testenv gives a package's tests a home of their own, on every OS: HOME, USERPROFILE (Windows' home), the XDG folders and Windows' APPDATA and LOCALAPPDATA all point into one new temporary folder, the agents' own variables (agentenv.Vars) are cleared, and the keychain tools and agent CLIs on PATH are failing stand-ins, so that no test reads or writes the files of the user running it.
|
Package testenv gives a package's tests a home of their own, on every OS: HOME, USERPROFILE (Windows' home), the XDG folders and Windows' APPDATA and LOCALAPPDATA all point into one new temporary folder, the agents' own variables (agentenv.Vars) are cleared, and the keychain tools and agent CLIs on PATH are failing stand-ins, so that no test reads or writes the files of the user running it. |
|
tui
Package tui is magpie in the terminal: one row per agent, arrow keys to pick a field, enter to change it; and pages for providers and usage beside it (pages.go), routing groups (routing.go), sessions (sessions.go) and the library (library.go), 1–6 to go between them.
|
Package tui is magpie in the terminal: one row per agent, arrow keys to pick a field, enter to change it; and pages for providers and usage beside it (pages.go), routing groups (routing.go), sessions (sessions.go) and the library (library.go), 1–6 to go between them. |
|
update
Package update keeps magpie current.
|
Package update keeps magpie current. |
|
usage
Package usage keeps the token count of every call the gateway serves, so magpie can show what each agent and model consumed and roughly what it cost.
|
Package usage keeps the token count of every call the gateway serves, so magpie can show what each agent and model consumed and roughly what it cost. |
|
wslrun
Package wslrun runs, from magpie on Windows, a command that is installed only in a WSL distro: Claude Code signed in to inside Ubuntu, say.
|
Package wslrun runs, from magpie on Windows, a command that is installed only in a WSL distro: Claude Code signed in to inside Ubuntu, say. |
|
zed
Package zed speaks to Zed's hosted models, the way the Zed editor does for a Zed Pro (or trial, student, business) account.
|
Package zed speaks to Zed's hosted models, the way the Zed editor does for a Zed Pro (or trial, student, business) account. |