Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

150 KB
Raw Blame

Agent wiring

magpie connects a coding agent to its gateway by editing the agent's own config. That covers the endpoint, the key magpie-<agent> and the model, in the agent's own format. When the agent is disconnected, magpie puts back what the agent had before. Package internal/agent describes every supported agent: where its config lives, which fields matter and which values to offer. It also records what magpie set, so a later change made by something else shows up as drift.

Responsibilities and sources of truth

Part Responsibility Source
Agent description Agent has an id, name, icon, Bin and Dir for detection, Path, Fields and Native. It also has optional hooks: Notice, UA, ListsModels, Sync, Unwire, Join/Joined, Routed, Follow, RenameRefs, Check, LastUsed, Reached, Import/Added, Launch, SplitSuffix, Spelled and ModelAliases. Each hook's comment says which agents need it. agent.go
Fields and options A Field has Get, Set and Options. Set("") returns the field to the agent's default and takes magpie's wiring out. Quiet fields follow another field until set (Follows, such as Claude Code's tiers). An Option carries the picker's facts: Direct, Via, Same, Alias, Rate and Context. The GUI's and TUI's pickers list Agent.Picks: with the agent in settings' ownModelsHidden (the switch at the top of its model list, #1642), a field that offers catalog models (Ref) leaves out the agent's own (no Ref), but for its default and the value it is set to. The CLI still takes an own model by name. agent.go, route.go
The list of agents All lists every agent magpie knows, then the WSL agents (wslAgents). Clients lists every agent whose requests the gateway knows by name, which usage.Agents reads. One file per agent: claude.go, codex.go, opencode in agents.go, and so on. agents.go
Connect ConnectHow picks the model an agent starts on and reports how. How is one of: kept, again, joined, magpie, same, alike, default or first (#726). With no models to give, it returns NoModelsError (code no_models). applied.go
What magpie set Apply sets a field and records it in applied.json. Wired says whether magpie is in the config. Drift reports unwired, replaced, unreachable, proxied or bypassed. Reapply sets the record again. Keep accepts the config as it is now. applied.go
What came before The stash (stash.json) remembers what the config said before magpie pointed it at the gateway, so Disconnect restores it rather than guessing. stash.go
Disconnect and preview Disconnect runs Unwire, then returns each field still on magpie to its default. Last it runs Restore: Pi and its kin (piLike: Pi, OmO, Prime Agent; and MothX, its one settings.json) copy settings.json and models.json aside (*.before-magpie, beforeMagpie) before magpie's first write, and put that copy back byte for byte where what Disconnect left is the same JSON; a file that wasn't there goes again when only empty objects are left in it. DisconnectPreview runs the real Disconnect on a copy under a temporary home, in a subprocess (DryRunArg), and diffs the files. The preview is never a second account of what Disconnect does. applied.go, preview.go
Uninstall magpie uninstall and Settings › About › Uninstall magpie take magpie off this computer, because deleting magpie's folders by hand left Codex's openai_base_url on a gateway that was gone, and every turn failed with a 502 (Jevik_AI on X). Run goes in this order. System removes the service, opening at login, the Start menu shortcut, magpie:// links and the privacy model's helper. Agents ends Codex's account failover, runs each connected agent's Disconnect, or its offline disconnect for a closed app, so the restore keeps what the user changed by hand since. It then ports Codex's rollouts and restarts the Codex app's app-server. Data deletes magpie's folders, but keeps the Library while it holds skills, servers or hooks. The executable stays where the user put it. The CLI refuses while another magpie runs, and asks first unless given --yes. The app runs System and Agents from POST /api/uninstall. If anything failed, nothing else is removed. Otherwise POST /api/uninstall/finish starts a detached magpie uninstall --data-after <pid>, which deletes the files once the app has quit, since WebView2 holds its folder open until then. magpie web refuses both routes (TestUninstall*, uninstall-settings.test.cjs). Every line magpie writes into a TOML, YAML or env config has a # magpie: note above it saying how to undo it, so a config left behind still names magpie (edit.Mark, TestMarkedLinesEveryAgent). uninstall.go, uninstall_cli.go, gui/uninstall.go
Keeping configs current Reseat moves agents off a model magpie no longer serves (#200). OnGateway and Rewire write the new gateway address into every connected agent when the port changes. Source and Stale say what an unconnected agent runs on, and whether running copies still use the old list. reseat.go, rewire.go, connectinfo.go
Restarting a desktop app Claude Desktop and WorkBuddy (WorkBuddy AI on macOS) read magpie's settings only as they start (微雨南山 and stones on Discord). AppBehind names one running here that started more than a second before magpie last changed what it reads (changedAt, which puts a change no file's time shows, such as Claude Desktop's gateway model list, at when it is first seen); only for an agent connected in magpie or disconnected in it. The row's Restart asks first in magpie's own dialog (confirmRestart), then POST /api/agents/restart/{id} runs RestartApp. On macOS (restartApps, the bundle found by id under appFolders, its CFBundleExecutable matched in pgrep) it quits as ⌘Q does and waits for every process of the bundle (reopenBundle); one still open after appQuitWait (a "Save?" question) is left as it is and not opened again (noticeRestartStillOpen). On Windows (claude.exe under AnthropicClaude or its Store package, WorkBuddy.exe outside the WorkBuddy AI folder) its processes are asked to close (taskkill without /F); one that has hidden every window and still runs after appTrayGrace (1s) is in the tray and has its tree ended at once (waitClosed, winShown: Claude Desktop hides its window in ~0.6s and keeps all its processes, so waiting the whole appCloseWait made a Restart ~12s where quitting by hand takes ~2s, CyberCaius on Discord, 10-29); one still showing a window (a question) gets appCloseWait before it is ended, and it is opened again through its Store id or Squirrel's stub. The Codex app's own Restart (ReopenCodexApp) asks first too, then ends only the app-server that app runs for itself (provider.RestartCodexApp: under its bundle, never a --listen one), as a switch does; the app starts another and keeps its window. Quitting and opening it, as before, opened a new window (yoshi037070 on Discord, 10-27). Codex on Windows, WorkBuddy AI on Windows and Linux aren't restarted: their process names aren't known. apprestart.go, apprestart_windows.go, connectinfo.go
Codex background compaction Long conversations' Codex background compaction, in Codex's opened row on the Agents page (CodexAsyncCompact, CodexAsyncCompactPercent, #2490) writes [features.async_compaction] enabled = true and model_async_compact_threshold_percent (Codex 0.163 reads it only in that table) into each Codex config magpie routes, on every Sync. The table is written only when every Codex that reads the config is 0.163.0-alpha.8 or later (codexReaders: the CLI on PATH, the Mac app's bundled codex-cli/codex-package.json, the Windows Store app and an editor's openai.chatgpt extension, whose versions aren't known, a WSL distro's CLI): an older Codex takes every unknown [features] entry for a bool and won't load a config with the table ("invalid type: map, expected a boolean"). Otherwise, or with no Codex found, magpie writes the bare [features] async_compaction = true, which every Codex loads, and no threshold; a table magpie wrote before is taken out on the next Sync, and Settings' row names the Codex that held it (CodexAsyncHeld). Codex starts a background compaction only on a provider whose capabilities.remote_compaction is "v2", which it gives OpenAI and Azure alone, so [model_providers.magpie] gets capabilities = { remote_compaction = "v2" } too, also when the user turned the feature on by hand (#2493); putProvider carries the table's capabilities over when it writes it again. What magpie wrote is in the stash under codex.async: a value the user set, or changed since, is never written over and stays when the switch goes off; a bare async_compaction = true the stash doesn't name as magpie's (bool), an inline or dotted table is the user's as written. codex_async.go
Codex windows Each magpie model's entry in Codex's catalog (codexcat.entriesAt, and listedEntry for a relay's own entry) says the model's whole window as context_window, which Codex shows (95% of it) as the conversation's context. Where Codex compacts goes in the entry's auto_compact_token_limit: the threshold set on the model or its provider, else Long conversations' (settings.Working, 272K by default), only when that is below the window; Full window writes none. Codex 0.165 compacts at the lesser of it and 90% of the window, and a model_auto_compact_token_limit the user put in config.toml comes before it. Until 10-30 the threshold went in context_window with the window as max_context_window, so a 1M model showed 258K in Codex (01huadalang on Discord); max_context_window stays a field magpie owns so Keep doesn't carry an old catalog's over. Codex's own models (codex/) keep their entry's window. Tag carries catalogFormat, so a Codex holding a list in the old shape asks again. TestCodexCatalogCompactAt, TestCodexWindowShownCompactApart. codexcat.go
Named omp profiles omp keeps a profile's settings under ~/.omp/profiles/<name> (or under PI_CONFIG_DIR), each with its own config.yml and models.yml. Every such profile is an agent of its own — omp#<name> on Windows, omp#<name>@wsl:<distro> in a distro — so each can be connected, drifted and disconnected on its own. They share omp's model lists (ListsFor), and the default omp row is the folder ompDir/ompIn already pick, so an OMP_PROFILE that row is already pointed at is not listed twice. A name omp refuses is not a row: default, a trailing dot, or a Windows reserved device name (aux, nul, com1, lpt9.x, con.work), on every platform (ompProfileOK). A distro's profile names come from its probe and are kept in wsl.json; a stopped distro is never started to list them, its profile rows showing what was last seen (asleep). omp.go, wsl.go
WSL twins On Windows each running distro is probed once, without starting a stopped one. The wslKinds agents found there become agents of their own, <id>@wsl:<distro>, edited through \\wsl.localhost\<distro>. A kind is found by its folder under the distro's home or by its command there (not one on a Windows drive). Where another tool shares one of them, the kind leaves it out: Gemini CLI is found by its command alone, because Antigravity keeps ~/.gemini too. Antigravity CLI is found by its own ~/.gemini/antigravity-cli or its agy command (mimi001234 on Discord). Goose is found by its folder alone, because a goose command can be pressly's migration tool. Reasonix also needs the version its command gives (accept), because the old npm client is named reasonix too. The gateway address and key follow the distro's networking: mirrored or NAT (place, keyAt). Under NAT the key is the gateway's WSL key (gateway.WSLKey, -<agent> after it where the agent's key names it), sharing on or off; the gateway listens at that address itself (gateway-routing's WSL under NAT). ListsFor keeps a twin's model picks under the Windows twin's id (#927). wsl.go, gatewaykey.go
Settings tuned from use Usage › Context's "Tuned for you" advises, per agent, the settings that would have spent the fewest tokens on the user's own calls of the range, and puts one in on a click. Package tune replays the calls sessions.Calls reads from the agents' session files under each candidate value (Compact, CacheTTL); tuneOf picks the agents and models (Claude Code per model, Codex pooled). TuneRead, TuneApply and TuneUndo know where each setting lives: Claude Code's modelSettings.<model>.autoCompactWindow (where its /autocompact saves), promptCacheTtl and subagentPromptCacheTtl in ~/.claude/settings.json. Where Codex compacts, and Claude Code wherever magpie's own window is what it runs at, is one value with Long conversations in the agents' settings sheet (settings.CompactAt/FullContext, source long; 7eleven on Discord): the card reads it, Use sets it through provider.SetCompactAt, and Sync writes it into each agent's config as it does for the sheet; the note says it is Long conversations, shared by Codex and Claude Code (compact-one-value.test.cjs). The advice is weighed by tokens alone: it is labelled "Fewest tokens", and a compaction window it would change says it doesn't measure how well the agent keeps the task after a compaction, and that a lower window compacts more often (#1854, context-tune.test.cjs). A compaction row's "Other window…" opens the app menu with every value of the curve, each with its estimated extra tokens over the fewest and about how many compactions it would have made (Point.compacts, from the same replay), and puts the one picked in like Use (#1860). An agent whose files time its compactions also has their wait weighed (HirotaNagai on X): Claude Code's compact_boundary line says compactMetadata.durationMs, which sessions puts on the first call after it, and Codex compacts by a call of its own (the record a compacted line names, in rollouts since 2026-09), whose time is the compaction's (Call.Compact; an older rollout's compaction has no call and stays untimed). With 3 or more timed for a model (minTimed), Facts.took is their median seconds, each window says its wait (Point.wait, its compactions × took), and the row says what a compaction took, the wait at the advice against the window now, and the cheaper window the advice passed over for waiting longer (Compaction.cheapest, wait_cheapest) when it saves 3% or more; the advice is labelled "Tokens + wait", its caveat says tokens and waiting only, and the picker says each window's wait with "Fewest tokens" on the cheapest (context-tune.test.cjs). An agent or model with fewer timed reads and is advised as before. internal/tune, tune.go, internal/gui/tune.go
Agents a plugin adds A plugin's magpie.agent module (or a *.agent.js file) says where an agent magpie has no setup of its own keeps its model (config, format, model, prefix), and its connect returns the other keys to write. One with no model is connect only (#2374): its one field is provider, magpie or nothing, as an app whose one setting is magpie as its provider; connect is called without a model, must return keys, and is called again on a catalog change (Sync); ListsModels is set, so its list is the models picked for it. agentplug compiles each in moejs (via jsmod, as gateway middleware is), reloads it when plugins.json or the file changes, and keeps why one didn't load. plugged makes each an Agent with Plugin set, listed after magpie's own; an id one of magpie's own agents has is refused (PluginErrors). connect is given each model as magpieModels builds it, with /v1/models' native_endpoints (provider.NativeEndpoints, carried as catalog.Model.Endpoints) and pricing (catalog.OpenRouterPricing of the same EntryPricer price), each left out when not known (plugged_connect_facts_test.go). agentplug.go, plugged.go
Environment-only agents Agents that read the gateway only from the environment get a Launch command. Antigravity CLI (agy) also gets a function agy in each shell's profile while it is on one of magpie's models, so typing agy in a new terminal starts it on magpie (bestony on Discord). The function runs magpie agy run, which starts the agy on PATH with GEMINI_API_KEY, GOOGLE_GEMINI_BASE_URL and --model (no --model when the user gives one) while settings.json's model is still magpie's, and unchanged otherwise. PowerShell's asks magpie agy env for them, since the Windows app is a GUI program PowerShell doesn't wait for. Typed says the function is there; the row then says plain agy works in a new terminal, and the Launch command is for a terminal open before. agy has no settings-only route: 1.4.7 refuses to start without GEMINI_API_KEY in the environment even with a key on the custom model. Cursor Private Inference instead gets user-level variables (cursorLocalOn, KeepCursorLocalEnv), and magpie writes none of Cursor's own files. It is found by its product.json in the apps folders, in the folder Windows' list of installed programs names (cursorLocalInstalls, any folder picked in its installer), or as its Linux AppImage (Cursor_Private_Inference-…AppImage) in the folders downloads are kept in (#1254). Its effort field is kept in magpie (provider.AgentEffort) and asked by the gateway, its levels those of the models it lists (cursorLocalEfforts, #1003). cursorlocal.go
Claude Science Its daemon (claude-science) reads the API's address only from its environment's ANTHROPIC_BASE_URL and has no setting for it. Connect restarts the daemon with that variable set to the gateway (scienceOn: stop, then serve --detached --no-browser on the port status said it was on) and notes the daemon in claude-science.json (url, pid, port); Disconnect restarts it without the variable, one in magpie's own environment taken out too. No variable is set for the user and no file of the app's is written. Setting it again while magpie's daemon runs on this gateway does nothing (Pick sets the field after connect). KeepClaudeScience starts it again on the gateway, on its port, when it isn't running (a restart of the computer), each minute while magpie serves; it never stops one running. Check reads the daemon's operon.lock, not status (seconds for a 130 MB Bun program), and calls a daemon with another pid drift: the app's window, opened while none ran, starts its own without the variable. It is found in the Mac app's bundle (Claude Science.app/Contents/Resources/bin), %LOCALAPPDATA%\Programs\ClaudeScience on Windows, ~/.local/bin, else on PATH. The app still needs its own Claude sign-in; the gateway never passes it on (see gateway-routing). claudescience.go, science.go

Runtime path

  1. Connect. The Agents page's switch calls ConnectHow (POST /api/agents/{action}/{id} in internal/gui/api.go). It stashes the current values (<id>.connect.was). It brings back the models used before a switch-off (reconnect), or calls Join where the agent keeps its own model (Codex signed in with ChatGPT). reconnect calls Join first too, so a Codex switched off on a routing group comes back joined, as the switch first connected it: put back on the group alone it was beside its sign-in only, and an own model picked on the Agents page took it off magpie (NancyTom18 on X, TestCodexReconnectStaysJoined). Otherwise it picks a model by the order ConnectHow documents and sets it through Apply.
  2. Pick. Pick sets a field from the model picker. Picking one of magpie's models on an agent that isn't connected connects it first. Each row of a model picker that a provider served with a timed reply this week says how fast: tokens a second, or the first token's wait when only that was timed (speedTag in app.js, from GET /api/model-speeds, modelSpeeds in internal/gui/speeds.go: the usage ledger's mean TTFT and decode speed by provider/model, the catalog ref an option carries). Under a search, rows that match equally go fastest first by about how long a 200-token reply takes (speedRank), the untimed last, so a model several providers serve lists the fastest one first (axuhere on X). Without a search the rows keep catalog order, grouped by provider. A routing group that always asks the fastest provider is the Speed first strategy (gateway routing).
  3. Notice. After a change the page shows Notice when the agent reads its config only at start-up and needs a restart. A field that is Live (Field.Live: magpie's own setting, which the gateway reads on each request, Claude Desktop's subagent_model and subagent_effort) needs no restart, so POST /api/set and magpie <agent> <field> <value> leave the Notice out after it, unless the pick connected the agent too (Pick on an agent not connected). A stopped WSL distro's copy of a field keeps the flag (asleep).
  4. Drift. As the Agents page is drawn, Drift compares the config with applied.json. It runs Check first, then each field. An agent pointed at magpie through a reverse proxy is still on magpie (#1985, davisjiahao: a company's nginx at https://ai.corp.example/magpie). wiringOff, where most agents' Check compares a URL, and the checks of their own (Claude Code's managed settings, Reasonix's provider) take a URL that isn't magpie's when it ends with magpie's path, the rest is an http or https address on another machine (onAnotherMachine) or one on this machine's loopback with a path of its own (loopbackWithPath: the reporter's compliance proxy at http://127.0.0.1:8788/claude-code-anthropic/<route>; proxyBase), and GET <rest>/ there answers as the gateway's own GET / does ({"name":"magpie"}, magpieAt in reach.go, tried in the background like reachProbe). Something else there (a relay CC Switch put in) is unwired, as is an address on this machine's loopback without a path, which is magpie's on an older port and is never tried. Until the answer is known it isn't drift, so Reconnect isn't offered and doesn't write the proxy away; port moves (OnGateway, Rewire) re-set only unwired agents, so they leave it too. Codex keeps such an address by magpie's key, as for #816 (codexKeptGateway: http or https, any port, a path before magpie's, loopback with a path). A model picked in Claude Code keeps it too once magpie has answered there (surelyMagpie; routed and gwAt in claude.go), so a proxy every request must go through isn't bypassed; before that, or at a relay, a pick points Claude Code at this magpie. Tests stub magpieAt in TestMain as known and not magpie. When the config is right and points at an address off loopback (a WSL twin under NAT, or this machine's Codex at an address the user kept, #816), it tries that address (reach.go): in the background, at most every 20 s, never waited for. When nothing answers there while the gateway answers on loopback, the drift is unreachable (#1013), with what has to listen there: Share on local network, the user's portproxy, Windows' firewall. Then it checks whether the agent's latest use (LastUsed, Reached) reached the gateway: a request Codex's log says went to the host its config keeps magpie at, or one the gateway saw from it after (lastSeen), reached it.
  5. Disconnect. Disconnect puts back what the stash kept and forgets the record. It also marks the agent disconnected (<id>.disconnected in the stash, Disconnected) until the user connects it again (connect, or an Apply that leaves it wired): nothing magpie does by itself puts magpie back in meanwhile, neither a start's Sync nor Codex's account failover nor #701's magpie API wiring (paynezhuang on Discord: Codex had openai_base_url back after every update). A Codex thread keeps the provider it was started on, so one started while magpie was Codex's provider (its API, or the takeover of a used-up account) still sends to /v1 after Disconnect or a switch back to ChatGPT. One of Codex's own models asked there that no account in magpie serves (an OpenAI model of Codex's models cache or the catalog), from Codex on this computer with no held gateway key, goes on Codex's own ChatGPT sign-in through codexBackend, magpie's key and x-openai-actor-authorization left behind (codexOwnOffMagpie in codex_own_v1.go); it was answered 404 "magpie knows no model" (iuengei on Discord). With the sign-in out of reach (subscription accounts off, signed out, expired) the 404 says why and to start a new thread. TestCodexOwnModelOnMagpieThreadGoesOnSignIn, TestCodexOwnModelOnMagpieThreadStaysHere, TestCodexOwnModelOnMagpieThreadSaysWhy.

Constraints and failure behavior

  • magpie only removes what it wrote. Anything else in an agent's config stays as it was.
  • agy's shell function (update.ShellFunction, shellfn.go) sits between # >>> magpie agy >>> and # <<< magpie agy <<<, the only lines magpie writes or takes out of a profile. The profiles are those cliProfile names (zsh's in ZDOTDIR when set, bash's, fish's config.fish), plus PowerShell 7's and Windows PowerShell's on Windows when their execution policy runs a profile. A missing profile is made only for the shell a terminal opens. Only a file inside the home is written, writes go through temp-and-rename, and a profile that can't be read is left alone. Picking one of magpie's models and every Sync on one put it there, which covers users wired before it existed. Stepping out and a Sync off magpie take it out. agy in a WSL distro gets the function in the distro's own profiles (agyDistroProfiles in agy.go, through update.ShellFunctionAt): ~/.bashrc, ~/.zshrc and ~/.config/fish/config.fish where each is, and the profile of the login shell the distro's /etc/passwd names (bash when it names none) made where it isn't. The distro's ZDOTDIR and XDG_CONFIG_HOME aren't read. No magpie runs there, so the function (agyDistroFunction) reads settings.json's model with sed and carries the gateway's address as the distro reaches it (place.gw, Windows' under NAT) and the key it takes from there (agentKeyAt, the WSL key under NAT). Sync writes it again, so an address WSL changed on a restart follows, and until then Check reports a function naming another address. A user's own alias agy still wins over it. A terminal opened before the change still needs the Launch command.
  • A sync brings magpie's models up to date, not where the agent reaches magpie. Every Sync that SyncCatalog runs (each start and update of magpie, a provider added, and a plugin signed in to, out of or renewed, or listing other models than the last time: plugin.OnChange and plugin.OnListed call catalog.Touched, #2373) goes through synced, which passes each file written through kept.away (edit.Filtered, keptaway.go). The filter sees every file written through edit while it is on, from any goroutine and under whatever lock the writer holds, so it takes none a writer may hold: the gateway's address and the LAN key are read before it is on (keeping), and magpie's own files (magpieFile: its folder as named or where its links lead, such as a ~/.config linked into a dotfiles repo) are left as they are (ylorn on Discord: settings.Save under the settings' lock reached a filter that read the settings, and the app hung ~10s after every start; TestOwnWritesDuringASyncWithALinkedConfig). In a file without the gateway's own address, whose magpie the user pointed at an address on another machine (a NAS's, or this machine's LAN address), and with no address a WSL distro was seen at, that address stays in place of gateway.URL(), with the path before magpie's every URL at it had (awayPath: a reverse proxy's /magpie; on loopback, a local proxy's route where magpie answered or hasn't been asked), and so does the key that went with it in place of magpie's own (coeo91 on Discord: the base URL went back to 127.0.0.1 after an update or restart). An address on this machine's loopback follows the gateway; with more than one address or key gone, the write is left as it is. Picking a model in magpie still points the agent at this magpie, but for Claude Code at a proxy to it (above). ZCode and WorkBuddy keep such an address in their own writers too (zcodeAddress, buddyWriteAt).
  • SyncCatalog holds the catalog it builds (provider.Hold), the plugins' providers and sign-ins among it, for up to a second. Those catalog.Touched drops are told in the background, so a plugin change also drops what is held at once (plugin.OnChangeNow, hold.go): the host's "auth" event is read before its reply to the sign-in that saved it, and a look at the accounts once the sign-in returns sees it (#2449: magpie plugin login found no account while a sync ran; TestHeldGoesWithAPluginChange).
  • JetBrains Air's magpie-opencode.json keeps user-added fields in provider.magpie, including nested options, on sync and model picks (air in air.go, using theirsKept in sync.go). The gateway fields and complete model list are still replaced, so removed models leave the list.
  • In every OpenCode-shaped config (OpenCode, DevEco, Air, OpenChamber; openCodeKept in agents.go), a variant the user put on one of magpie's models stays through a sync, and so does one they wrote over under a name of magpie's. A variant exactly as magpie writes it under its name (openCodeVariant) is magpie's, so one the model no longer has goes (#2379, TestOpenCodeCodexFastVariants).
  • magpie's OpenCode provider goes under provider (OpenCode 1's key), not OpenCode 2's native providers, on purpose. OpenCode 2 reads provider and turns it into its own shape in memory without rewriting the file (migrateProviders in packages/core/src/config/normalize.ts at v2.2.0; its "Migrate from V1" page calls the V1 format supported and converting optional), while OpenCode 1 ignores providers (ConfigV2Compat.lower in packages/opencode/src/config/v2-compat.ts at v1.19.5, npm's latest), and both read the same opencode.json. A native entry is a different shape too (package, settings.baseURL, variants as an array). Checked on 10-29 against a fake server: 2.2.0 listed and used magpie's provider entry (#high-fast sent reasoning_effort high and service_tier priority), and 1.19.5 with the entry under providers had no magpie models. OpenCode 2 logs one WARN for each model marked reasoning, which only OpenCode 1 reads.
  • OpenCode has no /fast. A ChatGPT account's own gpt-* model, not a routing group (catalog.Model.CodexFast, set in magpieModels), gets each reasoning level again as <level>-fast (or fast alone with no levels), asking service_tier: "priority" as Codex's /fast does. The tier is written twice: as an option, which OpenCode 1's @ai-sdk/openai-compatible sends as it is, and in extraBody, which OpenCode 2 sends while it drops an option it doesn't know (checked with OpenCode 2.0.25 against a fake server). The gateway drops OpenCode 1's stray extraBody field when it rebuilds the request as Responses for the ChatGPT backend (TestOpenCodeFastVariantReachesCodex).
  • Every sync and pick that writes magpie's own block into an agent's config lays it over what is there, so keys magpie doesn't write stay (#2030, then its siblings). Each block was checked against the app's own schema or source. magpie's parts are named; a key it no longer writes goes with them.
    • Qoder's providers.magpie keeps routing, the timeouts, type, authType, anthropic and a non-empty displayName (qoderKept).
    • fx keeps reviewer_model and a tool_choice_mode of omit. Its auth is magpie's whole, since fx refuses an env beside type: none (fxKept).
    • Hermes keeps the default_model that hermes model writes there, key_cmd, the timeouts, extra_body, a name and headers beside magpie's (hermesKept). This holds in every profile.
    • Hermes copies the launch profile's model into a new profile (_seed_model_config, or --clone's config.yaml) and never reads it again. A model picked in magpie moves every other profile still on magpie with the model magpie had set (recorded in stash.json as hermes:<path>:magpie.default, or the connected config's model before that record) onto the new one; a profile on any other model was set by its user and stays (hermesFollow in hermes.go; tjhhhh_84378 on Discord).
    • The config magpie connects is the profile hermes starts in: HERMES_HOME when it names a profile, else the one hermes profile use made sticky in <root>/active_profile (a live profile folder; hermes model writes the same one), else HERMES_HOME or the default folder (hermesActive; _apply_profile_override in Hermes's hermes_cli/main.py). The root's config is then one more profile. A bot on the model the connected config is on through magpie follows too, besides one on the recorded model (hermes model there before the bot was made).
    • Disconnect moves a profile on magpie onto its own model from when magpie connected it, else the connected config's own model (with that provider's providers entry when the profile lacks it, as Hermes's launch_model_seed does); with neither, its model goes. What it was on is kept (hermes:<path>:off), and connecting again puts it back when nothing has changed it, and gives a profile with no model at all magpie's (hermesBack). The recorded model stays through Disconnect. Before, Off emptied every such profile and hermes there failed at start after Off and On (tjhhhh on Discord, TestHermesOffAndOnKeepsEveryBotsModel, TestHermesStickyProfile).
    • With more than one profile, each profile other than the connected one has a field of its own, profile:<name> (default for the root), drawn as a line of the opened row's Other profiles with hermes -p <name> beside it, never as a square of the row's (hermesProfileFields; hermesBot in app.js; dongshanfengdongshizhcn on Discord). A magpie model puts magpie's provider into that profile and stashes its own provider and model first; a model of its own is written as model.default and gives back the stashed provider. Default puts back the profile's model from before magpie, or keeps the one it has: Disconnect sends the same empty value. A bot picked there is recorded (hermes:<path>:picked) and doesn't follow the connected config's next model, and a sync keeps magpie's provider current in a bot on magpie while the connected config isn't (TestHermesProfileModels, hermes-profiles.test.cjs).
    • Hermes's api_key may be a reference, ${VAR} or ${env:VAR}, which Hermes expands from the .env beside the config (its own or a profile's) and then the environment. Check and a sync read the key it names (hermesKey): one that holds (keyHolds) stays and isn't drift, and so does one naming a variable magpie can't see (only a shell profile sets it), which is unknown. One naming a key the gateway doesn't take is drift, and a sync keeps the reference and writes magpie's key into that .env under the variable, made 0600 when there is none (hermesKeptKey; PaulT on Discord, TestHermesWithAKeyInItsEnvFile). A value with more than the one reference in it is replaced by magpie's key, as before.
    • omp's models.yml keeps modelOverrides, discovery, disableStrictTools, headers and compat flags (ompKept). Its auth and apiKey are magpie's, or gone.
    • Kimi Code's [providers.magpie] has magpie's three keys set in place, so custom_headers, env and default_model stay (kimiProvider).
    • Cline's models.json keeps the provider's other keys, and on each model magpie lists what magpie doesn't write, such as a VS Code override (clineKept).
    • VS Code's, Insiders' and VSCodium's group in chatLanguageModels.json (each profile's too) keeps every key magpie doesn't write, such as settings["<model id>"].reasoningEffort, which VS Code writes there when the user picks an effort in Copilot Chat's model picker (setModelConfiguration); a whole rewrite on each Sync and pick sent the model at its first level (chim3744 on Discord). A model's settings stay after it leaves the catalog; the model list is magpie's (vscodeGroupKept, TestVSCodeKeepsThePickedEffort).
    • Goose's custom provider file keeps a name, timeout_seconds, toolshim, headers and the like (gooseProviderKept).
    • ZCode's provider rule keeps its name, logo, visibility, API headers and the key's management link (zcodeRules).
    • Each model magpie writes into ZCode's providerModelRules has native web search (properties.supportsNativeWebSearch, "原生联网搜索") on while the provider's format is Anthropic Messages, the only format ZCode sends it on (zcodeWebSearch). The models magpie turned it on for are kept in the stash under zcode.web_search, so a model the user unticked in ZCode (which takes the key out of the rule) stays off, a value in the rule stays, a manual rule is left alone, and a stash that can't be read turns nothing on. On another format magpie's own on is taken out. Disconnect forgets the list.
    • The YAML ones go through yamlKept and mergeKept in sync.go. Each is tested by a Test<Agent>KeepsTheUsersSettings.
  • Copilot in JetBrains IDEs keeps its Bring Your Own Key providers in the Copilot language server's byok.json, shared with Xcode's and Eclipse's Copilot (copilotJetBrains in copilotjetbrains.go). magpie writes its own three keys there, magpie-provider-config, magpie-api-key and magpie-models-config, in the bytes the server itself writes, and only when they differ; the user's providers and keys stay. A magpie model the user hid in Manage Models (isRegistered: false) stays hidden through a sync. A new file is made 0600 in a 0700 folder, as the server makes it.
  • dsh (DeepSeek Harness) sets one API per llm-pi-ai route, so magpie writes a route per protocol (dshKinds in dsh.go; 01huadalang on Discord): magpie (Chat Completions) for most models, magpie-responses (openai-responses) for a model served on Responses, magpie-anthropic (anthropic-messages, the gateway root, forceAdaptiveThinking where AdaptiveThinking or AdaptiveWithEffort, so Max reaches GLM-5.3 as max) for one served on Messages, by the model's APIs (dshRouteOf). A model's APIs is the one its provider serves it on best (Provider.Native, in magpieModels, route.go), and Pi, omp and droid read it the same way. A routing group has responses when every member is best on Responses (allResponses, #1594), so its tool-call arguments are relayed as they stream; any other group has none and stays on Chat, a Messages-only group too, as a Claude member's thinking is known by its own model. A route with no models is taken out. An api the user picked for a route in dsh's Models page is kept, and so are keys they added there. The start (agent-default-model) names its model's route, and Sync moves a start on one of magpie's routes to the route its model is now on (dshStartOnItsRoute), its effort and marks kept. Check asks the route the start names to list its model. A dsh session resumed on a model that has since moved routes asks for the model to be picked again, since dsh finds a model by route and id.
  • dsh takes a model's listed maxTokens as every request's output and reserves it, with 65536 of headroom, out of contextWindow before deciding when to compact (compaction-basic's resolveCompactSpec: the smaller of 80% of the window and window − maxTokens − 65536). A vendor's reply limit near its window had dsh compact at 41248 of a 500000 group (#2823) or fail with no budget (524288/524288, LoKi on Discord; 131072/65536), so magpie lists it held to what leaves dsh half the window to compact in (window/2 − 65536), or to a quarter of the window where that is more (every window under 262144, as VS Code and Copilot in JetBrains hold it), on every route and in the older llm-deepseek entry (dshMaxTokens). A quarter alone cut DeepSeek's 393216 on its 1000000 window to 250000 (#3298); now it keeps all of it and dsh compacts at 541248, while 500000/393216 is held to 184464 and compacts at 250000. A Max output the user set stays as they set it (outputOr), even one that leaves dsh no budget. TestDshOutputLeavesCompactionRoom.
  • While magpie serves, KeepDshWired writes the routes again every 30 seconds, since dsh writes over its patch list. A round that writes nothing is kept (dshRounds), and the next round does nothing when nothing it reads has changed since. It checks the bytes of dsh's files (every profile's cordis.patch.yml, the home layer, settings.yaml, .env, .credentials.yaml, config.yaml) and the gateway's address. It also checks provider.StampNow: no Changed, plugin change or filememo.Forget, the same environment, and the providers', settings' and catalog's files unchanged. The models are built again when that stamp moves, and at least every dshModelsFor (5 minutes) for what no stamp sees, such as another app's account file or a date-retired model. Building the whole catalog and every route each round allocated 12 GB of a user's 35.7 GB in 48 minutes (TestDshRoundWithNothingChangedBuildsNothing, TestDshRoundAfterAChangeWritesAgain).
  • DeepSeek Harness Desktop (macOS arm64 and Windows x64; no Linux build) reads the same $DSH_HOME or ~/.dsh as the CLI, as its own profile profiles/desktop (resolveDshHome and resolveDesktopPaths in the app's lib/main.js; defaultDshHome in github.com/deepseek-ai/deepseek-harness's packages/util/home-paths/src/index.ts and apps/desktop/src/paths.ts), so it takes magpie's routes with no wiring of its own (#2279, liangjinyuan-sihan). Only that app, from deepseek-ai/deepseek-harness (bundle id com.deepseek.dsh, productName DeepSeek Harness in apps/desktop/scripts/electron-builder-config.mjs), is dsh's: the community "DeepSeek Hermes" (motongv/deepseek-hermes-desktop) v0.1.1337 took for it is not listed or written for (WuSix on Discord, TestDshOnlyTheOfficialApp). It is found by /Applications/DeepSeek Harness.app, by %LOCALAPPDATA%\Programs\DeepSeek Harness, or by the folder its current-user installer records under HKCU\Software\1bf39983-50d0-5fe0-9ef4-cece76f67c5e (InstallLocation), whose Uninstall key gives the version (registered in desktopapp.go), so a user who picked another folder is found. With the app installed but never opened there is no ~/.dsh: the row is still listed, and connecting writes profiles/desktop/cordis.patch.yml from dsh's own template (dshProfileTemplate) with magpie's routes, which the app keeps on its first start, since it writes only the files that are missing. The notice says the app starts on it the first time it opens (noticeDsh5). Disconnect before that first start removes the profile magpie made when nothing else is in it (dshTidyUnopened); once the app has opened it, the profile stays and only magpie's entries go (TestDshDesktopNeverOpened, TestDshDesktopRegisteredFolder; the registry as 0.2.1-rc.2's installer writes it, TestDshWindowsAsTheInstallerRegistersIt).
  • Ante's catalog.json keeps user-added fields in providers.magpie the same way (ante in ante.go); its auth, http_headers, extra_body and stream_idle_timeout_secs are what a gateway shared on the local network or reached from WSL needs to send a key. Ante starts a session on the provider and model of settings.json, not on what its catalog holds (#1210), so magpie sets that pair and puts back what it found there; a pick the user makes in Ante while magpie is wired is theirs and stands.
  • AstrBot keeps its providers in data/cmd_config.json under its root ($ASTRBOT_ROOT, else ~/.astrbot, the desktop app's, else ~/astrbot), written with a UTF-8 BOM, which magpie keeps (astrbot in astrbot.go). magpie adds a magpie entry to provider_sources and one magpie/<model> entry per model to provider, keeps the user's own entries byte for byte and keeps what the user changes in magpie's (timeout, proxy, enable), and sets the default chat model (agent_runner.config.model.provider_id, or provider_settings.default_provider_id before the agent runner), putting back what it found there. A pick the user makes while magpie is wired is theirs and stands. The first connect copies the file to cmd_config.json.before-magpie. AstrBot reads the file only at start-up and its WebUI writes it back whole on save, so the agent's notice says to restart AstrBot before saving in the WebUI. A Docker install's root is inside its container, which magpie doesn't reach.
  • OpenClaw keeps its settings in openclaw.json (openClaw in openclaw.go), found as OpenClaw's own resolveConfigPath and resolveStateDir find it: $OPENCLAW_CONFIG_PATH, else in $OPENCLAW_STATE_DIR, else in ~/.openclaw-<profile> for a named $OPENCLAW_PROFILE, else in ~/.openclaw, ~ being $OPENCLAW_HOME when set. magpie adds the provider models.providers.magpie as OpenClaw's schema has one (zod-schema.core.ts, strict, so only keys it knows): baseUrl at the gateway's /v1, apiKey naming OpenClaw, api: openai-completions, and one model per catalog model with id, name, input (image for a model that takes images), reasoning for a model with effort levels, and contextWindow. The model OpenClaw runs on is agents.defaults.model: a string stays a string, an object gets its primary set and keeps its fallbacks, and the ref is added to agents.defaults.models as openclaw models set adds it. A non-empty agents.defaults.modelPolicy.allow with nothing of magpie's gets magpie/*. What the model was is stashed and put back on Disconnect, while magpie's is still the primary; the magpie/* and the {} entries magpie added go, and so do objects magpie made and the file if magpie made it. The user's own keys stay, in magpie's provider and in a model entry of the same id too, and a sync with nothing to change doesn't write. The file is read as JSON with comments; a JSON5 file (bare keys), which OpenClaw also reads, is left alone and Check says so. A new file is made 0600 in a 0700 folder, as OpenClaw makes its own. OpenClaw's gateway takes the change without a restart, but a chat already on a model keeps it, so the notice says to send /model default there. A per-agent model (agents.entries.*.model) and a config split with $include are left to the user.
  • jcode keeps its settings in config.toml in $JCODE_HOME, else ~/.jcode (jcode in jcode.go). magpie adds a named profile, [providers.magpie], as jcode provider add writes one: type = "openai-compatible", the gateway's /v1, an inline api_key naming jcode (jcode sends nothing else that tells it apart) and requires_api_key = true, since jcode sends no key to a loopback URL without it. Its models list has one entry per model, with context_window, input and reasoning for a model with effort levels. A reasoning_effort the user set on one stays while the model has that level. The model jcode starts on is [provider] default_provider = "magpie" and default_model. What was there is stashed and put back on Disconnect. A model of jcode's own picked while it is on magpie takes magpie out. Each key is set alone, so the user's other keys and tables stay, and the [[providers.magpie.models]] tables jcode writes when it saves the file itself are replaced by the one list. A sync with nothing to change doesn't write. Disconnect drops the profile whole, its sub-tables included. jcode reads the file when it starts, so the notice says to restart open sessions.
  • Raycast AI reads Custom Providers from ~/.config/raycast/ai/providers.yaml in the user's folder, on Mac and Windows alike (raycast in raycast.go; manual.raycast.com/ai/custom-providers). magpie adds one entry to its providers list, id: magpie, at the gateway's /v1 with an api_keys alias holding a key that names Raycast (its User-Agent isn't known), and one model per catalog model with context and all five abilities said, since Raycast assumes tools and vision off when one isn't. The list is edited as a node (EditYAMLNode), so the user's other entries, the tools block (anchors too) and comments stay. A key the user adds to magpie's entry or to one of its models (include_user_email, a description) is kept on a sync (mergeYAMLKept), and a sync with nothing to change doesn't write. Disconnect takes the entry out, the list when it was the only one, and a file left with nothing in it. Raycast watches the file, so there is no restart notice. The model is picked in Raycast, so the field is whether magpie is in its picker (ListsModels). Detected by Raycast.app on a Mac or the ~/.config/raycast folder.
  • Kiro Crew (AWS's persistent agent: KiroCrew.app, the kirocrew CLI, its Gateway on :5476) has no model setting of its own: it runs every session on a harness over ACP, chosen by agent.acp_backend in $KIROCREW_HOME/config.json (default ~/.kiro/crew; "" is kiro-cli), and dispatched members by agent.member_acp_backend (kirocrew in kirocrew.go; github.com/kirodotdev/KiroCrew v0.9.0, src/kiro_crew/ config/paths.py, config/loader.py, config/sections.py, agent_sdk/backends.py). Connecting it sets both to an agent already connected to magpie (Codex, Claude Code, OpenCode, Pi or Goose; Pi can't take dispatch, so only the first key for it), preferring the one whose ACP adapter is installed (codex-acp, claude-agent-acp, pi-acp; looked for, never installed, and named in the notice when missing). When agent.acp_backend already names one of those five and that agent is installed but not connected, connecting Kiro Crew connects that agent too, in the same action, and runs Crew on it (wuping9525 on Windows: Crew on Claude Code, Claude Code not connected); the stash's kirocrew.joined records it, and Kiro Crew's Disconnect disconnects it again, unless the user disconnected it themselves since (kiroCrewUserLeft in Agent.Disconnect), and a disconnect the user had made before stays theirs. Otherwise, with none connected it refuses and says which to connect. On Windows the app is found by ~\.kirocrew-app\.venv\Scripts\kirocrew.exe and an adapter also by npm's .cmd/.exe shim names. config.local.json is merged over config.json and wins, so a harness set there is the user's: magpie neither writes nor reads past it, and the row says so. The previous values are stashed and put back on Disconnect, only while each key still holds what magpie wrote; a file magpie made is removed when it is left empty. The row reads as connected only while the harness it names is still wired to magpie. Open sessions keep their harness; new ones take it.
  • OpenPencil (ZSeven-W/openpencil, the openpencil-desktop app) keeps the builtin agents its chat runs on in settings.json in Rust's dirs::config_dir() joined with openpencil: ~/Library/Application Support/openpencil on a Mac, $XDG_CONFIG_HOME or ~/.config on Linux, %APPDATA% on Windows (openPencil in openpencil.go; its settings_io.rs and settings_payload.rs). magpie adds one entry to builtin_agents, id: magpie, kind: openai-compat at the gateway's /v1 with a key naming OpenPencil (its User-Agent isn't known), preset: custom, the picked models as OpenPencil writes a list: the first as model, models only for two or more, at most 64 (v0.8.4 reads model alone). The user's other entries and settings stay, and so do the display_name and enabled they give magpie's entry; a sync with nothing to change doesn't write. OpenPencil needs "version": 1 (a file without it is set aside as corrupt and saving stops), so magpie writes it in a file it makes and leaves a file with any other version, or none, alone. Disconnect takes the entry out, and the file when only the version and an empty list are left. OpenPencil reads the file once at start and writes it back whole when it quits, so a change is refused while openpencil-desktop runs (Windows can't be asked, so the notice says to quit it first). The model is picked in OpenPencil's chat, so the field is whether magpie is in its picker (ListsModels). Detected by its settings folder, ~/.openpencil (its CLI's), OpenPencil.app (com.zseven-w.openpencil), or %ProgramFiles%\OpenPencil. open-pencil/open-pencil, the other app of the name, keeps its providers in its webview's localStorage, so it is not a row: it reaches magpie through Pi or an ACP agent magpie wires.
  • NewMax (newmax.cc, an Electron app on the Claude Agent SDK) keeps its settings as JSON in the row app of the settings table of newmax.db, a SQLite database in WAL mode in $NEWMAX_USER_DATA_DIR, else ~/.newmax on every system (newMax in newmax.go; its main bundle's configureAppDataPaths, loadPersistedAppSettings and the renderer's mergeProviders, v1.1.22). magpie adds one entry to providers in the shape NewMax's own import writes, id: magpie-gateway (its own preset is magpie, its import's ids hold %3A), apiFormat: anthropic at the gateway's root (NewMax appends /v1/messages) with ANTHROPIC_AUTH_TOKEN and a key naming NewMax, at most 20 models (MAX_MODELS) as models and enabledModels with their context windows, and its id at the end of providerOrder. The row is edited in place in one immediate transaction, so every other byte stays; the user's name and enabled for magpie's entry and the fields NewMax adds to it stay through a sync, and a sync with nothing to change doesn't write. A row that isn't a JSON object, or whose providers or providerOrder isn't a list, is left alone. With no row (NewMax at its defaults), magpie writes one with its entry alone, as NewMax lays its defaults and presets under the row; with no database yet, it asks to open NewMax once. Disconnect takes the entry and the id out, sets a pick of it back to default, and takes the row out when only what magpie made is left. NewMax holds its settings in memory and writes the whole row back whenever one changes, so a change is refused while NewMax (newmax on Linux) runs (Windows can't be asked, so the notice says to quit it first). The model is picked in NewMax's model picker, so the field is whether magpie is in it (ListsModels). Detected by its data folder or NewMax.app (cc.newmax.desktop).
  • DevEco Code (Huawei's OpenCode fork, #1885) is wired as OpenCode is (deveco in agents.go): magpie's provider goes into the first of deveco.jsonc, deveco.json and config.json in ~/.config/deveco (the one DevEco merges last, so the one that wins), or in $DEVECO_CONFIG_DIR when that is absolute, read after them. 0.2.3 sends deveco/0.2.3 ai-sdk/… to a provider of its config, but much of the OpenCode code it keeps still sends OpenCode's own User-Agent (opencode/<version>), so its provider's key is magpie-deveco (openCodeKeyAt), not the plain magpie OpenCode and MiMo Code send, and Check asks for that key. Its npm package has no Linux binary, so no install command is offered there (cliSpec.only).
  • Grok Build keeps magpie's models as one [model."magpie/<provider>/<model>"] table each in config.toml under $GROK_HOME, else ~/.grok (grok in grok.go), each on the gateway's /v1 with magpie's key. Grok Build takes api_backend per model table, "chat_completions" (its default), "responses" or "messages" (Anthropic Messages), and sends each to base_url joined with /chat/completions, /responses or /messages (the "Supported API Backends" page bundled in its binary; grok 1.0.67). magpie writes each model's native API (grokBackend, from catalog.Model.APIs as Pi, droid and dsh pick theirs; uk.jent on Discord), so the gateway relays the request as it is: Responses for a model served best there, Messages for a Claude on an Anthropic endpoint, Chat for the rest, a group whose members differ, or one not known. Each table's context_window "drives auto-compact timing" (Grok Build's config reference), so it is where Long conversations has Codex compact (grokWindow, codexcat's rule): a threshold set on the model or its provider, else settings.Working of the model's window, the whole window under Full window; Long conversations is in Grok Build's sheet on the Agents page (AGENT_PREFS). A context_window the user set in one of magpie's tables by hand stays through a sync and a new pick (uk.jent on Discord: dozens of 1M models set to 300K one by one): what magpie last gave each model is stashed (grok:<path>:windows), and a value other than it is the user's (grokOwnWindow). With no record yet (a config an older magpie wrote, which gave every model its whole window), a value other than the model's whole window and other than magpie's now is taken for the user's. Disconnect drops the record with the tables. TestGrokKeepsAWindowSetByHand, TestGrokKeepsAWindowSetBeforeTheRecord, TestGrokWindowFollowsLongConversations.
  • Grok App (RongleCat/grok-app, a desktop front end that starts Grok Build over ACP) keeps its provider channels in agent-home/config.toml under its data folder: $GROK_APP_HOME, else where its directories crate puts it, or its ~/.grok-app fallback when that is the one there (grokApp in grokapp.go). Its composer lists only Grok Build's official catalog, never the [model."magpie/…"] tables of Grok Build's row, so magpie adds itself as a channel, [model.magpie], with the keys the App's Providers page writes: the gateway's /v1, a key naming Grok App, api_backend = "chat_completions", app_provider_mode = "generic", and app_models, a JSON list of magpie's models with contextWindow, supportsVision and their effort levels (no none; a default the user marks in the App stays, else medium). The picked model's context_window (a bare integer) and supports_reasoning_effort (a bare bool, Grok Build's gate for --reasoning-effort) are on the channel, as the App puts them there when a model is picked in its composer. [models] default is the route, and magpie does not set it: setting it to "magpie" makes the App drop its own sign-in (ensure_independent_for_custom_route). The route stays whatever the App had. Pressing Use on magpie under Accounts is what switches it. A magpie that already set the route puts the old one back once, on the next sync or connect (grokAppReleased); a Use after that stays. Disconnect drops only the channel, and puts the route back only when it is still "magpie": the one stashed at connect, else the one connect.was holds. One of the App's own routes picked in magpie's model field is written as the route and takes magpie's channel out, as picking another provider does elsewhere. A sync with no channel and a route other than "magpie" writes nothing, magpie's stash included, and Check says so when the route is "magpie" with the channel gone. A model picked in the App's composer since is the user's and stays through a sync, and a sync with nothing to change doesn't write. Shared mode keeps GROK_HOME at ~/.grok (Grok Build's library row). Independent mode, which Use turns on, reads agent-home: the Library writes AGENTS.md, [mcp_servers] in the same config.toml, and skills/ there, and Grok App also reads ~/.agents/skills. RTK has no Grok hook, so the Library lists Grok App with the switch off. The notice, while the App runs, says magpie is a custom provider in Settings › Account, a chat can pick its models in the model picker, and the App stays on its current route until Use.
  • JSON/JSONC config edits and their previews reject malformed input rather than editing a partially parsed document. Object edits and VS Code's model-group array edits leave the original file untouched on a parse error; valid comments and trailing commas remain supported (internal/edit). An edit's result is checked as the apps read JSONC (edit.ValidJSONC: jsonc-parser with allowTrailingComma, as OpenCode, VS Code and Zed parse; a trailing comma after a value is fine, one with nothing before it, {,} or },,, is not), and an edit that would turn a file the app reads into one it can't is refused, nothing written (checkJSONC). A delete takes the last member's own trailing comma with it, an insert into an object of comments only adds no comma, and a lone comma an older magpie left ("mcp": {,} after the hub was toggled for OpenCode, chenxiang0010 on Discord) is dropped by the next edit of that file (dropLoneCommas).
  • A config that starts with a UTF-8 byte order mark (a Windows settings.json or config.toml saved by PowerShell, Notepad or a channel switcher, #1534) is read without it (edit.Read), and a write keeps it (keepBOM in WriteAtomic): the user's file keeps the encoding it was saved in. That covers every format internal/edit writes (JSON/JSONC and its arrays, TOML, YAML, env); Codex reads a TOML file through a BOM too, so magpie no longer refuses one. A file read some other way trims it with edit.TrimBOM (the Claude Code and CC Switch imports). A line an edit takes out of a CRLF file goes with its \r\n.
  • Codex's model picker tags each of its own models by where a pick on the Agents page sends it: via magpie while routed, joined, or failing over, and direct while it is only beside its sign-in on one of magpie's models (beside, not joined, failover off), where such a pick takes magpie out (#940) and the GUI asks first (TestCodexBesideOwnModelsSayDirect).
  • A line magpie writes into an agent's TOML, YAML or dotenv config gets a comment line of its own just above it, # magpie: <what it is>; <how to undo it> (edit.Mark, set to agent.lineNote by the CLI's run in mark.go; the edit side in internal/edit/mark.go). Jevik_AI on X deleted magpie's folders by hand, and Codex's config.toml kept openai_base_url on the gateway with nothing in it naming magpie: every turn was a 502. Only a one-line scalar that points at the gateway or names magpie's model list gets one, and only when the write adds or changes that line, or it had a note already; a line of the user's own that magpie leaves as it is gets none. The note is never on the value's line: Grok App's providers.rs reads the rest of a line as the value. Every write takes the notes out first and puts them back over the lines that still need one, so a note goes with its line and a Disconnect leaves none. A YAML note that would change what the file reads as isn't added (sameYAMLValue). JSON has no comments and gets none. Tests set no Mark, so their exact bytes stay; TestMarkedLinesEveryAgent connects every agent with notes on and checks each gateway line has one, a second sync writes nothing, and Disconnect leaves none; TestCodexMarkedLines, internal/edit's TestMark*.
  • Codex signed in to ChatGPT stays beside its sign-in (openai_base_url) unless the user picks magpie API. magpie becomes its provider only while the Codex app holds the active account, which it sends nothing for: /wham/usage says it isn't allowed, and it has no credits and isn't a workspace still within its overage (codexHeld, read by provider.CodexUsedUp). With Codex switched off or removed in magpie (leftAlone), whose allowance magpie otherwise reads nothing of, the active account is still read for this alone while Codex takes magpie's models beside its sign-in or magpie is its provider for the held account (Agent.HoldMatters, through the provider.CodexHoldMatters hook; codexHoldReading): once a minute at most, with the token as Codex keeps it, never renewed or written (codexTokenAsKept), and nothing shown on the Usage page. Before, turning Codex off in magpie after its allowance ran out left the Codex app greying Send for magpie's models through restarts, and one already moved was put back on the held account (sherlock_23333 on X; TestCodexHoldReadLeftAlone, TestCodexHoldMatters). Where the app goes by what usage can't show (an experiment's gate, a reserve, a Team plan's overage under the reserve experiment), it counts as held: a wrong move costs ChatGPT extras, a missed one every turn. A saved reading kept through a failed read stops saying held once its used-up window has started again; a hold with no window used up stays till a fresh read. The app then loses its ChatGPT state (durable threads, remote control), so a window at 100% alone, which credits get past, doesn't move it (codex.out marks the move, and Sync undoes it once the account has room). The same holds on one of Codex's own models joined beside the sign-in (MasterYi on Discord: the Codex app greyed Send for every model on a used-up account): Sync makes magpie the provider on that model as magpie serves it (codexOwnViaMagpie, codex/<model>), keeps the model picked in codex.out_own, and once the account has room puts Codex back joined on it; a model the user picked meanwhile stays theirs. With no ChatGPT account in magpie to serve it, Codex is left as it is (TestCodexOwnModelGoesThroughMagpieWhileUsedUp, TestCodexOwnModelKeptOnChatGPT). The account is read again at once when a reply says it may be out (a usage_limit_reached rest, or an x-codex-* window heard at 100%; provider.CodexMayBeUsedUp, at most every 20s, the active account only), not only on the five-minute look. A turn relayed to Codex's own sign-in, the one account on (codexUpstreamOn with no account, the gateway's codexRelayedAccount), is heard the same way: its x-codex-* windows and codex.rate_limits event kept as the sign-in's usage (heardCodexLimits), and a usage_limit_reached refusal reading it again. Before, only turns served through magpie's accounts were, so with one account magpie learned the account was out only at the next look, minutes on, and the Codex app kept Send greyed until it was restarted (unsplashz on Discord; TestCodexUsedUpRelayedAsksAtOnce, TestCodexRelayedWindowsHeard). A Codex started before magpie became its provider keeps sending its own model's turns to its built-in provider; while the sign-in is known out (provider.CodexUsedUpKnown) and the request signs as it, those go through routing as codex/<model> (codexAccounts), as a restarted Codex's do (TestCodexHeldSignInServedWithoutRestart). The Codex app greys Send for every model, magpie's too, while its authMethod is chatgpt and its rate limit says not allowed (its composer's gate in ChatGPT.app 26.1013), and reads authMethod from its app-server's account/read only as the app-server starts; with magpie the provider (requires_openai_auth false) that answers no account, so the gate lifts. So the gateway process restarts the app's own app-server each time magpie becomes Codex's provider for the used-up account (Agent.AppOut) and again when Codex is put back on the account after its reset, and likewise whenever what the app-server reads as it starts and magpie writes changes (model_provider, openai_base_url, model_catalog_json, the magpie table's base_url, and a hash of what the catalog file holds, codexCatalogTag in codex_app_route.go, read again only when its size or time changes; codexAppRoute, through the provider.CodexAppRoute hook): a Disconnect, a Connect, failover written or taken out, a provider or group renamed or a model added. Without the catalog in it the app kept the names and models it started with until it was restarted (lucis0116 on X). Before this an app-server started while Codex was connected kept sending to the gateway after Disconnect until the app was restarted (JiangLiuer222 on X). At the watcher's first look only a used-up account's app-servers are ended, since what the others read before magpie started isn't known. It runs on every system (KeepCodexAppOnItsProvider, every 3s; Ethereal499 and Isdavexxx on X, MasterYi on Discord, #540: the earlier once-only reopen ran on macOS from the GUI process only, so Windows, Linux, a GUI-less magpie and the switch back stayed greyed). It ends only app-servers on magpie's Codex home (codexAppHomeIs: the process's CODEX_HOME, else HOME/.codex, read by proc.EnvOf; Windows can't tell and counts every one), only once no Codex request is in flight through the gateway nor ended in the last 10s (Server.CodexBusy) and no session under the Codex home has a turn started and not ended (codexTurnOpen), and with a clean exit (proc.End: SIGTERM, TerminateProcess with code 0), since the app shows any other exit as a crash. The app starts another app-server at once and keeps its window, threads and drafts (tried in the real app in a sandbox CODEX_HOME, both ways). An app-server that outlives three ends, or may not be ended, leaves the row saying to quit and reopen the app (CodexAppStuck). Until the reset the app's ChatGPT side is off (cloud tasks, its usage meter, Log out); the Agents row says so with the reset's time (appOut in /api/state, CodexOutUntil), and it all comes back at the reset. While the active account is held or a window is at 90% or more, its usage is read every minute rather than every five (codexLookEvery). TestCodexAppServerRestartedEachWay, TestCodexAppServerRestartedOnDisconnect, TestCodexAppRouteFollowsConnectAndDisconnect, TestCodexAppRouteFollowsTheCatalog, TestCodexAppServerUnknown, TestCodexAppServerStuck, TestCodexAppServersOnHome, TestCodexTurnOpen, TestCodexBusy, codex-app-out.test.cjs.
  • Moving a field from one of magpie's models to another (the agent's own picker) is not drift. Moving it off magpie is.
  • Claude Desktop applying a configLibrary profile other than magpie's is not drift when that profile is a gateway profile for this magpie's gateway (desktopAppliedGateway in claudedesktop.go): Desktop's "Import configuration" adds a file exported on another computer, magpie's profile there with the user's connectors (managedMcpServers), as a new entry under a random id (aa86222 on Discord). magpie keeps it applied on Reconnect and through Sync, and writes in it only inferenceGatewayApiKey (with a missing auth scheme) when the gateway would refuse its key (desktopKeyApplied; magpie's own keys count as taken, desktopKeyTaken). A profile for another gateway, CC Switch's among them, is still drift, and Reconnect applies magpie's. The first switch-on still starts magpie's profile from an applied one (#2035). TestClaudeDesktopImportedProfileIsOnMagpie.
  • Claude Desktop 4.4212 (10-29) seals the secrets of its configLibrary profiles at rest: at every start it writes inferenceGatewayApiKey (and every other string secret its schema drops on export) back as __sealed__:v1: + base64 of {"configLibrary":{"key":…,"value":…}} behind anthropic.claude.crossProfileSecret.v1:, protected with the user's DPAPI on Windows (entropy anthropic.claude.crossProfileSecret.v1, claude-native's userDpapiProtect) and Electron's safeStorage (the Keychain) on macOS, and it sends the gateway the key as it was. desktopOpen (desktopseal.go) reads the key as Desktop does: on Windows it opens the seal (desktopUnprotect, CryptUnprotectData, never prompting) and judges what is in it; a seal it can't open (macOS, another user's) is unknown, so Check doesn't call it changed and desktopKeyApplied doesn't write over it. Before this the key read as changed after every Desktop start and Reconnect only wrote it in the clear for Desktop to seal again (a Windows user on Discord). A key in the clear that isn't one the gateway takes, a missing key and another address are still drift (TestClaudeDesktopSealedKeyIsNotChanged, TestClaudeDesktopImportedSealedKeyStays, TestClaudeDesktopSealedKeyOpened on Windows).
  • A field that follows another while empty (Follows: Claude Code's tiers and subagents on its main model) is read by Drift as on that field's model. The main model moved, in Claude Code's own /model, onto the model magpie had set a tier to is not drift (#1050). The tier keeps that model as its own through the move and the next one (tier_own in the stash), whatever it would follow on the new main model: fable, which follows no model that is no Fable, and haiku, which follows a Claude model on its Haiku, read as following and lost their model on the next move (#2257).
  • A Claude Code tier or its subagents given a model of their own keep it when the main model moves onto that model and on again (ownKey in claudeIn), whether the main model is picked in magpie or in Claude Code's /model. Same as model, picked for them, has them follow again.
  • While this machine's Claude Desktop is on magpie, Claude Code's shared settings get CLAUDE_CODE_DISABLE_EXPLORE_INHERIT_CAP="1" (writeExplore in claudeIn, claude.go). Claude Code 2.1.295's Explore inherit cap can otherwise replace Desktop's mythos-magpie compatibility alias with Opus. This disables that cap, not the model choices of all subagents. It applies with Desktop alone or beside a connected Claude Code, including model picks and Sync; WSL twins do not get it. A user's existing value, including an empty string, stays. The stash (claude.explore_inherit_cap) marks only magpie's value: taking Claude Code off magpie leaves it while Desktop is on, and taking Desktop off removes it only if the user has not changed it. Since the settings file is shared, other Claude Code sessions reading it see the flag while Desktop is connected too.
  • Claude Code's tier and subagent models the user had set for their own endpoint (claudeOwnEnv) are stashed with that endpoint and token when magpie is wired in, and come back with them when magpie steps out, by Disconnect or by Claude Code's own model (#1050). So does their main model in the env (ANTHROPIC_MODEL, a Bedrock model id beside CLAUDE_CODE_USE_BEDROCK for one), which magpie takes out while wired in because it outranks a pick in /model.
  • Claude Code's auto mode field (auto_mode, claudeAutoModeEnv in claude.go) is CLAUDE_CODE_AUTO_MODE_MODEL, the model Claude Code 2.1.302's client-side auto mode classifier judges each action with (Linka on Discord). It changes nothing about server-side auto mode, and a classifier model Anthropic configures for the account comes before it. Unset, Claude Code picks its own (the sonnet tier's model, else Sonnet), so it follows no field and isn't Follows. It is set only while Claude Code is routed through magpie, only to one of magpie's models, dashed as the other model keys are, and never to Sonnet 5.5, Opus 5.5 or Opus 5 (claudeNoClassifier), which Claude Code 2.1.303 refuses there and replaces with its own pick. A value the user had before magpie routed Claude Code is stashed and taken out with their tiers (claudeOwnEnv), and comes back when magpie steps out, unless they set one again since; magpie's own value (claude.auto_mode_model in the stash, or any of magpie's models) goes then, and one the user set while wired in is left alone. Claude Code reads it as it goes, so it is Quiet and needs no restart.
  • Claude Code's provider switches (agentenv.ClaudeProviders: CLAUDE_CODE_USE_BEDROCK, _VERTEX, _FOUNDRY, _ANTHROPIC_AWS, _ANTHROPIC_GOOGLE_CLOUD, _MANTLE, Claude Code 2.1.300) send it to that cloud's own endpoint and pass ANTHROPIC_BASE_URL over, so with one on it never reaches magpie (jw1dev on X: Bedrock refused magpie's model, and magpie showed nothing). Claude Code reads 1, true, yes and on as on (claudeSwitchOn). One that is on in the settings magpie writes is taken out on every route that writes the wiring (dropClouds in writeTiers and Sync), its raw value stashed (claude.cloud.<var>, under the distro's id for a WSL twin), and put back as written when magpie steps out (putClouds in unroute), unless the user set it again since. The cloud's own variables (AWS_*, ANTHROPIC_VERTEX_PROJECT_ID, …) and a switch that is off stay. Where magpie doesn't write it, Check says so, naming the variable, the cloud and where (claudeCloud): the managed settings, which win over the user's; ~/.claude.json's env, under the user's settings; and, for this machine's Claude Code, the login shell's environment (proc.LoginEnv, read but never set in magpie's), under every settings file. A project's .claude/settings.json isn't read: magpie doesn't know which folders Claude Code runs in. T3 Code's Check says the same of the user's ~/.claude settings, which are put over its magpie instance's environment, and a switch put on that instance goes at its next write; that Check first says when the instance's ANTHROPIC_BASE_URL no longer reaches the gateway (t3EnvOf), as every agent's Check does, so a port move rewrites it too. The drift's detail is shown in the row's line and its pill through tNotice (claude-cloud-drift.test.cjs). Claude Desktop's Code tab runs with CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST, under which Claude Code ignores a switch in settings files, so Desktop needs neither.
  • Claude Code's sign-in (login) is magpie's key ("", the default) or claude.ai (claudeai). claude.ai writes ANTHROPIC_AUTH_TOKEN empty, which Claude Code reads as no key: it keeps its claude.ai login and sends that to magpie, which never passes it on (claudeSignIn in the gateway). Every later write keeps the token empty (wiredKey), and a caller key of the gateway's own put there by hand is taken for magpie's, by Check and a model pick alike, kept as the user left it (keyHolds, #2545); a key the gateway would refuse is reported by Check and wired over, and so is the sharing key magpie itself made (access.Default), once sharing is off — magpie's own, however well the gateway still takes it. It's offered only where the gateway takes any key (gwKey() == gateway.Token: loopback, a WSL distro mirrored), not from a distro under NAT while magpie is shared on the network, where only the sharing key gets in. The choice is stashed, so it survives Disconnect and a port move. An empty token counts as magpie's only beside the address magpie last wrote (claude.wired_at in the stash, which Rewire carries to the new port, keyOurs): an endpoint of the user's own with an empty token stays theirs when the model goes back to Claude Code's own.
  • Claude Code's auto mode review (CLAUDE_CODE_AUTO_MODE_SERVER, claudeReviewEnv in claude.go) is written "0" while Claude Code is routed through magpie and none of the models it can reach there is one Anthropic reviews (claudeReviewed, by gateway.AutoModeReviewable: a model AutoModeReviewed that is asked on the Messages API; a Claude model a provider serves only on Chat or Responses, or one set to be asked on another API, is translated, carries no safeguards and counts for nothing, nexnull on Discord, TestClaudeReviewedOnlyWhereMessagesReachClaude): those it is shown (and Claude Desktop's while Desktop is on magpie), a shown group's members, those providers' fallbacks, and the models it is set to, each judged on the provider (or group, or fallback) it resolves to, as the gateway judges its requests, so a Claude model on Copilot or Kiro alone writes "0" and a name magpie doesn't know is judged by the name (TestClaudeReviewedJudgesTheSetModelWhereItGoes). Off, it classifies locally from the start, as it does anyway behind a gateway that doesn't answer, without the "isn't eligible because your requests go through 127.0.0.1:3425" notice (1EFLOPS on X). Any reviewed model leaves it unset, since /model can take the session there; a model hidden from Claude Code doesn't count. It is rewritten on every model set and Sync, so adding a Claude provider turns the review back on. magpie's value is kept apart in the stash (claude.auto_mode_server), a user's own is left alone, and it goes when Claude Code is taken off magpie (desktopOnly, unroute). T3 Code's magpie instance, which runs Claude Code on the gateway through its own environment, carries the same "0" there by the models it lists (t3InstanceJSON in t3code.go); a value in the user's ~/.claude settings comes after it.
  • Claude Code takes one window (CLAUDE_CODE_MAX_CONTEXT_TOKENS, claudeContextEnv in claude.go) for every model it doesn't know. Claude Code alone on magpie is told its main model's (claudeWindow). While Claude Desktop is on magpie too, its Code tab runs Claude Code on the same ~/.claude/settings.json with every model Desktop lists, so magpie tells it the largest window of those and of Claude Code's own models, and holds each model below it to its own with modelSettings.<id>.autoCompactWindow (claudePlan in claude_budget.go, #2025: the least held a 1M model to 131K). A model handed by a [1m] id (Desktop's under DesktopLongest, or Claude Code's own) counts by its 1M too, so it still runs at 1M when Claude Code stops taking the id for 1M (the 1M beta turned away once, CLAUDE_CODE_DISABLE_1M_CONTEXT); left out, a 1M model beside a 272K GPT was told 272K (dumplings on Discord). Claude Code 2.1.296 matches that key by the id it was handed, lowercased and without [1m]; it comes before the top-level autoCompactWindow, which serves a model without one. CLAUDE_CODE_AUTO_COMPACT_WINDOW would take precedence over both, so in this mode magpie's working window goes in the top-level autoCompactWindow instead, and an entry is written only where a model's window or its own threshold differs from what it would run at without one. magpie's entries and top-level value are stashed (claude.model_budgets, claude.compact_default) and go when Desktop leaves magpie; the user's own entries, top-level value and variables stay, a user's entry past its model's window (or auto) holds the largest to that window, and with a CLAUDE_CODE_AUTO_COMPACT_WINDOW of the user's the least window is told as before.
  • Claude Code is told what each of magpie's models can do in CLAUDE_CODE_MODEL_CAPABILITIES (claudeCapsEnv, claudeCapabilities in claude.go): <model>=effort[,xhigh_effort][,max_effort] for those it is shown, and, while Claude Desktop is on magpie, for Desktop's mythos-magpie-<number> ids its Code tab hands it. A Claude model Claude Code knows gets no more than Claude Code gives it (Opus and Sonnet 4.6: no xhigh), and one with no known levels isn't named. A model that reaches max without xhigh (GLM-5.3 at low/high/max, DeepSeek V4 at high/max) is said to have xhigh too: the gateway runs xhigh at max for it (fitEffort), and Claude Code 2.1.299 turns Ultracode down without xhigh_effort ("Ultracode isn't available on …"), which in Desktop is the Ultracode level and dynamic workflows (leesunrise2364 on Discord; TestClaudeModelCapabilities). A value of the user's is left alone.
  • MiniMax Code takes a model ref with one slash in the whole (a SubAgent's model must match ^[^/\s]+\/[^/\s]+$, #1387), and magpie's refs there are custom_provider:magpie/<model>. So a model under custom_provider.magpie is written with ~ for each slash of its catalog id (bb-codex~gpt-6.1-sol, provider.FlatID), only when that spelling stands for one served id (provider.Flattened); the gateway takes it back. A config an older magpie wrote moves over on the next sync: the user's keys on a model go to its new key, defaultModel, defaultLightModel and memory.captureModel/consolidationModel follow (mcodeRefs), and the slashed key stays, switched off (enabled: false), so a session begun on it still resumes. magpie never edits the user's own agents/<name>/agent.md. No other agent was found with this limit (minimax.go).
  • Claude Code's /model list (modelPicker in its settings.json) is magpie's while it is marked in the stash (claude.model_picker, claude@wsl:<distro>.model_picker for a WSL distro) or while every row's description ends "via magpie", as every row magpie writes does (magpiesPicker in claude.go). magpie keeps its own list up to date on every model set and Sync, and removes it when Claude Code is taken off magpie; a list the user wrote is left alone. The fingerprint covers a list whose mark an older magpie's stash lost, which otherwise stayed without every model added since (#2046).
  • Claude Code 2.1.296 reads a Claude model whose version has a dot (relay/claude-opus-4.6-us) as Claude Opus 4: a retired warning, budget thinking, 32000 output tokens, no effort. With dashes (relay/claude-opus-4-6-us) it knows the model (misteer_ti. on Discord). So every model magpie writes into its settings (model, the tier envs, ANTHROPIC_SMALL_FAST_MODEL, CLAUDE_CODE_SUBAGENT_MODEL, CLAUDE_CODE_AUTO_MODE_MODEL, modelPicker), T3 Code's Claude slugs and Claude Desktop's Code-tab ids (claudeLooking) spell a dotted Claude version with dashes (provider.ClaudeSpelled), only when that spelling stands for one served id. A Claude model listed to Desktop with reasoning levels is given as magpie-<n>.anthropic.<model>, its dotted version dashed as well (claudeModel: Copilot's claude-opus-5.5 is …anthropic.claude-opus-5-5, which Claude Code knows; it was mythos-magpie-<n>, an unknown model, and Haiku 4.5 got an effort Copilot refuses, #1819); a request for it is served by <n> alone (aliased), so that spelling needn't be unique. Mythos counts as Claude here too: Claude Code matches claude-mythos-5-1 by substring, so claude-mythos-5.1 would read as Mythos 5. Every read of those keys takes it back (provider.ClaudeRead: claudeIn's env, claudeMain, claudeStandInAt), so magpie's fields, applied state and Drift keep the dotted id. The user's own values are stashed and given back as written. Values an older magpie wrote dotted are rewritten on the next Sync. Other vendors' ids are never respelled (claudedash.go).
  • Codex's "subagents" field is [agents] default_subagent_model: only the model a subagent starts on when its lead names none in spawn_agent (codex-rs core/src/agent/child_config.rs). Unset, it isn't "same as model": the lead may still name another, so the GUI calls it the lead's pick, else the model (leadPicks in app.js), and its title points at the "subagent model" field.
  • Claude Code's "subagents" field is env.CLAUDE_CODE_SUBAGENT_MODEL. Unset, magpie writes nothing there (writeTiers, setSubagent), and Claude Code picks: the Agent tool call's model, then the subagent's own frontmatter model, then the variable, then the lead's model (Claude Code 2.1.306; the built-in Explore inherits, capped at opus). So the GUI calls unset "Claude Code's own pick" (claudePicks in app.js), not "same as model" (KorenKrita on Discord). Its effort is written only with a model: unset, a saved subagent effort is kept (claude.subagent_effort in the stash) and not applied, since writing the main model at that effort into the variable would pin every subagent to the main model (KorenKrita on Discord). A model picked later takes it. A value an older magpie wrote that way (the main model at an effort, not own) is moved into the stash and taken out of the env by writeTiers and Sync (subagentFollowing, TestClaudeSubagentEffortNeedsAModel). The window draws that effort at the right of the Subagents row like a tier's, disabled at Default while the model is unset (effortBtn in connectPanel, claude-subagent-effort-row.test.cjs); the tray panel keeps its own square.
  • Codex's "subagent model" field writes nothing to Codex's config: its lead names each subagent's model in spawn_agent, which [agents] can't overrule. It is magpie's setting (settings.CodexSubagentModel, codex_subagent.go), and the gateway moves the subagent's request onto it (see gateway routing). Its options are every model and routing group Codex's own lists show (CatalogFor("codex"), so a model taken out of them or not picked is left out here too), ChatGPT accounts' first (#1633: a lead on a chat provider wants its subagents there too). A task a ChatGPT-backed lead sealed opens only on a ChatGPT account, so the gateway keeps such a subagent on its own model when the one set is another provider's. Its setter takes any provider/model or group/<id>, also one magpie doesn't serve now, so a profile or backup put back on another computer still applies (ApplyFields stops at the first failed Set), and refuses one of Codex's own bare names.
  • Claude Desktop's "subagent model" field (subagent_model, desktopSubagentField in claudedesktop.go) writes nothing to Desktop's config: Desktop runs its Code tab's Claude Code with CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1, under which Claude Code ignores CLAUDE_CODE_SUBAGENT_MODEL, CLAUDE_CODE_SUBAGENT_MODEL_FORCE and the tier variables in its settings files' env ("Ignoring … this session's provider routing is managed by the host", Claude Code 2.1.295), and the env Desktop builds for the Code tab has no key for it (Desktop 2.31226). It is magpie's setting (settings.DesktopSubagentModel, desktop_subagent.go), and the gateway moves each subagent's turn onto it (see gateway routing). It is labelled as Codex's, so the Agents page gives it the same square. Its options are magpie's models and groups as Desktop's list shows them (viaMagpie("claude-desktop")), while Desktop is on magpie, as for the tiers. A Desktop alias picked is kept by its catalog id (DesktopCatalogID). Like Codex's, its setter takes any provider/model or group/<id>, also one magpie doesn't serve now, so a profile or backup still applies, and refuses a bare name. It is Live: the gateway reads it on each request.
  • Claude Desktop's "subagent effort" (desktopSubagentEffortField, settings.DesktopSubagentEffort) is also Quiet and Live. Default keeps the effort the request asks for, including disabled thinking; it never selects a new default. A picked level works independently of the subagent model: no model pick, the same model and an unavailable model pick all still take the effort. While wired, the field offers the selected model's levels, or the standard levels when its model is inherited or unavailable; a model marked reasonless offers none. The stored pick survives model changes. A disconnected preference can be saved or cleared without connecting Desktop or showing restart advice, so profile restoration and Disconnect can restore a value saved before connecting; reconnect returns to the last live pick. subEffortTitle gives Desktop the Claude Code default explanation; Codex's default meaning is unchanged. The gateway fits each attempt to its actual model and preserves fixed group-member efforts (see gateway routing).
  • Claude Desktop's 3p mode runs in a userData of its own (Claude-3p), whose config.json (Desktop's own settings, not claude_desktop_config.json) starts with no locale, so Desktop on magpie came up in the system's language rather than the one picked signed in with Anthropic (memory and Osal on Discord). Turning Desktop onto magpie copies that one key, locale, from the signed-in userData's config.json (Claude, %APPDATA%\Claude on Windows, the first set's before the others) into Claude-3p/config.json when that file is missing or a JSON object without one (desktopCarryLocale in claudedesktop.go); only a name Desktop takes for a catalog is carried. A locale already in Claude-3p, Desktop's or set by hand, is never written over, and no other key of that file is ever written. Off removes the file only when magpie made it and it still holds nothing but the language carried (TestClaudeDesktopCarriesTheLanguage, TestClaudeDesktopKeepsThe3pLanguage, TestClaudeDesktopUserEditsThenReapply). Desktop shows the language only where its 3p window has that catalog: the window is Desktop's bundled UI (Resources/ion-dist, 11 catalogs and no Chinese in 2.7032, 2.9939, 3.6556.2 and 4.4212.0 (packed as Resources/ion-dist.asar there), while 3.6556.2's main process has zh-Hans and zh-Hant for the signed-in window). On every start that window asks the main process for its own pick (requestLocaleChange: its localStorage, else navigator.languages mapped onto its 11, else en-US), and the main process writes it into Claude-3p/config.json. So a Chinese locale there, carried or set by hand, is en-US again after each start, written by Desktop and not by magpie (Dx25 on Discord, Windows); nothing magpie writes can keep it. So the GUI says it to a Chinese reader: Claude Desktop's opened row on Agents has a line that Desktop on magpie is Anthropic's gateway window, with no Chinese, and that its Chinese comes back once disconnected, and the switch-on notice says the same in Chinese (GZXYMH on X, desktop-lang.test.cjs).
  • Claude Desktop's sessions (Code and Cowork, claude-code-sessions and local-agent-mode-sessions) are kept in the userData Desktop runs in, keyed by account and organization (the claude.ai login signed in; in 3p the install id in ant-did and the profile's organization, both stable). So on magpie, in Claude-3p, the sessions made signed in with Anthropic are out of sight but untouched in Claude, and they show again when Desktop is switched back (lambdua on X: "切换账号,对话都不见"); claude.ai chats live on Anthropic's servers and 3p never shows them. magpie never writes or removes a session. Desktop imports them itself (Settings → Import: the signed-in userData, ~/.claude/projects, other Claude* folders), copying under new ids and leaving the originals, but in 3p only when the profile's policy claudeAiImport.enabled is true (off by default, 3p only, from 1.28929.0). magpie's profile gets "claudeAiImport":{"enabled":true,"bannerBehavior":"detect"} once per folder set (desktopSeedImport, marked in the stash as claude-desktop.import): on the switch on and, for a Desktop already on magpie, from Sync at magpie's start. A claudeAiImport already there is kept, and one the user removes is not written again (TestClaudeDesktopOffersItsSessionImport).
  • Claude Desktop's 3p mode reads its MCP servers (Settings → Developer, its connector list) from Claude-3p/claude_desktop_config.json, a file of its own, so on magpie the servers the user added signed in with Anthropic, in Claude/claude_desktop_config.json, were gone from the list (aa86222 on Discord: connectors didn't sync). Turning Desktop onto magpie copies each of those mcpServers entries that Claude-3p has none of the same name for (desktopCarryMCP in claudedesktop.go); one of that name already there, the user's or the Library's (which writes both files), stays. Sync does it once for a Desktop already on magpie (claude-desktop.mcp-seen), so a server the user takes out in 3p isn't brought back. What was copied is stashed (claude-desktop.mcp), and off takes back each one still as copied; one the user changed since stays (TestClaudeDesktopCarriesTheMCPServers, TestClaudeDesktopMCPKeepsThe3pServers, TestClaudeDesktopSyncCarriesTheMCPServersOnce). Claude's file is never written. A claude.ai account's connectors can't come along: Desktop calls them through claude.ai with that account (/api/organizations/<org>/mcp/servers/<id>/tools/call, refused with no_active_org without one, Desktop 2.7032), and 3p mode has no account; Anthropic's docs say "Made by Anthropic" connectors are only in standard Desktop, and others reach 3p through managedMcpServers or plugins (claude.com/docs/third-party/claude-desktop/extensions).
  • Claude Desktop names a Claude model with reasoning levels after its own catalog ("Opus 5.5"), not by the display_name magpie lists, because magpie lists it as magpie-<number>.anthropic.<model> to keep its effort picker (claudeLooking in desktop.go). Two providers' rows of one model then differ in Desktop's menu only by that number, so the provider editor shows it on the model's chip (gateway.DesktopNumber, desktopNumbers in providers.go, #2578). The chip shows it only while Claude Desktop is installed and is shown that model. Every other model Desktop is shown carries no number on the chip: Desktop names it by display_name, which already says the provider, or by its own id.
  • Codex's spawn_agent tool names only the first five models of its catalog to the lead (codex-rs MAX_SPAWN_AGENT_MODEL_OVERRIDES in child_config.rs, spawn_agent_models_description), Codex's own ahead of magpie's, though it takes any catalog model by name (find_spawn_agent_model_name). So a lead could put its subagents on none of magpie's models (Gearclickist on Discord). The gateway adds the rest of the catalog Codex was handed to that tool's description, after Codex's own list, at most 200 (spawnAgentModels in codex_spawn_models.go). A model that can search tools (supports_search_tool) isn't handed it in the request's tools: Codex defers its multi-agent V1 tools behind tool_search (codex-rs core/src/tools/spec_plan.rs), and the lead gets spawn_agent in the tool_search_output Codex puts in the conversation and sends again every turn, so that one is widened too. That text goes upstream with the prompt, to OpenAI too for a ChatGPT lead, so its header (spawnMore) stays neutral: it names neither magpie nor Codex's limit. At CodexPath that is Codex's own listed models less the hidden ones, then CodexListed unless Codex is held to its own. At /v1 it is CodexCatalog under the key's allowance. A lead the ChatGPT backend answers in multi-agent V2 seals its subagents' tasks for a ChatGPT account (#619), so it gets Codex's own only. The model catalog Codex puts in context under model_catalog_in_context (under development, off by default) is capped at five too, and isn't widened.
  • Snow CLI runs on one profile at a time (profiles/<name>.json in ~/.snow or $SNOW_CONFIG_DIR, named in active-profile.json) and copies the active one over config.json at every start, snow --ask too (snow.go). magpie writes a magpie profile, makes it the active one, and copies it to config.json itself, so a Snow already running and Snow App's "Sync Snow CLI API config" see the same. It is made from the profile the user was on, their settings kept and its OAuth sign-in left out. A vision model of that profile comes along only with an endpoint and key of its own (snowOwnVision), since one on the profile's would now go to the gateway. maxContextTokens, maxTokens and supportsVision follow the model from the catalog (snowSynced; supportsVision as every agent is told, true while magpie's Vision describes images); what magpie last wrote of them is stashed, and one the user changed since in Snow's own settings is kept through later picks and syncs. The small field is magpie's profile's basicModel, Snow's light model for summaries, compaction and file search: empty while it follows the main model, a model through magpie of its own kept through new main models and syncs; on a profile of the user's it offers nothing and is hidden. The thinking field is magpie's profile's chatThinking ({enabled: true, reasoning_effort}), the only thinking setting Snow reads on the chat protocol; empty deletes it, Snow's default, which sends thinking disabled. A chatThinking the user brought from their profile is shown, not written over. The profile they were on (or that there was no active-profile.json) and a magpie.json of their own are stashed and put back by Disconnect. A Snow from before profiles (config.json alone) gets the default.json Snow itself would have made of it, so its next start doesn't take magpie's for the user's. Picking a model of another of the user's profiles switches Snow to that profile. On magpie's profile, a value that is neither a model through magpie nor the model of one of the user's profiles is refused and changes nothing (#1457: magpie snow --help used to take magpie out and write --help as the model of the profile it went back to). Gemini CLI's auth field refuses an auth it doesn't know before it unroutes, for the same reason. On the CLI, -h/--help after any command or agent only prints its usage, before run reads or moves anything, and any other flag given to magpie <agent> … is refused (help_cli.go; TestHelpOnEveryCommandDoesNothing walks run's switch and every agent).
  • omp's enabledModels in config.yml is the list it holds its default role to: a model left out of it isn't used, whatever modelRoles.default says (#1769). So a model picked for the default role is added to a list that is there and doesn't take it in already, by name or by one of omp's globs (* not crossing /, as Bun.Glob), and once nothing in config.yml is on magpie its plain magpie/… entries are taken out (a list left empty goes, never []); a renamed provider's entries are renamed once, and folder-scoped entries are left alone (ompScope* in omp_scope.go). No list, no change: omp then takes every model. A list that leaves the default role's model out is drift, which Reapply mends.
  • Pi's enabledModels in settings.json (and OmO's and Prime Agent's, piLike) is the Ctrl+P list a new session starts from. A picked model the list doesn't take in is added (piScopeWith in pi.go), and a renamed provider's magpie/<old>/ entries are renamed with it, a glob or a thinking level included, the copy the pick just added dropped (renameRefList in rename.go, #1919, TestPiEnabledModelsFollowRename). The user's other entries stay; a list naming none of the provider's models isn't rewritten.
  • After the catalog sync, an entry in Pi's (and its forks'), StepCode's or omp's enabledModels that names one of magpie's models outright (no glob; a thinking level read off) whose model magpie no longer gives the agent is taken out: Pi warned "No models match pattern" for each one at every start (#2055). It may be the user's own, so it is remembered in stash.json (<agent>.scope.gone) and goes back on the list's end when the model is offered again; a rename moves the remembered entries too, and a disconnect forgets them. Globs, other providers' entries and omp's folder-scoped entries stay. A list left empty is removed and made again when its entries come back, with the model picked meanwhile; one the user removed isn't. When magpie's model list in the agent's file can't be read, nothing is taken out (scope_gone.go, TestPiEnabledModelsLoseDeselected). For StepCode, the wiring state's last-written scope follows, so a disconnect still puts the user's own list back.
  • A value an agent spells as its own provider's model is never taken for one of magpie's, even when magpie has a provider of the same name (Spelled, #835).
  • The other way round, a value that names one of magpie's models the agent isn't shown (kept from it by magpie visible or a model not ticked for it), a model of one of magpie's providers that isn't on its list (a remote magpie's group added there since the list was fetched), or a group/… magpie has no group for, is refused by Spell (notOffered), and nothing changes. It used to be written as the agent's own: Pi read remote/group/smart as its own provider remote and model group/smart, and was taken out of magpie (#2376). A model shown the agent that a field offers fewer of (Claude Desktop's tiers) is still taken, and so is a value whose provider part one of the agent's own models goes by (openai/… in Pi) (agent.go, TestSpellRefusesMagpieModelNotOffered).
  • Reapply on unwired sets again every field on one of magpie's models and every field set to magpie itself (magpieID, as Wired takes it): Claude Desktop's drift shows on a tier, and its provider field is what writes the gateway back (dumplings on Discord). Claude Desktop's Check judges only the set of folders whose Claude-3p it ran in last (desktopRead, by desktopdir.LastRun), every set when it ran in none: magpie writes both of an MSIX install's sets, and 2.31226 reads the real %LOCALAPPDATA%\Claude-3p, so the package's copy being emptied is not Desktop off magpie.
  • unreachable never sets anything: the config is right, and the page's pill only says what has to listen. The exception is an address a WSL distro reached Windows at before (distro.Was, kept in wsl.json) while it reaches Windows at another now: the pill offers that one, and Reapply moves the config there (Agent.move, Codex's codexMoveGateway). An address no distro was seen at is the user's own and is never moved. An unknown answer (no probe yet) and a gateway down on loopback too are not drift. Tests stub reachProbe in TestMain. A WSL twin's address on a WSL network is asked from inside the running distro (reachFrom, wslReach: curl, wget or bash's /dev/tcp), never from Windows, where the gateway's own listener answers whatever the firewall keeps out. A distro that can't connect is told the firewall rule that lets it in (wslFirewallCommand). A stopped distro is never run to be asked, and one with nothing to ask with is not drift.
  • proxied (Muma102kMichael on X: every project and every new chat 502 after magpie took Codex over) is this machine's Codex sending its requests for the gateway through a proxy that doesn't pass them on, while the gateway answers here (codex_proxy.go). Codex's reqwest takes HTTP_PROXY, else the system's proxy for http:// (macOS' HTTP entry alone, never its HTTPS or SOCKS one; Windows' ProxyServer only when it is one address for every protocol), else ALL_PROXY, and lets only an exact IP or a CIDR in NO_PROXY (on Windows, with no NO_PROXY, the bypass list with *. taken out) keep 127.0.0.1 off it: 127.* and localhost don't, and macOS' exceptions aren't read. With [features] respect_system_proxy it asks the system alone, matching its list itself, wildcards and <local> included, and goes direct when no proxy is set there; a macOS SOCKS entry alone it can't use, and takes HTTP_PROXY/ALL_PROXY then (codex-rs outbound_proxy; tried with codex-cli 0.162.1). Its reqwest has no SOCKS, so a socks5:// proxy is spoken to as an HTTP one, and the probe does the same. The environment is Codex's: the login shell's *_PROXY (proc.LoginEnv, which a terminal's Codex and the ChatGPT app's both have; only exported ones, as the probe asks a child /bin/sh for them, so fish's unexported universal http_proxy doesn't count, #2627) over magpie's own, which a magpie opened from the Dock lacks (liu_dyj on X: a NO_PROXY=127.0.0.1 in the profile, or a macOS proxy with no HTTP entry, warned while Codex went direct). codexProxyFor works out that proxy the same way, and a GET / through it must come back as magpie's (proxyProbe), tried as reachable is. Its pill says how to fix it, as unreachable's does, naming the proxy and the variable it was read from, http_proxy or HTTP_PROXY as it is (Addr, Detail), through netproxy.Redact, without its user and password (#1886), while the probe goes through it whole, and the dialog has Disconnect from magpie. Account failover, which magpie writes uninvited, waits for that probe (codexProxyOK) and isn't written while the proxy doesn't pass Codex on, and one it wrote goes again. Tests stub the env, the system proxy and proxyProbe in TestMain.
  • Listing never starts a stopped WSL distro. A stopped distro's agent shows what was last seen there (asleep, wsl.json); setting one of its fields writes its files, which starts the distro. The Library keeps what it last saw of each agent's places there in the same memory (WSLKeep, WSLKept; see library), and lists a stopped distro's agents from it.
  • Codex's sign-in (login) is ChatGPT ("", the default), Always ChatGPT (chatgpt) or magpie API (api). With ChatGPT, magpie's models join Codex's own beside the sign-in (openai_base_url), and while the Codex app holds the ChatGPT account Codex is signed in to (codexUsedUp, provider.CodexUsedUp: OpenAI no longer allows the account and it has no credits left, a workspace still within its overage excepted), magpie is made Codex's provider (codex.out): the Codex app sends nothing at all on an account it holds, a magpie model's turn included (#540), and as a provider of its own magpie is past that. A window at 100% with credits left doesn't count, and Codex stays signed in. Sync puts it back beside the sign-in once the account has room. Always ChatGPT never does that: Codex stays in its ChatGPT state, and the Codex app may send nothing till the account has room, while Codex CLI's turns still reach magpie by the base URL, and its routing and other accounts serve them. Codex's app-server answers account/read and getAuthStatus with no account and no token for a provider without requires_openai_auth, and the Codex app then switches to an identity of no account: its ChatGPT mode's chats and projects ("Work") are gone, with its Chrome control (#1824) and cloud tasks, while magpie's models still answer (Qyburn3 on X). So [model_providers.magpie] says requires_openai_auth = true while Codex has a ChatGPT sign-in with room (openaiAuth: codexChatGPTKnown and not codexUsedUp), magpie API included; Codex still sends magpie's key (experimental_bearer_token) and no ChatGPT-Account-ID, with the same tools (tried with ChatGPT.app 26.1021 and its codex 0.164.0-alpha.11 against a capturing server). Not for an API key alone (Codex drops its image tool for a provider requiring OpenAI auth, uses_openai_actor_authorization), no sign-in (the app would ask for one), or a sign-in the Codex app holds: the app would read its rate limit again and grey Send for magpie's models too, which codex.out exists to get past. Sync writes the key in or takes it out as the sign-in or the allowance changes, an older magpie's table included (authStale), and the key is part of the app-server's route (codexAppRoute), so the Codex app is restarted onto its account (TestCodexMagpieProviderKeepsChatGPTAccount, TestCodexAppRouteFollowsOpenAIAuth). While magpie is Codex's provider for codex.out the app has no account till the reset, so the Agents row opened over that takeover names browser use among what is off and offers Keep on ChatGPT right there (keepChatGPT, posting login = chatgpt); picked on one of Codex's own models taken over (codex/<model>), set puts Codex back on its sign-in at once, model_provider and model_catalog_json gone, where it had left magpie the provider (eddie.zhan on Discord, TestCodexOwnModelOutThenKeptOnChatGPT). While magpie is Codex's provider (magpie API, or codex.out), Joined reports false although the codex.joined mark stays for Sync's way back: the Agents row said Codex's own models stay in /model beside magpie's, the ChatGPT state the Codex app blocks sending in, and the app only leaves that state once it is restarted (#2267, TestCodexProviderIsNotJoined). A Codex that reaches the gateway from another machine (a WSL distro under NAT, or MAGPIE_ADDR pinned beyond loopback, onAnotherMachine(at.gw())) is wired as one with no ChatGPT sign-in (chatGPT() is false there): never joined or beside, since beside its sign-in it would send its ChatGPT token to /backend-api/codex, and from there the gateway takes a named key alone, so every request was a 401 (#2145, TestCodexBeyondLoopbackNotJoined). magpie is its provider and it sends gwKey(), the LAN sharing key; one of its own models picked goes straight to OpenAI on its sign-in.
  • Whether Codex is signed in to ChatGPT is read from its auth.json or keychain item (codexChatGPTKnown, provider.CodexSignInKnown). Codex rewrites auth.json in place when it refreshes its tokens (codex-rs FileAuthStorage::save opens it with truncate), so a read in that moment finds it empty or cut off, and a keychain read can fail for a moment. Such a read is unknown, and Codex is taken to be as magpie last wired it (joined, beside, or codex.out); only a sign-in that isn't there (no auth.json, no item) or holds no ChatGPT token is "not signed in". Taking an unknown read for "not signed in" made Sync or a pick move Codex from beside its sign-in to magpie as its provider, with no codex.out to bring it back, and the Codex app showed "magpie" for its account and magpie's catalog for its models, on and off (lucy on Discord, v0.1.1394; TestCodexHalfWrittenAuthKeepsSignIn, TestCodexHalfWrittenAuthKeepsOut, TestCodexSignInKnown). A top-level forced_login_method = "api" in Codex's config.toml (another tool or guide writes it; magpie never does) counts as no ChatGPT sign-in: Codex logs such a sign-in out as the TUI starts and its app-server reads no account (codex-rs enforce_login_restrictions, load_auth), so wired beside it the Codex app asked for a sign-in and offered an API key alone (Tiger on Discord). magpie is then the provider without requires_openai_auth, and Codex needs no sign-in. The line is the user's and stays; taking it out brings the ChatGPT account back to the Codex app (requires_openai_auth) (TestCodexForcedAPILoginIsNoChatGPT). So does a sign-in OpenAI refused to refresh for good (jjt on Discord, #4308): Codex keeps its auth.json as it was and the refusal in memory alone, and wired beside it every turn, magpie's models too, failed at Codex's workspace routing discovery (/wham/accounts/check, 401). magpie refreshes Codex's sign-in itself (codexTokenRenewing, on its usage read), and a refusal Codex takes as permanent (codex-rs request_chatgpt_token_refresh: refresh_token_expired, _reused or _invalidated, a 400 invalid_grant, or a 401 carrying an error code; codexRefreshGone) is kept for that Codex home as the refused refresh token's hash (codex-signin-gone.json, only while the store still holds that token). codexChatGPTKnown reads that sign-in as none (provider.CodexSignInGone), and magpie is the provider without requires_openai_auth; the user's auth.json stays. A 5xx, a network error, a 401 with no code, or a token Codex replaced meanwhile marks nothing, and a record that can't be read is unknown. Signed in again, the refresh token is another one and counts at once; KeepOnAnAccountWithRoom's loop (noteCodexGoneNow) has Sync write requires_openai_auth back within minutes (TestCodexGoneSignInIsNoChatGPT, TestCodexSignInGoneWhenRefusedForGood). In left-alone mode magpie doesn't refresh Codex's sign-in, so nothing is recorded there.
  • Codex signed in to ChatGPT and not connected still gets openai_base_url while more of its ChatGPT accounts are on in magpie (failover, stash codex.failover; with a CC Switch mirror as its provider, the mirror's base_url and codex.mirror_failover), so a turn its own account has no allowance for goes on to the next — never for a Codex that reaches the gateway from another machine, where that path takes a named key alone and the failed-over turn came back a 401 (#2145, TestCodexFailoverBeyondLoopbackNotWritten); Sync takes one it wrote before off again. That Codex is FailingOver: not Wired, yet its requests go through magpie. The Agents row says so and what turns it off (FailoverSaid in the CLI and TUI, failover in /api/state, a button to Providers › Codex in the GUI), and the gateway hands it only its own models from /backend-api/codex/models (CodexOwnOnly, set on gateway.CodexOwnOnly by main; its ETag carries provider.CodexOwnListTag, and Sync ages a models_cache.json without it). A connected WSL Codex shares the gateway path, so while one is connected every Codex gets magpie's models (#1385). A base URL the user wrote by hand (#856) isn't failover's and stays a plain not-connected row. A Codex the user disconnected gets no failover till they connect it again. The app serving the gateway takes failover out as it quits (EndFailover, EndCodexFailover in OnShutdown), so a Codex left on its own goes straight to OpenAI rather than retrying a gateway that's gone (Leon920717 on X); the next start's Sync writes it again. Codex's app-server read the old base URL as it started and keeps it, and KeepCodexDaemonCurrent ends with magpie, so EndCodexFailover restarts it there when no codex session is on it (codexDaemonCheck); with one on it, it stays on the gone gateway until the user restarts it (thisisvainxx on X: "several restarts"). So does every thread already open, in the Codex app above all: each turn went to the closed port, and a system proxy in between answered 503 Service Unavailable: Unknown error, url: http://127.0.0.1:3425/backend-api/codex/responses until magpie was opened again (idkatbro on X; without a proxy Codex says "Connection refused" and reconnects). Masking plays no part: it runs only in the gateway, and its own 503 says why. When EndCodexFailover took failover out, the gateway's address is this computer's and Codex runs (provider.CodexPIDs: the app's app-server, the daemon, the CLI's sessions, an editor's codex), OnShutdown starts magpie codex-relay apart from itself (agent.RelayOpenCodex, codexrelay.Start; Setsid, or a detached process on Windows). It waits up to 60 s for the gateway to let go of the port, then serves only /backend-api/codex/* from Codex on this computer (a loopback Host, no Origin) and passes each request to the ChatGPT backend as the gateway passes a turn of Codex's own: the same item-id, compaction and Claude-seal rewrites, zstd and proxy, signed by the caller's own Authorization (gateway.CodexRelay). A magpie model, a turn on one of magpie's accounts, and a turn masking would have masked are refused with a readable 400 instead (Codex retries a 5xx five times over and shows a 4xx at once); anything else says magpie isn't running, never as magpie (ServedBy). It ends once every Codex process it was left for has and nothing is in flight, and the next magpie to serve the gateway asks it to leave (codexrelay.Leave in ListenAndServe and serveGatewayLocked; a POST with the token from codex-relay.json, 0600 in magpie's folder): it closes its listener at once and finishes the turns it streams, up to 30 minutes. TestCodexRelay*, TestLeaveFreesPortAndFinishesStream, TestEndsWhenCodexGone, TestLeaveNeedsToken. Not covered: a connected Codex (magpie's models, left pointed at magpie by design), a Codex in a WSL distro, and a magpie that ends without quitting. Every restart magpie makes runs codex app-server daemon restart as its own responsible process on macOS (proc.CombinedOutputOwn, a disclaimed posix_spawn): the daemon works in the folder of each codex attached to it, and as magpie's child the first codex in ~/Desktop had macOS ask for the Desktop folder in magpie's name (reformed9448 on Discord; TestRestartedCodexDaemonIsNotMagpies). A magpie built without cgo (the CLI) still restarts it as its own child. A connected Codex keeps magpie as it quits: its model is one of magpie's, and Disconnect is what puts its own config back. A magpie that ends without quitting (killed, a crash, magpie serve) leaves failover in place.
  • A Codex thread keeps the provider it was started on. While a magpie model is on, CC Switch's provider tables go through magpie too (takeTables), and get their own base URL back when Codex steps off magpie (giveTables, stash codex.tables). CC Switch's OpenAI mirror (a table of another id, name = "OpenAI", requires_openai_auth, no base_url) isn't reached by openai_base_url, which takes only the built-in provider to magpie: a thread started on it and reopened went straight to ChatGPT, which refused the magpie model picked in it, and magpie never saw the request (#1796). While Codex goes to magpie by the base URL, takeMirrors gives each such mirror magpie's ChatGPT backend as its base_url (stash codex.mirrors), and giveMirrors takes it off again; a mirror a profile names, or one whose base_url was changed since, stays as it is. Moving the threads onto another provider is the Sessions page's Move (#887).
  • An agent's config is written in the form the installed version reads, taken from what that version declares, not the latest one. VSCodium has no Copilot Chat of its own, and the Marketplace's last one (0.48.1) has no Custom Endpoint provider, only OpenAI Compatible (customoai, #1014). magpie reads the provider list in the package.json of the github.copilot-chat installed under ~/.vscode-oss/extensions (vscodeChatOf). It writes its group for customendpoint when that is declared, for customoai when only that is, with each model's window as maxInputTokens + maxOutputTokens and the token as x-api-key (that version drops an Authorization in requestHeaders). A missing or unreadable extension keeps customendpoint. Sync rewrites a group written for the other provider, and Check reports it, as it does a Copilot Chat declaring neither. That Copilot Chat registers its providers only while signed in to GitHub with a personal Copilot plan, which the Notice says.
  • Tuned settings are written only on the user's click, never by Sync or Connect. A window that is Long conversations (TuneLong) is stashed once as Long conversations was (tune.long.compact, one stash for both agents, as the value is one), and Undo puts it back, Full window included, unless the user changed it since. Codex's card is always Long conversations, unless config.toml has a model_auto_compact_token_limit of the user's, which Codex stops at first: that one is locked. A limit an older magpie's tune wrote there (tune.codex.compact) is moved by tuneMigrateCodex, from Codex's Sync and from the card: Long conversations at magpie's default, or under Full window, takes it as the user's own choice; one the user typed takes it only when it is lower, where Codex compacted; the file gets back what it had; and a limit the user changed after the click is theirs and stays. Claude Code's CLAUDE_CODE_AUTO_COMPACT_WINDOW is Long conversations when magpie wrote it from that value (claude.compact_long beside claude.compact_window, set by writeCompact), and its top-level autoCompactWindow when magpie wrote it (claude.compact_default) and it equals Long conversations; a window from a provider's Compact at, or the user's own, stays locked. A Claude model's own modelSettings window, under no such variable, is still per model, since Long conversations doesn't reach Claude models. The value there before is stashed once (tune.<agent>.<knob>[.<model>] in stash.json), so Undo puts it back, or takes the key out (and a modelSettings entry left empty). A value the user changed after the click is theirs: Undo then only forgets the stash. A variable that comes before the setting (CLAUDE_CODE_AUTO_COMPACT_WINDOW, FORCE_PROMPT_CACHING_5M, CLAUDE_CODE_PROMPT_CACHE_TTL, CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, in settings.json's env or magpie's own) is shown as locked and Apply refuses, since the setting would change nothing. Claude Code compacts at the smaller of the window set and the model's own (its /autocompact says "capped to 200k by model"), so advice starts from that, and a model that isn't Claude's has no window here (magpie's own compact wiring serves it). Codex's window is the one magpie's catalog lists for each model it ran (typed, or the vendor's), and with none in config.toml it runs now at what magpie tells Codex (provider.CompactFor, else Long conversations in the agent's opened row, as codexcat writes it); a model of magpie's whose window isn't known caps nothing short of 1M (or the user's own larger value), never the largest prompt seen (zhemu on Discord: a 1M model at 750K was offered up to 410K), and only Codex's own models, outside the catalog, keep 272K or the largest prompt (codexWindow, TestTuneWindowsAreTheUsers). Advice changes a value only when the replay saves 3% or more, and of the windows within 1% of the cheapest takes the largest; with the compactions timed, it never advises a window that compacts more often than the one now, so never a longer wait: of the windows that compact no more often it takes the cheapest, and of those within 3% of that (sameCost, the same bar as changing at all) the one that compacts least, the larger of two that compact as often. Tokens and seconds share no unit the files measure, so the advice doesn't trade one for the other at a guessed rate; a cheaper window that waits longer is said with its wait in the row and the picker, for the user to choose. The wait per compaction is taken as the same at every window: the files time compactions only near the window the user ran with, too narrow to fit how it grows with the prompt. Tokens are weighed as billed: cache reads 0.1, 5-minute writes 1.25, hour writes 2, output 5 for Claude; reads 0.1, writes 1, output 8 otherwise.
  • A plugin's agent writes each key in place (JSON, YAML or env), the user's comments and other keys kept. An object or array connect returns is taken as its JSON text (agentplug.keys), so it is written in the order the plugin gave it, not sorted as a Go map would be: Kilo lists its effort variants in key order (#1890, TestPluggedKeepsPluginOrder). What each key held before the first write is stashed under plugin:<id>:<path>, typed, and its own model or Disconnect puts every key back and takes out the ones that weren't there; the file is never written whole. A connect that throws or takes over a second writes nothing and says why. Its gateway key is magpie-<id> (agentKeyAt), and usage names its requests by that key or by its ua words (usage.PluginAgents). Its agent.library (instructions, mcp with mcpFormat, skills) gives it the Library's three as well, written by internal/library as any agent's are (library); a mcpFormat outside agentplug.MCPFormats, or an mcp without one, keeps the plugin from loading. Turning the plugin off or removing it (provider.SetPluginOff, provider.RemovePlugin, from the CLI or the Plugins page) first disconnects its agent as magpie <agent> default does (provider.PluginAgentGoing, set to agent.UnwirePlugin in plugged_gone.go), since without the plugin magpie no longer knows the agent (#3810); a plugin already off is read from its module as it is, and one whose module is gone puts back each file whose stash names its spec. A failure keeps the plugin as it was. On again, the agent stays as the user had it, and connecting it puts back the model it was on (Disconnect's .reconnect). The stash records the plugin's spec and the file's format, so magpie <id> default for the agent of a plugin deleted on disk puts the file back from the stash alone (agent.RestoreGone; an older stash's format is its file's name, agentplug.FormatOf); a file that no longer holds the gateway's key is the user's and left alone, and one that can't be read is put back over by nothing; with the plugin only switched off, it says the agent is off magpie already, not "unknown agent" (TestPluginOffPutsItsAgentBack, TestRestoreGoneAgent, TestGoneAgentDefault).
  • StepCode config root resolves to the parent of an absolute STEP_CODING_AGENT_DIR (agent resources directory differs from config root; relative values ignored), or STEPCODE_CONFIG_DIR under home when native, defaulting to ~/.stepcode (stepcode.go). Project configs override global configs in StepCode, but magpie manages global configuration only (config.toml and models.json). Detection is strictly directory-only via agentDir, avoiding collision with Smallstep's bare step command on PATH. Wiring performs an atomic two-file edit (models.json provider block and config.toml top-level defaults/scope) backed by stash.json. Custom fields within providers.magpie are preserved during sync, and the original provider block is restored on disconnect. A renamed provider's magpie/<old>/ entries in enabledModels follow it, a glob or a thinking level included, and the scope remembered for disconnect follows too; the user's other entries stay. Disconnect restores original defaults, preserves user native changes and custom scope edits, and removes newly created files only when empty.
  • MothX's folder is $MOTHX_DIR as it is (no ~), else %APPDATA%\mothx on Windows, else ~/.mothx; a WSL distro's is its ~/.mothx (mothx.go). Its thinkingFormat is openai unless the user set one: with it empty, MothX picks Qwen's enable_thinking, DeepSeek's thinking or Doubao's levels by the model id, which for magpie's ids says nothing of the vendor that serves them. MothX's /model and /statusline … global rewrite the whole file, so Disconnect after one takes out magpie's provider, the pick and a providers left empty (MothX omits an empty one), and keeps the rest.
  • PenguinHarness's file is $PENGUIN_HOME (else ~/.penguin/data, on Windows too) /<project>/.project_config.toml, the Project $PENGUIN_PROJECT_ID when it is a folder's name (agentenv.NotPaths, so a relative name isn't dropped as a path), else default_project; a WSL distro's is its ~/.penguin/data/default_project (penguin.go). Magpie's models are [[models]] array entries with provider = "magpie", replaced together where the first one was by edit.SetTOMLArrayTables, which leaves the user's entries, the blank lines between them and the file's time alone when nothing changed (Penguin's server reads the file again on every mtime change). default_model is spelled { provider = …, model_id = … } as Penguin's own writer (smol-toml) spells it; that writer rewrites the whole file, so Disconnect takes out magpie's provider, entries and a vision model on them rather than putting back a copy. A default naming no entry is refused by Penguin, so entries go in before default_model and out after it. PenguinHarness's desktop app (PenguinHarness.app, bundle id com.prismshadow.penguinharness; on Windows PenguinHarness\PenguinHarness.exe under %LOCALAPPDATA%\Programs or the folder its installer registered, desktopApps) runs its server on the same root and needs no CLI, so with it installed the agent is detected before the app is first opened (sign) and never shown as gone; Connect then writes default_project, which the app's server adopts without overwriting (rankyurky_80676 on Discord, TestPenguinDesktopAppDetected, TestPenguinDesktopOnlyConnects).
  • CodeBuddy is one row for the CodeBuddy Code CLI and the CodeBuddy IDE (Tencent's VS Code fork; 4.12.2's CodeBuddy.app, com.tencent.codebuddy, from codebuddy.ai, and CodeBuddy CN.app, com.tencent.codebuddycn, from codebuddy.cn; both are desktopApps["codebuddy"], the second as one of its more builds) (codebuddy.go). The IDE's genie extension (CustomModelsProductProvider, with CustomModelsJSON on in its product.json) reads <home>/.codebuddy/models.json, the file magpie writes for the CLI, skips an entry without a string id and url, takes availableModels as a whitelist when it has one, and lists each model in its own picker; it ignores $CODEBUDDY_CONFIG_DIR and settings.json's model. With only the IDE installed the row is detected (sign), shows the IDE's version and is never "CLI not found" (bjzhangwn on X; TestCodeBuddyIDEIsCodeBuddy, TestCodeBuddyIDEReadsMagpieModels). The IDE's Windows and Linux install folders aren't known, so there it is found by ~/.codebuddy alone (never gone on Windows, as every desktopApps agent).
  • Zoo Code's provider profiles are in VS Code's secret storage, so magpie writes a settings file for it (magpie-import.json in Zoo Code's globalStorage/zoocodeorganization.zoo-code/settings, not magpie's folder, so a sync keeps an address the user moved it to) and points Zoo Code's zoo-code.autoImportSettingsPath at it in VS Code's settings.json and each profile's, a user's own path stashed and put back (zoocode.go). Zoo Code imports it on each start (importSettingsFromPath), merging it over the user's profiles and making magpie the current one. Disconnect stops the import and deletes the file; the profile already imported stays in Zoo Code, where magpie can't reach it.
  • An agent is detected by its config file, its folder, or its command on magpie's PATH (Detected). That PATH is the login shell's plus the folders users' tools go in (proc.UserPath: ~/.local/bin, npm's prefixes, the Node nvm's default alias resolves to (the highest installed when it names none), bun, Homebrew, ...; on Windows the registry's PATH plus the Node fnm's default alias names, %APPDATA%\fnm\aliases\default or under FNM_DIR, which fnm puts on a terminal's PATH from the shell profile and never in the registry, #2685), so a CLI a terminal doesn't find can still be found and listed: an npm install under a Node the terminal no longer uses. /api/agents/cli then gives where it is (path) and offPath when the login shell's PATH (proc.LoginPath) lacks its folder, and the Agents row says "Not on your terminal's PATH", its tip naming the file (悠悠哥 on Discord: Codex 0.162.1 listed with no codex on PATH and no ~/.codex). An unknown login PATH says nothing. A folder another tool writes too doesn't count (dirShared): Pi's for omp, ~/.copilot for the Copilot CLI, which GitHub Copilot's JetBrains and VS Code plugins also write, and Qoder's and Qoder CN's, which Qoder's JetBrains plugin fills, and ~/.cursor for Cursor CLI, which the Cursor editor makes on its own (TestCursorFolderFromTheEditorIsNotTheCLI, @G_Z_Y on X); only cli-config.json or cursor-agent finds Cursor CLI. A command another app ships under the agent's name doesn't count either: VS Code forks put a code launcher in their own bin folder (Cursor; Qoder IDE beside qoder), which their Windows installers put on PATH, so a code, code-insiders or codium counts as VS Code, Insiders or VSCodium only when the product.json beside it names that build (applicationName), or names none (vscodeCodeBinary; ggbr on Discord: Qoder IDE listed as VS Code too, TestVSCodeDetected, TestVSCodeBuildLauncher). A config file another tool writes first counts only when pathOwn says it is the agent's: Qoder's settings.json holding enabledPlugins alone is the plugin's (qoderPluginOnly; #1495, TestCopilotFolderFromAnIDEPluginIsNotTheCLI, TestQoderSettingsFromAnIDEPluginIsNotTheCLI). The Qoder app (the desktop app, which runs Qoder's CLI as its agent with the same folder) is found by the .qoder-app-status.json it writes there (sign, qoderApp; #2138, TestQoderAppIsQoder), as its settings.json can be its bundled plugin's enabledPlugins alone. Only the GUI and daemon install widen the PATH so; magpie serve, web, tui and the CLI keep the one they were started with, so an agent's CLI (cliBin, which its version and omp's max effort are read from) is looked for in those folders (proc.FindTool) on every system when it isn't on the PATH, not only on Windows (whqtian on Discord: omp under ~/.bun/bin on Ubuntu read as no version and offered xhigh in place of max; TestOmpVersionOffPath).
  • Detection goes by an agent's folder, which an uninstall leaves behind, so an agent found by that alone is shown as gone (CLIMissing; #843, #2177, #2173): its CLI is on no PATH and in none of proc.FindTool's folders nor where its own installer puts it (~/.claude/local, ~/.codex/packages/standalone, ~/.opencode/bin, Hermes' hermes-agent checkout), and nothing else that reads the folder is here (cliHeld): its desktop app (HasApp), an editor's extension (~/.<editor>/extensions/<id>-*: anthropic.claude-code, openai.chatgpt, saoudrizwan.claude-dev), Claude.app, OpenCode.app and Goose.app on a Mac, a JetBrains IDE's settings (its AI Assistant's agents and Cline's plugin) or Zed's external_agents (its Claude Code and Codex adapters). Where magpie can't tell (every shared folder, cliShared, on Windows, whose readers can be a Store app, a portable editor or a PATH only a shell profile sets, #1482, and there too one a desktop app of the agent's reads, desktopApps: DeepSeek Harness Desktop installs to any folder and puts its dsh.cmd in one the user picks, #2300, #2304; OpenCode and Goose off a Mac, Gemini, an agent detected its own way or by a command name other tools share, one with no install command but cliOnly's Hermes), it is never gone. A gone row in the GUI shows "CLI not found" and none of its settings, nor Apply again; while connected it keeps its switch and Disconnect, and it folds under Not set up once not. Get started never offers it (connectKind is "no"). The TUI leaves it out and magpie ls says "CLI not found" (TestCLIMissing*, agent-cli-missing.test.cjs, getting-started.test.cjs).
  • Tests never touch the real machine. TestMain uses testenv, which points HOME, USERPROFILE, the XDG folders and APPDATA into a temporary folder, clears agentenv.Vars and puts failing stand-ins for keychain tools and agent CLIs on PATH. Agent-specific side effects (Aside, the Zed keychain, Codex's usage check) are also stubbed in TestMain.
  • Pi, OmO and Prime Agent write a Gemini-capable model as google-generative-ai at the gateway's /v1beta (piModelJSON in agents.go); each one's Google client takes the version path from baseUrl (pi-ai's and senpi-ai's apiVersion = "", Prime Agent's pa-ai providers/google.rs). StepCode keeps such a model on Chat (stepcodeProvider): it registers no google-generative-ai stream, only anthropic-messages, openai-completions and openai-responses (Step-Code packages/providers/src/compat.ts), though its docs list it. magpieModels in route.go includes Gemini and Code Assist capabilities when no native Chat, Responses or Messages API was selected; this includes a plugin model declaring @ai-sdk/google. Requests keep going through the gateway and the plugin's sign-in and fetch, with the gateway's usual translation where needed. A normal model sync updates existing entries. Routing groups retain their existing API choice, and Pencil remains on Chat. Pi resolves a level there to one of Gemini's four (minimal, low, medium, high) and throws on any other, so a level the model names otherwise is set to null in thinkingLevelMap (TestPiGoogleThinkingLevelsAreGeminis).

Verification

go test -tags nogui ./internal/agent -run '^TestStepCode'
go test -tags nogui ./internal/agent ./internal/update ./internal/cli -run 'TestAgy|TestShellFunction|TestWithFnBlock|TestShellProfiles'
node --test internal/gui/tests/agy-launch.test.cjs
go test -tags nogui ./internal/agent -run 'TestPiModelsAskedOnTheirNativeAPI|TestPiGoogle'
go test -tags nogui ./internal/agent -run '^TestMothX'
go test -tags nogui ./internal/agent -run '^TestPenguin'
go test -tags nogui ./internal/agent -run 'TestClaudeAutoModeReview|TestClaudeReviewedOnlyWhereMessagesReachClaude|TestT3CodeAutoModeReview|TestConnect|TestDisconnect|Drift|TestKeptAddress|TestWSLAgentAddress|TestReachProbe|TestDryRunKnowsTheAskersProviders|TestReseat|TestPort|TestWSL|TestClaudeKeepsItsClaudeAISignIn|TestClaudeSignIn|TestClaudeOwnEndpointWithAnEmptyKey|TestClaudeAtAnOlderGatewayAddress'
go test -tags nogui ./internal/agent
go test -tags nogui ./internal/agent -run '^TestAir'
go test -tags nogui ./internal/agent -run 'TestReverseProxy|TestClaudeManagedProxyIsStillMagpie|TestMagpieProbe|TestCodexBehindReverseProxy|TestCodexSignedInBehindReverseProxy|TestAwayPath|TestClaudeBehindLocalProxyKeepsIt'
go test -tags nogui ./internal/agent ./internal/edit -run 'TestSyncKeepsAnAddressOnAnotherMachine|TestKeptAwayOnlyWhatIsSure|TestKeyValuesFormats|TestFilteredWrites|TestOwnWritesDuringASyncWithALinkedConfig'
go test -tags nogui ./internal/edit -run 'BOM|CRLF|JSONC|TrailingComma|LoneComma'
go test -tags nogui ./internal/library -run TestHubToggleKeepsOpenCodeJSONCValid
go test -tags nogui ./internal/agent ./internal/proc -run 'ClaudeCloud|TestT3CodeSaysAClaudeCloudSwitch|TestLoginEnvClaudeProvidersNotSet'
go test -tags nogui ./internal/agent -run '^TestAnte'
go test -tags nogui ./internal/agent -run 'AionUi|Cindy'
go test -tags nogui ./internal/agent -run 'AppLink|CommandProgram|SystemLinkHandler'
go test -tags nogui ./internal/gui -run 'TestAionUiImportRow|TestImportStatusUnreadableIsUnknown|TestLodyImportHandoff|TestImportLinkNothingOpens'
go test -tags nogui ./internal/cli -run 'TestImportAddSaysNothingOpensIt'
node --test internal/gui/tests/import-row.test.cjs
go test -tags nogui ./internal/agent -run '^TestAstrBot'
go test -tags nogui ./internal/agent -run '^TestJcode'
go test -tags nogui ./internal/agent -run '^TestOpenClaw'
go test -tags nogui ./internal/agent -run '^TestRaycast'
go test -tags nogui ./internal/agent -run '^TestKiroCrew'
go test -tags nogui ./internal/agent -run '^TestOpenPencil'
go test -tags nogui ./internal/agent -run '^TestNewMax'
go test -tags nogui ./internal/agent -run '^TestGrokApp'
go test -tags nogui ./internal/agent -run 'ClaudeScience'
go test -tags nogui ./internal/gateway -run 'TestClaudeScience'
go test -tags nogui ./internal/agent -run '^TestPlugged'
go test -tags nogui ./internal/agent -run 'TestCodexFailoverOnlyKeepsOwnModels|TestCodexOwnModelThroughMagpieWhileAccountsOn|TestCodexHandWrittenBaseURLStays|TestCodexProxyFor|TestRealProxyProbe|TestCodexEnvTakesLoginShell|TestCodexFailoverHeldWhileProxyDoesNotPassOn|TestCodexProxiedDrift|TestCodexFailoverEndsWithMagpie|TestCodexMirrorFailoverHeldAndEndsWithMagpie'
go test -tags nogui ./internal/agent -run 'TestDisconnectStaysThroughSync|TestCodexDisconnectStaysWithAccountsOn|TestCodexAPIDisconnectStays'
go test -tags nogui ./internal/tune ./internal/agent -run 'TestCompact|TestCacheTTL|TestTune'
go test -tags nogui ./internal/sessions -run 'CompactTook'
node --test internal/gui/tests/context-tune.test.cjs internal/gui/tests/compact-one-value.test.cjs
node --test internal/gui/tests/agent-connect.test.cjs internal/gui/tests/agent-disconnect-preview.test.cjs internal/gui/tests/claude-signin.test.cjs internal/gui/tests/agent-failover.test.cjs internal/gui/tests/agent-proxied.test.cjs internal/gui/tests/plugin-agent.test.cjs

Lody import handoff

lody.go detects Lody by its home folder (~/.lody, ~/.lody-oss) only when it holds an entry Lody makes there (workspace-catalog.json, loro-repo, agent-binaries or code-collab-v2), so a bare folder of that name another tool made isn't Lody; by its Electron data folder under the OS's config folder (Lody, Lody OSS, Lody Nightly: ~/Library/Application Support, %APPDATA%, ~/.config); or by a macOS bundle whose id starts ai.lody. (the real app is ai.lody.desktop). A Windows or Linux install that has never been opened has no data folder yet and isn't shown. Its row opens lody://provider/import?v=1&data=<base64url JSON> with the Magpie envelope and seven runtime targets. Only loopback HTTP gateways are offered; the key is always the public attribution token magpie-lody, never a LAN secret. With MAGPIE_ADDR pinned beyond loopback there is no link: the row has no button, and magpie lody add says why and opens nothing (TestLodyLinkCarriesNoSecret). On macOS and Windows the OS chooses the installed Lody handler: Lody's bundle and installer claim lody://. On Linux agent.OpenLody runs Lody itself with the link, as its desktop entry's Exec says (ai.lody.desktop.desktop, then Nightly's ai.lody.desktop.nightly.desktop and OSS's dev.loro.lody.oss.desktop, in $XDG_DATA_HOME/applications before $XDG_DATA_DIRS): Lody's AppImage writes that entry at each start but makes itself the default only for its channel's scheme (ai.lody.stable), so lody:// reaches it only through a desktop database that nothing builds without update-desktop-database, and xdg-open's gio answers "Operation not supported" while Lody runs (Atlas, 10-25). A second Lody hands the link to the running one. With no entry whose program is there, the link goes to xdg-open as before (TestOpenLodyRunsItsDesktopEntry, TestLodyImportRunsLodyOnLinux). The web page opens the link from the browser and is not covered. A compatible Lody build must implement this import route.

Lody asks which Providers to add, names them with -magpie, and writes only to the current desktop's local machine after confirmation (Lody 0.108.1: the import's machine is always the desktop's own, and its link names no other). So a machine Lody Desktop reaches as a remote, one that runs only Lody's command-line agent, takes no import from magpie running there: nothing on it opens lody://, and a link opened on the desktop's computer would point that computer's agents at its own loopback. Lody Desktop opened on that machine itself shares the agent's ~/.lody/machine-id, so the import lands on the same machine (Atlas, 10-25). Magpie does not read or write Lody's private document store, select models there, or claim that opening the link completed the import. Lody exposes no public status reader: Agent.Added remains nil and the JSON row omits added. The GUI shows a confirmation hint for this unknown state; Cindy still reports its known true/false status. Added returns (added, known): Cindy's databases are read without writing beside them (sessions.OpenUntouched, immutable with no WAL log, from a copy with one; a plain read-only open made -wal and -shm in Cindy's folder while it was closed), and one that can't be read, or a stopped WSL distro's, is unknown, never "not added" (TestCindyHasClosedWALAndUnreadable, TestImportStatusUnreadableIsUnknown). Reopening the link lets Lody handle duplicates. Bub requires its separately installed ACP plugin.

Whether anything opens an import link

Windows' rundll32, macOS' open and xdg-open are started and not waited on, so an import link that nothing here opens (the app never registered its scheme, or the program it registered is gone) did nothing at all, and nothing said so (sungt, 10-29: Cindy's Add magpie on Windows "spins, no response"). applink.go's agent.OpenAppLink asks the system first, without opening anything: Windows reads HKEY_CLASSES_ROOT\<scheme>\shell\open\command (what Electron's setAsDefaultProtocolClient writes) and then the user's UrlAssociations\<scheme>\UserChoice; macOS asks Launch Services (LSCopyDefaultApplicationURLForURL, cgo builds only); Linux asks xdg-mime query default x-scheme-handler/<scheme>. Only "none", or a registered program whose full path isn't there, refuses the link with agent.NoLinkHandlerError; a key with no command of its own (a packaged app's), a bare program name, KDE's empty answer, no xdg-mime, a build without cgo or a failed read is unknown, and the link is handed over as before. /api/open checks Cindy's, AionUi's and Lody's links this way (Lody's after agent.OpenLody's desktop entry), and fail answers code: "no_link_handler" with app, exe and said, an i18n.js key from linkSaid (the one with ({exe}) when a gone program is named), which api() puts through t() with the reply's fields, as it does bunSaid's. The Agents page's import button awaits the call and says what came of it: "Sent to {name}: confirm adding magpie there" (handed over, not seen to open), that reason in the reader's language, or any other error's own text. magpie <app> add returns the same error instead of "✓ opened" (TestOpenAppLinkSaysNothingOpensIt, TestSystemLinkHandlerNoSuchScheme, TestImportLinkNothingOpens, TestLinkSaidIsTranslated, TestImportAddSaysNothingOpensIt, import-row.test.cjs). Whether the app then shows its confirmation is the app's own and is not read.

AionUi add-provider link

AionUi (internal/agent/aionui.go) keeps its providers in its own SQLite database, <userData>/aionui/aionui-backend.db in WAL mode, with each key encrypted, so magpie has no file to write there. Its row is the link that AionUi 2.2.2's main process parses (parseDeepLinkUrl) and its renderer sends to Settings → Model, where the add form opens filled in for the user to confirm:

aionui://add-provider?api_key=<agentKeyAt("aionui")>&base_url=<gateway>/v1&name=magpie&platform=custom

custom is AionUi's OpenAI-compatible platform, and its OpenAI-compatible base URLs end in /v1. TestAionUiLinkParsedAs2_2_2 runs the link through the parser copied byte for byte from 2.2.2's app.asar (testdata/aionui/deeplink-2.2.2.js). userData is os.UserConfigDir()/AionUi on every OS. Added reads providers.base_url for the gateway's address untouched (sessions.OpenUntouched), from the real 2.2.2 schema (TestAionUiHas). It keeps the last read while the database and its log keep their size and time, for 15 seconds at most. A database it can't read is unknown. Released 2.2.2 asks for an aionui.com sign-in before any page, Settings included, so the form, the saved row and gateway traffic have not been tried end to end. As with Cindy and Lody, the TUI leaves the row out because there is nothing to pick. magpie aionui add opens the link.