Install Magpie
One command on macOS and Linux, one installer on Windows. Ten minutes later Claude Code is running on Kimi, Codex is running on DeepSeek, and you know where to change it back.
The whole install, macOS & Linux
curl -fsSL https://usemagpie.ai/install.sh | shThe script is served by the official site. If you would rather read it before running it, open usemagpie.ai/install.sh first, or install from the latest GitHub release.
Pick your platform
macOS
- Apple Silicon build
- Intel build
- or
curl -fsSL https://usemagpie.ai/install.sh | sh
The installer puts the magpie command in ~/.local/bin and the app in /Applications. The build is signed and notarised.
Windows
- x64 build
- ARM build
- terminal-only:
magpie-cli-windows-amd64.exefrom the latest release
magpie.exe takes the same commands as the Mac and Linux builds, so every step below works unchanged in PowerShell or Windows Terminal.
Linux
- x86-64 build
- ARM64 build
- or the same
curl … | shcommand
Needs GTK 3 and WebKitGTK 4.1. The desktop entry lands in your app menu; the CLI goes to ~/.local/bin.
- macOS — 11 or later, Apple Silicon or Intel
- Windows — 10 or later, x64 or ARM
- Linux — GTK 3 + WebKitGTK 4.1, x86-64 or ARM64
- Size — under 15 MB with the desktop app, about 7 MB terminal-only
- Licence — MIT, free, no account
Requirement details come from the official download page; one part of that page lists macOS 12+ and another lists macOS 11+, so check the official page for your build before installing on an older Mac.
Step 1 — Install, then confirm it is there
# install (macOS / Linux)
curl -fsSL https://usemagpie.ai/install.sh | sh
# list every agent on this machine and the model it is set to
magpie lsmagpie ls is the fastest proof the install worked, because it can only print that list if the binary runs. Anything you have never installed will not appear — Magpie only shows agents that are installed or configured on the machine.
Step 2 — Add a provider
# a preset needs only the key
magpie provider add deepseek sk-…
magpie provider add moonshot sk-…
# local servers need no key at all
magpie provider add ollama
# see what you have, and which agents use it
magpie providers
magpie presets26+ presets cover vendors, relays and local servers: Anthropic, OpenAI, Gemini, DeepSeek, Kimi, GLM, MiniMax, Qwen, Mistral, Groq, xAI, OpenRouter, Together, Fireworks, SiliconFlow, Ollama, LM Studio and more. With a key in hand Magpie asks the vendor which models it serves and offers exactly those, so a model released this morning appears in the pickers on the next refresh.
ANTHROPIC_API_KEY or OPENAI_API_KEY sitting in your .zshrc is ignored. What you add to Magpie is what it uses.
Step 3 — Give an agent a third-party model
magpie codex deepseek/deepseek-v4-pro
magpie claude moonshot/kimi-k3
magpie gemini zhipu/glm-5.3
# your Claude plan, available to OpenCode
magpie opencode claude/claude-sonnet-5Each command rewrites only the provider and model keys in that agent's own config file. Comments, ordering and indentation survive, and the write is atomic — so a settings.json you hand-edited hours ago does not get reformatted underneath you.
Changed your mind? Pick the native model and Magpie puts back exactly what was there before.
Step 4 — Confirm the gateway is serving
# one tiny request per API, with the latency
magpie provider test deepseek
# the model catalog the agents see
magpie modelsEvery model is spelled provider/model and served by the gateway on http://127.0.0.1:3425/v1. Codex speaks OpenAI Responses, Claude Code speaks Anthropic Messages, Gemini CLI speaks Gemini — Magpie speaks all of them and translates in both directions, streaming and tool calls included. Agents therefore never hold vendor keys or vendor URLs.
Step 5 — Save the setup as a profile
magpie save work
magpie use work
# one model across several providers, in order
magpie group add opus models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order
magpie claude group/opus
# the whole app, in the terminal
magpie tuiA profile is a snapshot of every agent's settings under a name, so switching all of them back is one command — "Budget", "Focus", whatever you save. This is the step that turns a one-off experiment into a setup you can actually live in.
Where Magpie writes
Useful when you want to check a change by hand, or back up before a big switch. Every path below is the file Magpie edits for that agent.
| Agent | Config file | Fields Magpie sets |
|---|---|---|
| Claude Code | ~/.claude/settings.json | provider, model, opus/sonnet/haiku/fable |
| Codex | ~/.codex/config.toml | provider, model, effort |
| Gemini CLI | ~/.gemini/settings.json, ~/.gemini/.env | auth, model |
| OpenCode | ~/.config/opencode/opencode.json(c) | model, small |
| Goose | ~/.config/goose/config.yaml | model |
| Crush | ~/.config/crush/crush.json | large, small |
| Cursor CLI | ~/.cursor/cli-config.json | model |
| Copilot CLI | ~/.copilot/settings.json | model |
Magpie supports 29 agents in total, including Claude Desktop, OpenChamber, MiMo Code, Pi, Devin, Kimi Code, Grok Build, Cline, Qoder and Hermes Agent. The full list with paths is on the Agents page.
When something does not work
“My agent isn't in the list”
Magpie only shows agents that are installed or configured. Install the agent, run it once so it writes its own config file, then reopen Magpie. A tool you have merely heard of will not appear.
“I added a key in my shell but Magpie still asks for one”
That is by design — Magpie never reads keys from environment variables. Add it to Magpie instead: magpie provider add deepseek sk-…, or use Add provider in the app.
“A provider shows no models”
Run magpie provider models deepseek to re-fetch the vendor's list. You can also choose which models a provider exposes rather than exposing all of them, and the models.dev catalog fills in names and reasoning efforts for vendors that serve no list of their own.
“Requests fail even though the key is right”
magpie provider test deepseek sends one small request per API and reports latency, which separates “the key is wrong” from “this vendor has no endpoint for the API your agent speaks”. If the second is the case, Magpie's gateway is what translates it — so either point the agent at a model whose vendor does speak that protocol, or add the vendor's Anthropic-compatible base URL with anthropic= when it has one.
“The magpie command is not found after installing”
The installer drops the binary into ~/.local/bin and does not edit your shell profile. Make sure that directory is on your PATH, then open a new terminal. On Windows, the equivalent is the folder that holds magpie.exe.
“Do I lose my Claude or ChatGPT subscription by doing this?”
No, and you do not paste anything. Sign in to Claude Code, Codex (ChatGPT) or Copilot as usual, and that login appears in Magpie as a provider; its models then reach every other agent through the gateway, with tokens refreshed the way the agent itself does it.
“How do I undo the whole thing?”
Point the agent back at its native model and Magpie restores exactly what was in the file before. Nothing is overwritten in place — only the keys you changed are touched, and the write is atomic — so a backup of your own is rarely needed, but taking one before the first switch costs nothing.