Docs · Guide

Get started

magpie is one place to choose the model each of your agents uses. Add the providers you have, then pick a model per agent; magpie writes it into that agent’s own config.

Behind it is a small gateway on your machine, at 127.0.0.1:3425. It speaks the OpenAI, Anthropic and Gemini APIs and translates between them, streaming and tool calls included, so any agent can use any provider’s models: Claude Code on a GPT model from your ChatGPT plan, Codex on DeepSeek, OpenCode on your Claude plan.

1. Add providersSign in to your subscriptions, paste API keys. Once is enough.
2. Pick a model for each agentClick the agent’s model, choose one. magpie rewrites that agent’s config.
3. Start a new sessionAgents read their config when they start; the next session uses the new model.

1 · Add your providers

Open the Providers tab and press ＋ Add provider. Pick a tile, or type a vendor’s name to find it.

Subscriptions · sign in, no key

Claude (Pro, Max, Team), ChatGPT (Plus, Pro, Business), Cursor, Grok (SuperGrok), Copilot and Devin. Click the tile and magpie opens the vendor’s own sign-in page in your browser; the account shows up as soon as you finish (Copilot gives you a code to enter on GitHub’s page). Subscriptions are added here, in magpie, not by logging in inside another agent.

• More than one account. Click the Claude or ChatGPT tile again to add another; each is listed under the provider, one click from being the one in use.
• Already signed in? An agent you are signed in to on this machine shows up as a provider too, signed in as ….
• Every agent can use it. A subscription’s models are claude/…, codex/…, copilot/… in every other agent’s picker. Claude subscription requests run through the Claude Code installed on this machine, so keep it installed.

Vendors

Anthropic, OpenAI, Google Gemini, DeepSeek, Kimi, Zhipu GLM, MiniMax, Qwen, Mistral, Groq, xAI and more. Pick one, paste the key (Get a key ↗ links to the vendor’s key page), save. magpie asks the vendor which models it serves and offers those; open the provider’s row to choose which ones agents see, or Test it.

On this machine

Ollama and LM Studio. No key.

Custom · any compatible URL

For anything else: a Name, an OpenAI compatible base URL (ending in /v1), an Anthropic compatible one (the root, what ANTHROPIC_BASE_URL would take), or both, and the key. Give every API the endpoint speaks; each agent uses the one it speaks natively and magpie translates for the rest.

Keys live in ~/.config/magpie/providers.json, readable by you alone. magpie never reads keys from your shell environment: what you add is what it uses.

2 · Pick a model for each agent

The Agents tab has a row for each agent installed or configured on this machine. magpie knows Claude Code, Codex, Gemini CLI, OpenCode, MiMo Code, Pi, Goose, Cursor, Copilot CLI, Crush, DeepSeek Harness, Command Code, omp, OmO, Devin, Hermes Agent, Grok Build, ZCode, OpenHanako and Alma.

• Click the model to open the picker. Models are grouped: the agent’s own, your routing groups, then each provider you added. Type to filter, or type any model id that is not listed.
• Reasoning effort, where the agent has it (Codex’s effort, Pi’s thinking), is a slider under the list.
• Claude Code through magpie can also give its opus, sonnet and haiku tiers models of their own; by default they follow the main model.

Picking a model writes it into the agent’s own config file. Only the keys magpie needs change; comments, ordering and indentation survive, and writes are atomic.

A running session keeps the model it started with. Agents read their config when they start, so the change applies to the next session. Codex builds its model list at start-up too: restart the Codex app and open codex sessions after a switch.

3 · Optional: routing groups

With one account per provider you can skip this. It matters once you have several: two ChatGPT accounts, or the same model from a subscription and from a key.

Several accounts or keys in one provider

Open the provider’s row and tick every account or key to use. Routing says how requests spread over them: Smart (the default), In order, In turn or Least used first. Fallback lists models to use instead when the provider is out of quota, rate limited or down.

One model over several providers

A group is several models, from one provider or many, that an agent picks as one: group/<id>, under Routing groups in the picker. A model two of your providers serve under the same name becomes a group on its own; New group in the Routing tab makes one of any models you like. The first model answers for what the group can do.

Rules · a turn to a chosen model

A group’s Rules send a turn to one of its models when the turn is of a kind you name: long (tokens ≥ N), carrying an image, asking for reasoning (on, or at least a level), from certain agents, asking for something you describe (an intent), or the agent compacting its context. They are looked at top first when you send a message; the first that matches puts its model first, with the group’s others behind it if it fails. A turn no rule matches is routed as the group always routes, and keeps to where it was.

• A rule decides as a turn begins, and the turn stays on that model while the agent sends tool results back, so what the vendor cached isn’t lost halfway. The one exception: a turn that grows past its model’s context moves to a member that takes it.
• Tokens are estimated from the request’s size, or what the vendor counted for the conversation’s last request, whichever is more. Leave some margin: a rule at 150k for a 200k model, not 199k.
• A subagent is a conversation of its own, so a rule can send it elsewhere while its agent keeps where it is.
• An intent is a few words for what the user asks for — “writing or fixing tests”, “a quick question”. As a turn begins, the group’s classifier — any model magpie has; a small, fast one without reasoning is best — is asked once which of the intents that could match the user’s message is. Only the message is sent, not the conversation. If it fails, is slow (8 s) or can’t say, no intent matches and the turn goes by the other rules. It isn’t asked when a rule without an intent would decide anyway, and the same message isn’t asked about twice. Its calls show in Usage as magpie’s own. Exactly what it is asked, how its answer is used and what happens when it fails: Intent routing.
• compacting matches an agent compacting its conversation — Claude Code’s /compact and auto-compact, Codex, OpenCode, Pi, Gemini CLI, Qwen Code, Kimi Code — so a cheaper, faster model writes the summary while the conversation stays on its own. A compaction is decided on its own: the turn it happens in, and its cache, stay where they were. When the conversation is longer than the rule’s model takes, the next rule that matches, or the group’s order, decides instead.
• The Routing tab says which rule sent each turn where, and what the classifier said.

Groups in groups

A group’s models can include another group: pick it under Routing groups in Add a model, or models+=group/<id> from a terminal. The group in it takes its place in the order and routes among its own models by its own routing and rules. So Coder can be deepseek-v4-pro then Fast, and Fast its own order of cheap models. A Coder rule can send a turn to group/fast, and Fast’s own rules then pick which of its models goes first.

• No loops. A group can’t be in itself, directly or through the groups in it. Saving Fast with Coder in it, while Coder has Fast, is refused, and the picker doesn’t offer such a group. Groups go at most 8 deep. A group can’t be removed while another has it: take it out there first.
• Failover goes through. If every model in the inner group fails, the outer group’s next member answers, as with any member.
• A model that appears twice (on its own and in a group in it) is asked once, at its first place.

The Routing tab shows the gateway’s decisions live: who answered each request, and why. The same groups from a terminal:

magpie groups                        # yours, then those magpie found
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order stays=session
magpie group set opus-anywhere models+=openrouter/anthropic/claude-opus-5.5
magpie group rule add opus-anywhere use=openrouter/anthropic/claude-opus-5.5 tokens=150k  # long turns to it first
magpie group rule add opus-anywhere use=copilot/claude-opus-5.5 intent="a quick question" classifier=groq/llama-3.1-8b-instant
magpie group rule add opus-anywhere use=deepseek/deepseek-v4-flash compact  # /compact summaries to a cheap model
magpie group set coder models+=group/opus-anywhere  # a group in a group
magpie group rule opus-anywhere      # its rules; rule rm|mv <n>, rule classifier <group> <model>
magpie group rm opus-anywhere        # one magpie found is hidden; magpie group restore <id>
magpie claude group/opus-anywhere    # use it

Usage and profiles

Usage. The Usage tab counts tokens, cache hits and cost for each agent and model, from every call through the gateway, for Today, 7 days, 30 days or All; your subscriptions’ allowance used, and when it resets, sits on top. Calls an agent makes to its own vendor directly don’t pass through magpie and aren’t counted.

Profiles. At the bottom of the Agents tab, ＋ Save current snapshots every agent’s settings under a name; click the chip to switch everything back in one move.

From the terminal

magpie tui is the whole app in a terminal, and every step above has a command. magpie help lists them all.

FAQ

Do I need to export OPENAI_BASE_URL or ANTHROPIC_BASE_URL?

No. For the agents magpie lists, it writes the gateway’s address and token into the agent’s own config file. Those variables are only for other tools with a base-URL setting: the Gateway tab’s Connect section has them as copy buttons and snippets.

Does magpie have to be running?

For a model through magpie, yes: the gateway runs with the app. Closing the window leaves it running in the menu bar or tray; magpie tray starts the icon alone (put it in your login items), and magpie serve runs just the gateway. An agent on its own model and its own sign-in doesn’t go through magpie.

How do I put an agent back the way it was?

Pick one of the agent’s own models in the picker, or run magpie <agent> default. magpie removes what it wrote and restores the values it replaced, such as an ANTHROPIC_BASE_URL you had before.

I switched models, but my agent still uses the old one.

A running session keeps what it started with. Start a new one; for Codex, restart the Codex app too.

Does editing the agent’s config by hand break anything?

No. magpie reads the files each time and touches only the keys it sets, so your other settings and comments stay. Providers brought over with Import… are copies: later changes in the agent’s settings aren’t copied again.

Stuck, or have a setup worth sharing? Ask on Discord. Vendors who want to hand their users a ready-made provider: see Add to magpie.