Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.
GUI app shell
The desktop app has a tray (menu bar) icon whose click drops a compact
panel, and a regular window. Both show one small web UI served from
embedded assets. The page talks to Go over a JSON API on the same handler,
with no binding generator and no bundler. magpie web serves the same page
to a browser for a machine with no desktop. Package internal/gui hosts all
three.
Responsibilities and sources of truth
| Part | Responsibility | Source |
|---|---|---|
| Native host | Run starts the Wails v3 app: the tray icon, the panel, the main window, single-instance handover, magpie:// import links and open at login. host implements Windows for the API: show and hide, open URLs and folders, copy to the clipboard, fit and tint the panel, and set the text size. A copy on Linux sets PRIMARY before CLIPBOARD, since GTK 3 serves CLIPBOARD empty when PRIMARY is set after it on a compositor with no primary selection (KDE Plasma with middle-click paste off, #1881); on Wayland the copy is read back through the compositor, and one that doesn't read back whole answers /api/copy with 501, so the page tries its clipboard API, then the copy command, then says the copy failed with the text to copy by hand (copy-fallback.test.cjs). |
app.go, clipboard_gtk3.go, clipboard_gtk3.h, mainwindow.go, traymenu.go |
| Backend | startBackend starts the gateway this process serves, unless another magpie already serves it. In that case this process only shows the other one's status (gw is nil). stopServing drains requests in flight. A restart to update can hand the listening socket to the new version instead (see A restart to update hands the gateway over). |
backend.go |
| API and assets | Handler serves assets/ (embedded with //go:embed assets) and the /api/* routes, such as /api/state, /api/set, /api/agents/{action}/{id} and /api/agents/restart/{id} (a desktop app's Restart, after the row's confirm). held lets one API request's reads share one catalog build (provider.Hold), and drops it after any write. revalidated and versionedPage name each script by its content hash, so a cache never serves an old app.js under a new page; a file asked for under its current hash (?v=) is cached for good (immutable), anything else is revalidated by its ETag. |
api.go |
| Browser mode | StartWeb serves the page and the gateway for magpie web. The browser signs in with a run key in a link. Added to a phone's home screen the page opens as an app of its own, with no browser bars (ninja_s6114 on Discord): index.html names manifest.json (display standalone), an apple-touch-icon and the iOS meta tags, the status bar keeps its own ground (default), and its theme colours match only (display-mode: standalone), so a browser's tab and the app's windows take none. webGuard serves those three files (webAppFiles: the manifest, icons/apple-touch-icon.png, icons/icon-512.png) without the key, to GET and HEAD at those exact paths alone, as a home screen may ask without the cookie; see TestWebAppAddsToHomeScreen and web-app-standalone.test.cjs. Gateway mode shows Providers, Gateway, Routing, Usage, Sessions, Plugins and Settings on a machine that is only a gateway. webHandler gzips the page's text files and the API's JSON for a browser that takes gzip (webCompressed, with a -gzip ETag that still answers 304; never an event stream, which gzip would hold back until its buffer fills); the app's own windows read the page in-process and get it uncompressed. The page's port answers the gateway's client routes too (onePort, gateway.ClientPath: /v1/…, /v1beta/…, /mcp/…, the Codex backend path and the routes without /v1; never /api/* or /_magpie/*, never a path that isn't clean), so one reverse-proxy location serves the page and the agents (zgcwkj on Discord). They skip the page's key and gzip and go to the gateway's own guards, always as a request from another machine (gateway.FromPagePort, the X-Magpie-Page-Port mark: local is false for it, from loopback too and under MAGPIE_TRUST_PROXY, so magpie must be shared and the request carry an enabled gateway key), since a raw TCP forward or a proxy that adds no forwarding header reaches this port from loopback looking like an agent here (reported privately by Coffemon); agents here use the gateway's own port. Server.Front (lanGuard over Handler) serves them in process when this process serves the gateway, or toGateway, a reverse proxy to gateway.URL(), when another magpie does; it keeps the Host, the forwarding headers and the mark, adds X-Forwarded-For for a peer that isn't loopback, and the peer's loopback address as X-Forwarded-For when none came, so a gateway of an older magpie that doesn't know the mark still asks for a key. lanGuard moves the mark into the request's context and takes the header off, so it never goes upstream. The page itself calls no client route. See TestWebOnePortServedHere, TestWebOnePortServedElsewhere, TestWebOnePortAgentsHereUseTheGatewayPort, TestPagePortMarkIsNeverLocal and TestClientPathCoversHandler. |
web.go, gatewaymode.go, oneport.go |
| The app's page in a browser | Settings › Network and sharing › Browser access (renderWebPage in plugins/gateway/settings.js, drawn with the Web pages rows) has the app serve its own page to a browser while it runs, so a tunnel (Cloudflare Tunnel, SSH) or a computer on the network can reach it without magpie web kept running in a terminal (jiakun_zhao on X). Off, This computer (127.0.0.1, which a tunnel's service points at) or Local network (every address; a "Not encrypted" row without --tls-cert). It is magpie web's page and guard, not a second kind: startAppPage (from Run, after startBackend) serves webServed over a Handler of its own, whose Windows is appWebHost (a browser tab for isWeb, but not ownWeb, so the app's windows aren't taken for magpie web's: webPage and gateway mode stay the app's; quitting quits the app, and a restart to update from it brings back the windows the app has up, restartFrom). The key is always asked for: no mode serves without it. It lives with the mode and port in web-page.json beside settings.json (0600, never in settings.json, so sync and backup don't carry it), is made the first time the page is turned on, kept across restarts (a browser's cookie stays good), and replaced by New key, which turns away every browser signed in with the old one (the guard is swapped atomically, appPage.cur). A file that can't be read, or names no known mode, is off and says why; Settings rewrites it only given a whole choice. A port another program holds (magpie web; the magpie before a restart to update) is said and tried again every 4 s (appPageRetry); the port must be 1024 up and not the gateway's. GET/POST /api/web-page are on the app's own windows' API only, never a browser's, so a browser on the page can neither read the key it came in without nor turn the page off under itself. magpie web on the port the app serves prints the app's link and opens it rather than starting a second (gui.AppPage, samePort). Sessions are warmed once a process however many Handlers there are (warmOnce). See TestAppPageServesOnlyWithItsKey, TestAppPageWaitsForABusyPort, TestAppPageUnreadFileServesNothing, TestAppPageTurnsDownBadChoices, TestAppPageBrowserIsATab and browser-access.test.cjs. |
apppage.go, web_cli.go |
| The page | app.js keeps one state object per view and renders it into a list, with no framework. The views have their own files: plugins.js and context.js, and those a plugin adds under assets/plugins/<id>/ (the Gateway, Sessions, Library, Routing and Usage pages, see plugin runtime) (Usage's Context tab, and the context window card the Routing page draws under a request's story, fed by /api/context in context.go, which scores and tags each agent; clicking a part, a cell or an item opens its text from /api/context/text, the last 10 requests' masked bodies in memory (openCtxText), rendered 100 items and 20000 characters at a time; its "Tuned for you" cards are fed by /api/tune in tune.go, see agent wiring). Strings go through t() with translations in i18n.js, and a plugin's own in its i18n.js (zh, zh-TW, ja and de; the English text is the key and the fallback). zh-TW is Traditional Chinese with Taiwan's words; a system language of zh-TW, zh-HK, zh-MO or any zh-Hant picks it, and the tray menu and notifications follow (trayLang). Dropdowns use openProtoMenu. Every app menu (openProtoMenu, openRowMenu, openSessCombo) is placed by placeMenu: under its anchor, or over it when the window runs out below; one that fits neither way takes the larger room, its height held to it, and scrolls inside itself, and a scroll inside a menu doesn't close it (#1437, removed-groups-menu-scroll.test.cjs). The highest any popover goes is popTop: 8px under header.top on a Mac window, where the traffic lights are drawn over the page, and 8px from the top elsewhere; placeMenu, the field picker's placePop (which also holds #pop's height to that room) and an agent's model list (openAgentModels) all use it (#1573, popover-mac-chrome.test.cjs). Scrolling is done only by scrollOnPurpose(e) with the reader's event. |
assets/app.js, assets/i18n.js |
| Window navigation | In the window from 1024 points wide (SIDE_AT, the same width as app.css's side-nav rules), layoutNav moves the brand, the pages (#nav) and Settings into the sidebar (#side): the pages in four groups (Work, Models, Insights, Extend; a group none of whose pages shows, as in gateway mode, leaves out its name), the gateway's address at its foot (sideGwRead, read from /api/providers only while there is a sidebar, or drawn at once from boot.js's sideGateway; on a page other machines open, magpie web, it is MAGPIE_PUBLIC_URL while they are let in, as the Gateway page's address and About's Gateway URL are, noahhrreion on Discord; a port applied in Settings redraws it), and the header a breadcrumb (renderCrumb). A page whose head holds only its tools (Library, Plugins, Settings) has them in the title bar after the breadcrumb, tools setting the room between it and the window's own buttons. When they don't fit there the tools show their icons alone (tools-tight; each keeps its name as aria-label and in its tooltip), then the breadcrumb drops its leading parts, and last the page's name is cut at its end, so no tool lies over the title (#2625, title-bar-tools.test.cjs). The open page's own tabs (NAV_SUBS: Usage, Library, Plugins, Settings) are listed under it as .nav-s rows (role="tab", data-of the page tab's id) and the page's strip is hidden; a row's click clicks that tab at once, the selection (.nav-hl) having set off as the row was pressed (navSubGlide; back if the press leaves the row), and is the list's only shape: a row hovered or pressed has no ground of its own, and a MutationObserver draws the list again when the strip changes. A page's tabs share its one scroll, so a row that picks another tab opens it at its top (scrollOnPurpose with the row's click); the tab already open, picked again, leaves the page where it is (sidebar-tab-top.test.cjs). The list opens and folds with an iOS-like spring (navSubEnter, navSubLeave; none under reduced motion), and a folding list is out of reach at once. The open page's own row is marked the same way, by one shape (.nav-top-hl, the rows' own ground given up to it, hovered or pressed too) that navTopGo moves to the row picked on a damped spring, as iOS moves a selection (NAV_SPRING, SwiftUI's response 0.42s and damping 0.84; navTopStep steps it each frame): it sets off as the row is pressed and comes back if the press leaves the row or the page isn't left, turns with the speed it has when the press changes its mind, and follows its row while the list above it folds, landing where the row ends up. It is put in place, not sent, when the window opens on a page or the rows move under it at rest (a ResizeObserver), is away while Settings is open (it has its own selection at the foot), comes back fading in on its row, jumps under reduced motion, and isn't drawn in the header's tabs, which have their .thumb. #nav is position: relative in the sidebar for it, so .seg's centring left and top are reset. See sidebar-glide.test.cjs. Narrower, the page beside a sidebar would be narrower than Usage's requests table needs (768 points), so they go back into the header's row, as a Mac sidebar gives way in a narrow window. At every width the reader can pick the sidebar or the header's tabs from the title bar's button (#sideToggle, ⌃⌘S or Ctrl+Shift+S; toggleSideNav), kept in localStorage magpie.navLayout (side or top) and so laid out from the first frame; none picked, the sidebar comes from SIDE_AT. Picked in a narrow window the sidebar is narrower (184 points under 860), and magpie web on a phone keeps its own tab bar and has no button. The two layouts trade places in a view transition (navMorph, app.css .nav-morph): the sidebar slides, each page's tab flies to its place in the other, and the page slides as one (its old image dropped, so no line prints twice); without view transitions, under reduced motion, or in the Linux app the change is at once: WebKitGTK with compositing off (WEBKIT_DISABLE_COMPOSITING_MODE, which webkit_linux.go sets under Wayland) crashes in a view transition. Elsewhere a transition still going after MORPH_MAX (1.5s) is skipped, so a webview that never ends one can't leave the window on the old layout's picture. See side-toggle.test.cjs. A window made wider or narrower drops what a click held (heldWidth): the page laid out again isn't the click's doing. The reader's own place is kept instead for a second while the page is laid out again (relaid, a ResizeObserver on the open page's parts calling backToReader): crossing SIDE_AT the browser clamps the scroll to each layout it passes through, and the page ended short of its foot (#1672, text-size.test.cjs). See sidebar.test.cjs. A sidebar longer than a short window keeps no scroll bar beside its pages: the native bars of .side-scroll and .side-foot are hidden, and sideBars lays a thin bar over each box's edge that shows while it scrolls, fades about a second after it stops (kept while hovered or dragged), can be dragged or clicked to page, and is gone when the box fits, the same in WebKit, WebView2 and WebKitGTK. See sidebar-overlay-scrollbar.test.cjs. The window opens on the page the reader last left, as a Mac app comes back as it was (molvqingtai and lc on Discord): show keeps the page in localStorage magpie.lastView (which the app's webview keeps across restarts, as it keeps magpie.navLayout), and keptView opens it at start. A page asked for in the address (?view=, the tray's links, a reload) wins, Agents too; a kept name that is no page opens the first page, and one gateway mode leaves out opens Providers (show). Opening on it scrolls nothing. See last-page.test.cjs. |
assets/app.js, assets/app.css |
| Settings › Privacy | The page opens on what masking kept from vendors (drawMaskObs in app.js, fed by /api/masking/summary): the values masked over 7 or 30 days with a chart of the days, the kinds, what only the local model found, agents to providers, and the values masked most, each shown only while pointed at (maskTip, /api/masking/value, which says it is gone after a restart). Its records (drawMaskRecs, /api/masking/records and /api/masking/record) take the page's place, filtered by kind, finder, agent or provider, a day at a time, each opening on the text the vendor saw with its placeholders marked. maskedBadge, on the Gateway page's recent calls and the Routing page's log, opens a request's own record (openMaskRecord), in amber with the count sent as written when every value found was on Warn. Below the card, What to mask, How it's found (the rules, always on while anything is masked, and the local model on top of them), When a value is found (Mask, Warn or Block per kind, the secret kinds first and the personal ones behind Show all kinds, and the Never mask list; renderMaskActions), Try it (renderMaskTry, the text as the vendor would get it from /api/masking/preview, kept in no storage) and Sharing. Agents' session history (renderSessionReads, read from /api/sessions/reads only while the Privacy part is shown) has Agents found later and a row per agent found, the choice the Sessions page asks first on a fresh install; see gateway sessions. While anything is masked, Instead of masking, send to (redactRouteRow in plugins/redact/settings.js, the redact plugin's part of Settings, which wraps renderRedact so app.js carries none of it) picks, in the app menu, a model a request masking would change goes to as written: Off by default, and only the models /api/settings lists as maskRouteModels (every route of theirs unmasked, gateway.MaskRoute), saved with POST /api/settings/redact-route (redact-route.test.cjs). See gateway routing for what is recorded. |
assets/app.js, masking.go |
| Built-in plugins | Plugins › Built-in, the page's first tab (drawBuiltin in plugins.js, rows by renderBuiltins in app.js), lists magpie's built-in plugins, each with a name, a line on what it is and a switch: Routing groups, Library, Observability, Sessions, Warm-up and check-in, and the Gateway and Routing pages (Essential). A plugin on with settings has their rows under its row, drawn from its schema by the kernel's ui.form, and a change posts {id, config}. The Gateway page is drawn by its plugin's own scripts through the window's kernel (kernel.js, assets/plugins/gateway/); see the plugin runtime, "The window's kernel". They are plugins/* registered with the plugin runtime; GET /api/plugins/builtin says each one (builtinJSON: on is active, the user's own choice, what of it is in use) and POST {id, on} (or {id, config}) writes plugins.yml. A page marks what goes with a plugin data-feature="<id>". Off, featureStyle hides everything so marked (rows drawn later too), navHides leaves its page's tab out of the sidebar and the header, show opens Agents for an address kept for it, and setSetTab, partShows and findSettings leave its Settings tab and rows out, of the search too. One in use stays on: its switch is disabled and the row says what uses it, and the POST refuses it off. A plugins.yml that doesn't parse is said above the list and no switch moves. boot.js says which are off (featuresOff) and their settings (pluginConfig) before the first paint, and settings.builtins carries the list on every state read. The TUI doesn't follow them. See builtins.test.cjs, builtins_test.go. |
builtins.go, assets/plugins.js, assets/app.js |
| No GUI build | -tags nogui builds magpie without the GUI: hasGUI is false and runGUI says to use magpie tui. The files of internal/gui that need Wails build under !nogui. |
gui_off.go |
| The terminal quitting | magpie tui that served the gateway with an agent connected hands the gateway on as it quits, on Linux where nothing opens magpie at login (a WSL distro, a server over SSH; zaidu259434 on X): keepGateway starts magpie's service when it is installed, installs it (daemon.Install) when the user never removed it (daemon.Removed, a mark magpie daemon uninstall leaves), and otherwise starts magpie serve in its own session (serveInBackground, log in magpie's cache). Elsewhere, with nothing connected, or where magpie opens at login, it only says the gateway stopped. |
keep.go |
Runtime path
magpiewith no arguments,magpie appormagpie traycallsrunGUI, which callsgui.Run. Anoguibuild runs the TUI instead. A second launch hands over to the instance already running. On Windows, before any window is made,webView2Checkasks Wails whether the WebView2 runtime is there (Env.Info().PlatformInfo["WebView2"], "" when its lookup fails; a key Wails doesn't set counts as there). Without it Wails would exit on the first window with nothing on screen, so magpie logs it, shows a Windows message box in the reader's language naming the runtime, Microsoft's download page (webView2Page) andmagpie web/magpie tui, opens the page on Yes, andRunends (#1806,webview2.go,TestWebView2MissingFromWailson Windows). The box can't come fromErrorHandler, which runs on the thread Wails makes its windows on.startBackendbrings up the gateway, or finds another magpie serving it.- The panel and the window load
index.htmlfromHandler.boot.jspasses the saved language, theme, colorblind mode, text size and desktop font choices before the first paint. - The page reads
GET /api/stateand writes throughPOSTroutes. Each write answers with the new state, built underheld. - Closing the window hides it. On the Mac a full-screen window first leaves full screen (
closeStep). The system's close on the panel (a title bar's X, Alt+F4, a window manager's close key) hides it as Escape does, so the tray icon opens it again; a panel lightweight mode let go, no longerh.panel, closes (makePanel,TestPanelCloseHidesIt). Lightweight mode lets go only of a window closed this way: one covered by another app's window, minimised, or open as magpie was hidden is still open (windowUp, not Wails'IsVisible, which is the occlusion state), and so is it for the Dock while the window is open and for a restart (#1381,TestCoveredWindowStaysUp). On the Mac the tray icon and a usage cell close an open panel by the same test (windowOpenintogglePanelNowandtrayCellClick, not Wails'ToggleWindow), so under a window over the whole screen, such as a remote-desktop server's privacy curtain, the icon still closes the panel instead of showing it again (#1661,TestTrayCellClickReleasedPanel). - The window opens as it was last left. Its settled size and whether it was maximised are kept in
settings.Windowandsettings.WindowMaximised(settle; per machine, seeKeepOwn). A maximised window keeps the size it restores to.makeMainopens it at that size (openSize). On its first show,placeMainmaximises it again on the Mac and Windows (on Windows once the page has come). On Linux,makeMainmakes it maximised withStartState. On Windows a size larger than the screen's work area is fitted and centred (fitRoom), and the larger size stays kept. The window's position is not kept. - The page's header is the window's title bar.
plainTitlebarsets it up once the app has started, and again on a window lightweight mode made again (madeAgain). On Linux it hides GTK's title bar and keeps the shadow and the resize edges; GTK 3 leaves the corners square. On the Mac the traffic lights are inset into the header (MacTitleBarHiddenInset). In the design of macOS 26 a window with a toolbar has larger corners than one with a plain title bar, soinsetLights(titlebar_darwin.go) takes the toolbar off, andMagpieLightskeeps the lights and the title bar's height where the toolbar had them: after a resize, a new title, light or dark, more contrast or less transparency, and leaving full screen. A sheet, such as the folder chooser, still begins below the title bar. A first press while another app is in front still moves the window from anywhere in that title bar (firstPress), as AppKit moved it with the toolbar; AppKit itself now does so only in a plain title bar's top 32pt. AppKit gives a program that design from macOS 26 when the program is linked against the macOS 26 SDK or a later one and its Info.plist doesn't ask for the earlier design (UIDesignRequiresCompatibility);designOf26reads each at run time, as the SDK depends on the toolchain that built magpie. The toolbar stays in the earlier design, where it doesn't change the corners, with the lights on the right (a right-to-left language), or when the title bar isn't laid out as expected; this is decided once, when the window is set up. In full screen the title bar is AppKit's own. Windows keeps its own title bar. - On the Mac, Settings › Show in Dock puts magpie in the Dock never (
DockNever), while the window is open (the default;DockWindowrecords it chosen, for an older magpie that took none for never) or always (Dock, which wins). The default was never until ShouguangCao on X found the open window out of Command-Tab, so going back to it to paste a key copied elsewhere took the menu bar; a new install (no settings.json) reads With window, and Hide is a choice of its own (inDock,dockChoicein app.js,TestDockFollowsWindowByDefault,dock-choice.test.cjs). A file written before that has nodockSettled, and stored Hide as nothing, so a user who chose Hide can't be told from one who never chose: such a file with no Dock choice reads as Hide, and the first save writes it so withdockSettled(settleDock,TestOlderSettingsKeepHide,TestNewInstallFollowsWindow). A file nobody can read reads the same way. The page never sendsdockSettled; the save keeps the file's (TestSettingsSaveKeepsDockReading). It is this computer's own, as the Dock choice is (KeepOwn). A full-screen window joins it whatever the setting (inDock,dockOnFullscreen).openMainjoins before it shows the window (setDockruns on the main thread at once). An app activated out of the Dock (the quick panel's focus) that then joins it stays last in Command-Tab's order though it is in front, so joining to the front activates magpie by way of the Dock (dockStep,activateAgain; #1381,TestDockStep,TestDockJoinLeadsCommandTab). It does so without asking NSApp whether magpie is active: the Mac makes it the front app at once, and NSApp says so only once the main thread has taken that in, after the join on a busy Mac (#1651).
Constraints and failure behavior
Allowance card refreshes
A card refresh applies only the requested account from the API's full
card list. A whole-page read begun before that refresh completed keeps
the newer card when its older response arrives; other cards still update,
and a later whole-page read can replace or remove the card. This also
keeps two different card refreshes from undoing each other's results.
If a refresh first supplies the account's name, its provider's cards are
replaced while newer card refreshes and other providers stay. The replaced
keys are protected too: an older whole-page response cannot restore an
unnamed card or erase its newly named replacement. Only a completed
whole-page read retires the ordering markers it no longer needs.
A remote magpie's summary can likewise become its namespaced child cards;
refreshing it preserves local providers and other remote magpies.
keepRefreshedQuotas and quotaRefresh in
app.js own this publication order;
quota-refresh-order.test.cjs covers held responses and failures, and
usage-card-refresh.test.cjs checks the real button in both browser
engines and all five languages. A cached readDeferred card says no
refresh was requested this time; a failed read retains its failure notice.
The tray panel's Allowances cards use the same quotaRefresh, at the
start of the line under the account (the reset deadline, the error, or a
balance's name), opened as the card is hovered or the button is focused.
That line names the deadline ("Resets 14:26"), so no bare ↻ stands for
it; renderPanelQuota puts the focus back on the button after the redraw.
panel-quota-refresh.test.cjs covers it in both engines, all five
languages, at 440 and 360px.
Redrawing the cards preserves their refresh controls and any running turn.
The reply updates the reading immediately; the icon then finishes its
current full turn before stopping (no rotation under reduced motion).
Streamed output speed
Usage rows and aggregates use Record.Decode and DecodeOf in
internal/usage/usage.go. Routing uses
decodeOf in plugins/routing/client.js; Usage
rows use ledDecode in plugins/usage/page.js.
When an answer follows reasoning, only answer tokens are timed from the
first answer text. Without answer text, all output tokens are timed only
when the gateway records paced visible reasoning and a usable content flow.
firstToken.reasoningMs in
ttft.go requires reasoning at the first
content and subsequent reasoning deltas at least 100 ms later. It excludes
native Responses and Gemini, whose summaries do not measure their reported
reasoning tokens, and redacted thinking, including translated sealed blocks.
The upstream protocol is retained when the client receives a translation.
These are receive-side timing checks, not access to the vendor's generation
clock: a relay that releases a buffered reply evenly can still look paced.
Without an upstream guarantee, this is an observed output-rate estimate.
Summaries stay excluded rather than extending their visible portion's time
to an unobserved reasoning-token count.
Record.FirstReasoning (first_reasoning_ms) and the corresponding
Call, Route and Try field (firstReasoning) record this evidence with
the same origin as their duration. Historical records have no evidence and
keep their previous speed. Request-page caches and compressed snapshots
preserve the optional field; the packed row keeps ReasoningHidden in
its own Flags bit (rowReasoningHidden), apart from pricing's
swapKnown, which every priced row carries. ReasoningHidden (reasoning_hidden in the
ledger, reasoningHidden in traces) suppresses a no-text speed even when
redacted/encrypted thinking has no reported reasoning-token count. A
Responses summary is marked this way on its own-login path too, and after
an endpoint fallback, where the try's protocol still names the first
endpoint, by the upstream that answered (summaryUpstream in
continuation.go). Optional
OTel attributes carry the evidence without response text. The existing burst and held-content limits in
DecodeOf still apply, and hidden reasoning does not enter average speed.
A streamed request's duration (Millis, which ends every speed window)
ends when its last try's reply ended, not when serve returns: what the
gateway writes down after an answer (answered's sticks, the provider's
last answer in NoteServed) goes to disk, and on a busy disk took
seconds, which made a paced reply read as held back and tell no speed
(#1939, TestSpeedEndsWithTheReply). A decision group's row is timed the
same way.
TestVisibleReasoningSpeed, TestReasoningSpeedEvidence,
TestReasoningSpeedThroughGateway, TestMixedRedactedReasoning,
TestHiddenReasoningThroughTranslation, TestSlowReleasedReasoningIsUntimed,
TestPricedRowKeepsReasoningEvidence, TestSummaryAfterEndpointFallbackStaysHidden and
reasoning-speed.test.cjs
cover the calculation, cache round trip, translated streams and both pages.
Routing purpose filter
The request heading's purpose menu in plugins/routing/client.js
uses openProtoMenu's live checkbox selection: each tick immediately shows
requests matching any selected purpose, with the menu kept open. An empty
selection, All purposes or Clear filter restores every purpose without
changing the day or request/session view. A live menu stays open when its
redraw clamps the list's scroll; the reader scrolling outside still dismisses it.
Choosing All purposes closes the menu and returns keyboard focus to the
purpose button without scrolling; unticking the last checkbox keeps the
menu open and focused on that checkbox.
A Claude Code subagent's turn has the Subagent tag (tagKind,
Route.SubagentID) and no kind, so it stays under Unmarked, as on the
Usage page. Counts, the current story and replay
follow the same filtered list. Selected purposes remain available when a day
has no matching requests. Opening a request from another page clears the
filter only when that request is excluded. Usage's purpose picker remains a
single choice sent to the ledger API. See purpose-filter.test.cjs and
routing-purpose-state.test.cjs.
Routing mode chip
The stage's chip and the Accounts and keys heading in
plugins/routing/client.js name how a route
routes only where that can be changed: a group, or a provider in
/api/groups' pools (two or more accounts or keys on). There they are
.rt-go controls (goTo, goRouting) that bring the group's card or the
provider's row under Several accounts or keys into view through
scrollOnPurpose, mark it (rt-found) and focus its routing. A provider
with one on names no routing, and the mode paragraph says how to get one
(LONE). The header is drawn again when the groups come in (headOf).
See routing-mode-goes.test.cjs.
Routing key and account folds
Three or more API keys, or three or more accounts, of one provider standing
next to each other for one model (same fixed effort, fallback and
group-in-group heading) fold into one stage row, li.rt-fold in
plugins/routing/client.js (FOLD_AT,
rebuild). It shows the count and their state together: the one that is
lit and what it is doing, how many are available and how many rest
(together). Requests that land on a folded seat fly to the fold
(shownRow). Clicking it (or Enter / Space) shows each in place, wired
from the fold. Accounts and keys folds a provider's keys, and its accounts,
into one .rt-keys row each with their summed tally.
A group in the group's heading (li.rt-sub, subNode) folds the same way
(toggleSub): folded, it says how many it routes to and what they do
together, a request to any seat under it flies to the heading
(row.shut), and its wire is the last one drawn (wiresTo).
Keys start folded. Accounts and group-in-group headings start open when
they hold fewer than LONG (6), folded otherwise (Aiirobyte on Discord: a
group of many accounts took the page). What the reader opens is kept in
localStorage magpie.routingKeysOpen and what they fold in
magpie.routingFolded (keepOpen, isOpen), keyed provider/model for
keys and provider/model@ for accounts on the stage, provider/* and
provider/@ in the list, and group/<id> for a heading. Display only: the
gateway's order and choice of seat don't change. Two stay two rows. See
routing-keys-fold.test.cjs and routing-group-fold.test.cjs.
Routing account windows
A subscription account's row in Accounts and keys shows each of its
windows under the one figure routing went by, with when each resets
("5 hours 40% used · resets in 2h"), as the Usage page reads them (#1833).
cardOf in plugins/routing/client.js matches
the route's account to app.js's quotas: a subscription card of this
computer (no from) whose provider is the account's agent (a plugin's
provider id) or its provider, and whose user is the account's, ignoring
case. winsOf names them with familyWindows, quotaText and
resetInText. Nothing new is read: opening Routing asks
/api/usage/quotas in the ordinary way (show, when the readings are
missing or over a minute old), never ?asked=1. A kept day's list shows
none, since those requests were weighed by readings long gone. See
routing-account-windows.test.cjs.
The refresh beside the Accounts and keys heading (#rtReadAllowances,
#1834) reads them again by hand: loadQuotas(true), the asked read the
Usage page's Refresh now makes. It turns while the read is on its way,
and a click then asks nothing more. Nothing on the page reads again by
itself. It shows only live, with a subscription account listed. See
routing-read-allowances.test.cjs.
On the stage, an account's seat tells the same windows in its tooltip,
under its id (render, #1835). The row itself keeps one line: the
fullest window while idle, what it is doing while it answers. See
routing-seat-windows.test.cjs.
The Sessions page's folders
The Sessions page lists an agent's project folders as one list, newest
session first (client.js).
A row says the folder's name, the folder it is in (home as ~, from the
manage reply's home), its newest session's title, when, and how many.
Temporary folders, the disk's root and apps' hidden folders under home
(scratch) wait folded under Other folders at the end; a search, or a
session opened from elsewhere, unfolds them. Checkboxes and the Delete bar
come only with Select, and Done lets the pick go. Relocate project and
Delete all sessions are in a folder's ⋯ menu, shown on hover (always on a
touch screen) and on a right-click. See sessions-folder-list.test.cjs.
Stored agent sessions in WSL
The Sessions page uses sessions.ListAgent; Usage → Sessions uses
sessions.List and StatsFor through the handlers in
sessions.go and
sessions_manage.go.
ListAgent also lists a session nothing was said in, so it can be cleared
away; List leaves such a session out. The routes a row opens
(conversation, Markdown, Terminal) look the session up with
sessions.Find. Find finds every session ListAgent lists, empty ones
included, so such a row doesn't answer "no such session" (#2273,
TestFindEmptySession, TestEmptySessionOpens).
On Windows, internal/sessions/wsl.go
reads running distros through their WSL shared paths. A stopped distro keeps
its cached listing and is not opened; running distros are relisted at most
every 30 seconds.
For omp, ompRootsIn includes both
~/.omp/agent/sessions and
~/.omp/profiles/<name>/agent/sessions. Subagents and advisor files count
in their parent session. A profile session's Resume command selects its
own profile with omp --profile <name> --resume <id>, including when
resumed through wsl.exe. Delete and Restore preserve its original
profile path and artifacts. Windows does not discover arbitrary stores
selected by a distro's PI_CODING_AGENT_DIR, XDG variables or
--session-dir.
Desktop fonts
Settings → General offers independent interface and code fonts, each with
the installed family's actual styles. GET /api/fonts calls
fonts.List: DirectWrite on Windows,
CoreText on macOS and Fontconfig on Linux. Discovery is lazy, cached in the
handler, and refreshed by the menu. It returns names and CSS traits, never
font files or paths. A failed refresh answers 503 and preserves the previous
collection; an empty successful collection is distinct from failure.
A nogui build can't read the catalogue and answers the app 404.
A browser tab (magpie web, or the app's page opened in a browser) always
has the same rows (Norcleeh on Discord). Its choice is the
browser's own, kept in localStorage under magpie.fonts and applied by
fonts.js before the first paint: the tab can be on another computer, so
it neither changes nor takes the app's settings.UIFont/CodeFont. A
tab's /api/fonts is the server's families (none in a nogui build such as
Docker or magpie-cli, and none when reading them fails, never an error)
plus commonFamilies in internal/gui/fonts.go, in regular and bold.
The tab keeps those it draws (webFonts.drawn in webfonts.js: text in
the family measures apart from a generic family's on a canvas), so another
computer's fonts, and Safari's user-installed ones, aren't offered. When
none is kept, the rows still offer System default.
Those are the server's names, so fonts installed only on the browser's
computer were missing (Norcleeh again, magpie in Docker). webfonts.js,
which only a tab loads (app.js loadFonts imports it; the app's windows never
need it, and it is outside the core script budget), adds them: where the
Local Font Access API is (Chromium on https or localhost),
queryLocalFonts() is called in the press that opens a family menu, once
a page, and at load when the local-fonts permission is already given;
its style names ("SemiBold Condensed Italic") become weight, slope and
width. Elsewhere (Safari, Firefox, a plain-http LAN address, a refused
permission) the menu's search also takes a typed family: "Use “name”" is
offered when the canvas probe says this browser draws it, and greyed out
when not. A chosen family the server doesn't list stays in the tab's list
on later loads while the browser draws it, so desktopFonts.available
keeps applying it. Until 10-28 the rows were
gated on a boot fonts flag, so a nogui server had none, and what
"flashed and vanished" on a refresh was Text size: the rows a tab never
shows (Text size, the tray click, Open at login, the menu bar's
allowances) are .app-only, which body.web hides before the first paint.
settings.UIFont and settings.CodeFont keep the family, style name,
OpenType weight, CSS slope and width percentage. A missing choice keeps the
platform default. A settings POST can restore that default with an explicit
null; omitting the field preserves it, as does every browser-mode save.
KeepOwn preserves this computer's choices during sync and backup restore.
Invalid traits reject the save without replacing the previous settings.
fonts.js applies choices at boot and
through applyPrefs. After a successful font change host.fontsChanged
notifies both existing webviews through receiveFonts, without waiting for
the other window to gain focus; a released lightweight webview uses boot
settings when recreated. An in-flight local save ignores the notification
and finishes its own queue.
The selected family precedes the existing platform fallback stack. The
interface and code traits apply independently; explicit component weights
still mark emphasis. A choice takes precedence over Omarchy's font, while
restoring the default follows the theme again. If discovery finds a saved
face missing, the page retains its name, explains the fallback and uses the
default until the face is available or the user chooses another. A discovery
error never clears a saved choice. The browser's own typography is unchanged.
The menus support search, keyboard selection and refresh. Styles are ordered by weight, then normal, italic and oblique; width and name break remaining ties. Family changes keep a matching style where possible, otherwise the nearest regular face; named variable instances are offered without arbitrary axis controls.
Recent-call bodies
providersState in providers.go sends
recent-call metadata without request or response bodies, including after
provider writes (#1521: forty calls' bodies made /api/providers about
20 MB). Each call in the gateway's 40-call ring has an id, numbered in
Server.record. Opening a recent call on Gateway fetches its captured
previews from GET /api/gateway/call?id=… (Server.RecentCall), sent
Cache-Control: no-store. The route sits on the same mux as the rest of
the API, so magpie web's key guard covers it. The bodies are the ones the
ring kept, masked as the request was (redacted); the route doesn't fetch
S3 or change capture, export or archival. A call evicted from the ring, or
a gateway served by another magpie, returns 404. The page keys a row by
that id (callRow), keeps fetched bodies in memory while their calls
remain in the list, preserves them across summary refreshes, and offers a
retry after a failed read. See TestRecentCallBodiesOnDemand and
recent-call-bodies.test.cjs.
A request on the Routing page opens to the same bodies (Fate on Discord):
its story's head has "Request and response", which fetches
GET /api/gateway/call?route=… (Server.RouteCall) only when pressed.
A call carries the Routing request it was (Call.Route, the trace's
Route.ID, set where serve, the Codex backend and a refused title
record it; the Codex backend's refused key and empty failure too, but not
a compaction's, which opens no route: TestCodexKeyRefusedCarriesItsRoute);
a route id is not a call id. When the ring no longer has it,
the story shows the request archive's copy through archivePanel if the
route names one (Route.Archive, call.archiveName(), set only when the
archive was on for that request), and otherwise says how to turn the
archive on. Nothing more is captured than before. The archive's switch
(POST /api/settings/archive) sets RequestArchive while sync has an S3
bucket and RequestArchiveLocal while it has none; GET /api/archive?name=… reads this computer's copy first and then the bucket's
(TestArchiveSwitchKeepsOnThisComputer, request-archive.test.cjs). See
TestRoutingRequestOpensItsBodies, TestArchiveWholeBodies and
routing-bodies.test.cjs.
Plugin check-in switches
A plugin's Usage-card Auto check-in button reads the persisted
settings.pluginCheckins[provider] first (pluginCheckinOn in
app.js). /api/state returns that map
without the derived checkinPlugins list included by /api/settings.
An explicit saved false wins over the list; when no saved choice exists,
the list's resolved vendor default remains the fallback, and without the
list (a state refresh) the switch of the built-in check-in the plugin took
over is (PLUGIN_CHECKIN_INHERITS, the ids provider.PluginCheckinOn names;
a test reads both). This keeps a saved
switch on through a focus refresh and lets the next click turn it off.
plugin-checkin.test.cjs
covers both response shapes, refreshes and the subsequent toggle.
Plugin options
A plugin provider's editor shows the options its plugin declares
(pluginOptionsField in app.js; see
provider-plugins.md). The
plugin's label, description and confirm text go in as text, never as HTML.
A change is kept in draft.pluginOptions until Save, which posts each one
to POST /api/settings/plugin-option before the provider's own save. An
option switched back to where it was is dropped from the draft, so it isn't
posted and doesn't make the editor dirty.
plugin-options.test.cjs
covers it.
A plugin's own page
A community plugin that declares magpie.page gets a tab in a Plugins
group at the sidebar's foot (pluginpages.js, loaded after plugins.js),
listed from GET /api/plugin-pages and again whenever Plugins reloads its
list (window.loadPluginPages). The tab's title is the plugin's own and is
not translated; renderCrumb and the sub-nav's label read its plain
<span> where a built-in tab has span[data-t]. The frame is made the
first time the page opens and fills the view (.view.plugin-page,
.plugin-frame). The theme and language reach it on every change of
data-theme, lang, class or style on :root. A page gone off or
away loses its tab, and the window goes to Plugins if it was on it. The
security model, the bridge and the reads are in
plugin-runtime.md.
plugin-page.test.cjs
covers it in both engines, every language and a narrow window.
Shared UI rules
Windows desktop windows and tray panels keep the modal's dimming veil without backdrop blur or saturation: full-window filtering can stall WebView2 while a provider test or sign-in dialog is open. The existing
winmarker fromlayout.jsscopes the rule inapp.cssto the desktop app; browser pages and other platforms keep their existing effect.modal-backdrop.test.cjschecks the computed filter and veil in both engines and modes.Settings → General is laid out as macOS System Settings is (1ooogle on X): a row says its name alone when that says enough (Appearance, Colorblind mode, Language, Text size, the fonts, the tray click, Open at login, Show in Dock), and keeps one short line where the setting isn't clear from its name or has a consequence (Lightweight mode, Prevent sleep, Session terminal). Codex's, Claude Code's and Grok Build's own settings (Codex subagents, Long conversations, which is all of Grok Build's, background compaction, thread titles and descriptions, composer predictions, the auto-review and memories models) aren't here: they are in the agent's opened row on the Agents page (
AGENT_PREFS,connectPanel), the panel's row has a Settings line that opens them in a sheet (openAgentPrefs), as does the agent's menu, and Settings' search finds them with a row that opens that sheet (#agentPrefLinks). Each row is one element moved between its places, so its handlers and state go with it (the owner, 10-20;agent-prefs.test.cjs). Long conversations is the exception with no Codex, Claude Code or Grok Build here, in gateway mode or a magpie in Docker: it sets the windows the gateway serves, which agents on other computers read, so it stays in General (renderAgentPrefLinks, Linka on Discord). A font row's line shows only while its fonts load or fail; the text size keys are the choices' tooltip, and Colorblind mode's note is its Off/On control's (#colorblindSegs). Colorblind mode (settings.Colorblind,data-colorblind="1"on:root, #2073) switches the chart series (--c1…--c7) in both light and dark themes to an Okabe–Ito palette where adjacent series differ in hue and lightness. On a quota curve each window (data-series, its index mod 7, set bydrawQuotaPlotandquotaCurve's legend only) gets a dash of its own onpath.qc-line, its legend key shows a sample of that line (.qc-sample) for the dot, and the even paces (line.qc-even) are dotted; the curve's tooltip says so. The balance curve sets nodata-seriesand keeps its solid line, dashed fit and dot. The Context tab's "good" grade, which takes--c2as a colour rather than a series, keeps a blue (--c1). Language is one menu button showing the language picked, opened in the app's menu (renderLangPick). Seesettings-general.test.cjsandquota-curve.test.cjs. Open at login readsautostart.Enabled, which on macOS 13 and later also asks Background Task Management about magpie's launch agent (SMAppService.statusForLegacyURL:, matched by the plist's Label, not its path); a record the user switched off in System Settings › General › Login Items reads as needing allowing, and the row keeps On with one line saying so and a button that opens Login Items (/api/openallows that onex-apple.systempreferencesURL). The status read again when the window comes back to the front clears the line. On macOS 12, in a build without cgo, or when the system can't be asked, the plist alone decides, as before (#2120,login-allow.test.cjs,login_allow_test.go).A setting row's line under its name (
.row.pref .sub, in Settings, Plugins › Built-in and an agent's own settings) wraps whole beside its control, never cut to one line with an ellipsis (arculongus on Discord,settings-lines-wrap.test.cjs).Settings' search-provider picker offers Off, saved as
searcher: "off". Its help explains API-only search and suppresses provider fallback/own-search hints while off; the search priority row is hidden because no provider competes with the APIs. See gateway search behavior,renderSearcher,TestSettingsSearchProviderOffandsearcher-pick.test.cjs.Settings' search APIs are asked in their listed order: each API's row (with its keys' row) is dragged as one, or moved with Alt+↑/↓, and has a switch that turns it off without removing its key (#2286). See the search APIs' order,
searchArrangeinplugins/search/settings.jsandsearch-order.test.cjs.Settings' Search APIs add row has a base URL field under the key for every API (#1580): the vendor's own address is its placeholder, picking an API already added fills in its saved URL so a new key alone keeps it, and Add with no key changes only the URL. See a search API's base URL,
renderSearchandsearch-api.test.cjs.Every user-visible string has zh, zh-TW, ja and de translations with the same placeholders.
gui-zh-tw.test.cjs,gui-ja.test.cjsandgui-de.test.cjsfail on a missing one;gui-zh-tw.test.cjsalso fails on a zh-TW string with a Simplified character left in it.A click never moves the page. Code scrolls a view only with the reader's event in hand (
scrollOnPurpose);click-scroll.test.cjsguards this. A click is taken where the reader left the view: a scroll not theirs made just before it, whose scroll event the browser sends only at the next frame, after the click, is put back first (backToReaderin the click guard, #1554). What was clicked is held where it was (hold); a view at its top when clicked stays at its top, and what comes in above the control moves it down instead (#2134,update-auto.test.cjs), as long as it moves less than half its own height and so stays under the pointer. When what the click does leaves the page shorter under it (a list emptied), the view keeps room at its foot for it to stay (.view-room), room that goes as the reader scrolls back. A control under what it unrolls (data-unrolls, "Show 7 more") goes down with what it opens: what's held is the part it is in, so the rows open downwards. Anything larger above it, as the stage a day picked on Routing brings in above the bar, is scrolled past, and the control stays where it was clicked (routing-days-fit.test.cjs,routing-failed-open.test.cjs).A scroll not the reader's is put back, so every way the reader scrolls has to count as theirs: the wheel and a trackpad's coast after the lift (WebKit on the Mac plays the coast itself and the page hears its scrolls with no wheel for each, so the wheel starts the same chain a touch fling does,
flings/flingUntil: each scroll keeps the next one the reader's till it rests, and a click ends it; issenn on Discord,view-trackpad-coast.test.cjs), a wheel or coast the page is never told of (macOS 13's WebKit, Safari 16.6's, scrolled a view under wheels it never dispatched, so every scroll was put back and only the bar's drag moved the page: three scrolls put back the same way within a second are taken as the reader's run and given back, and so is each one after it that goes on the same way within a second of the last, so a wheel turned slowly or on a loaded Mac loses no step; a scroll by code is one, not a run, and two at rest are still put back; issenn on Discord,view-wheel-unheard.test.cjs. Under a click's 4s hold the same holds: only a put-back that comes with the page redrawn since the hold last held (redrawn: the view's height or where the first held parts sit moved fromh.lay) is the hold's and never counts toward a run, so a profile opened on the Agents page and wheeled through at once scrolls, issennknight on Discord,view-wheel-after-click.test.cjs. The partsh.laymeasures are those still in the page that scroll with it: a part drawn again since (the Usage page's tabs, the agents' list under an agent opened or closed) is a redraw once, not at every scroll, and a sticky one (Settings' tabs at a narrow width) is left out, as it sits still while the page scrolls;view-wheel-after-redraw.test.cjs), a touch and its fling, the keys, a drag, the scrollbar's own drag (barDrag, #1089) and the middle button's autoscroll (panning, 多喝热水 on Discord). Chromium and WebView2 give the autoscroll a press of button 1 and then no event of the reader's while it scrolls; from that press the view follows it till Chromium ends it, on the next press (which reaches the page only as a pointerup), a key (a keyup), or the lift after the mouse moved while held. A field the guard brings back into view after putting a scroll back is one focused since the reader last scrolled that view, not one they scrolled away from (scrolledFrom): the middle press focuses the button under it. Seeview-middle-autoscroll.test.cjs.A load that lands puts the view back where the reader left it (
show'sbackon the page's first reads, the Providers pages' reload afterrender): what it drew may have pulled the view up, the browser clamping it to a page shorter for a moment. While the reader scrolls, the place last heard is late (the page hears of a scroll a frame or more after it, WebKit scrolling on its own thread), and putting it back took their last steps and stopped their coast each time a load landed under the wheel, so Routing and Usage, scrolled as they opened, shook and snapped back (issennknight on Discord, macOS 13).backAfterLoadkeeps a view that has gone on the way the reader's own scrolls go (readerWay, set from each scroll of theirs) as theirs, and puts back only a move against it, which is a redraw's clamp. The browser's scroll anchoring stays on: as data comes in above, it lowersscrollTopwith what's on the screen still, which the reader never sees, so the test tells a put-back (the view up, what was under the pointer going down with it) from that.Where the window's WebKit scrolls under wheels it never tells the page of (macOS 13's, 16.6), each gesture's first scrolls were put back until three the same way made a run (
puttingBack), a shake at the start of every gesture, the first on a page just opened included. The first run given back is remembered (deaf, kept in localStorage asmagpie.unheardWheelsfor the next start); from then on a scroll at rest waits 120ms before it is put back (waitsBack), and one more the same way within 80ms (a frame or a few; code's two scrolls in a row come further apart and are both put back,view-wheel-unheard.test.cjs), with the page's height the same (no redraw between them), makes it the reader's at once. A lone scroll (a redraw's, code's) is still put back, 120ms later; one under a click's hold is put back at once as before. Seeview-open-wheel.test.cjs, which starts the wheel before the first data, tells the page of each scroll 80ms late or never, and counts every write that moves the view up under the wheel. What the wait puts back is recorded as an at-once put-back is, so a wheel heard later than 120ms still gives it back (givesBack).Typing never moves the page either. A textarea that grows with its text (the Library's
autosizein plugins/library/client.js: a set's text, an agent's own text, a skill's description, a subagent's fields) is measured at height auto with what holds it kept at its height, so the page never goes short for a moment: a page gone short has its view's scroll clamped by the browser at every input, an input method's every composing step included, and the guard's putting it back pulled a textarea taller than the view to one of its edges (#2636,library-ime-scroll.test.cjs).A box that scrolls inside a page keeps the wheel at its ends: wheeled past its top or foot, the page stays where it was (碳碳双键 on Discord, Requests' list on Usage).
holdsin app.js marks every box between the pointer and its.viewthat scrolls vertically and overflows (.holds), onpointeroverand on each wheel, and app.css gives.holdsoverscroll-behavior-y: contain(the Mac's bounce stays, on the box). It is not one CSS rule for every box because Chromium (WebView2, magpie web) holds the wheel in a box told to contain even when it doesn't overflow, and in one that scrolls only sideways, so a short list or a wide table would stop the page..holdsis under:where(), so a rule that passes the wheel on still does (.mchipsin a short window, #833). The page itself (.view) and the document chain as before. An engine with nooverscroll-behavior(Safari 15, macOS 12's WebKit until Safari is updated; Safari 16+, WebKitGTK and Chromium have it) gets the same fromcompat.js: a wheel over a.holdsbox at its end in the wheel's direction is cancelled, so there the Mac's bounce at the box's end is lost. A guard ininner-scroll-contain.test.cjsbuilds every rule in every stylesheet under assets that scrolls a box vertically from its own selector, fills it and points at it, and fails naming the file and selector of one that doesn't hold the wheel (a rule that setsoverscroll-behaviorback to auto, or a boxholdsdoesn't reach). Seeinner-scroll-contain.test.cjs.There are no native
<select>elements and no colored left-border stripes. State is shown with a dot or a swatch.What the window shows can be selected and copied, its controls can't, as in a Mac app (Outvi V on Discord: nothing could be copied into a bug report). The page is
user-select: none, and two:where()rules afterbodyinapp.cssmake text content selectable (paragraphs,preandcode, a detail's values, hints and notes, every error class, a conversation, a request's story on Routing) and keep every control unselectable with what is in it (buttons, labels, tabs, menus, the navigation, grips). Both have no specificity, so a view's own rule still decides, as a list being sorted does; a field stays selectable. Seeuser-select.test.cjs.The Usage page's cards and the tray panel's Allowances tab share one order,
settings.UsageOrder(byUsageOrder). In the panel a balance-only card stands where that order puts it, and balances next to each other share one Balances grid (panelBalances, #1510); none is gathered after the plans. The panel's Arrange (panelArrange) moves rows in it and hides subscriptions from that tab alone (settings.PanelUsageHidden); both save throughPOST /api/usage/arrange, which changes only the field it is sent, and the Settings save keeps both. Hiding is display only: a menu bar cell's card shows though hidden (panelPeek). SeeTestUsageArrangePanelHidden,panel-arrange.test.cjsandpanel-balance-order.test.cjs.An allowance card can be hidden from Usage › Overview (whqtian_07012 on Discord: StepFun's plan wanted, its balance not). Right-click a card, or press it long on a touch screen (
quotaCardMenusinplugins/usage/page.js), and the app menu offers Hide from Overview; an account of a card with several says Hide this account from Overview, and a plan card carrying its key's balance (keyCards) also offers Hide its balance from Overview, which keeps the plan. Each is kept by its tray card id and kind (cardHideKey:stepfun|balance,kimi|me@x|plan) insettings.UsageCardsHiddenthrough the samePOST /api/usage/arrange(cardsHidden), and kept by the Settings save.overviewCardsleaves them out beforekeyCards, so routing, caps, the counting, the Accounts list, the tray panel (which has its own Arrange) and the menu bar cells never hear of it; a cell clicked for a hidden card shows it until the page is left (usagePeek). A quiet "{n} hidden" line under the cards (#quotaHid,renderQuotaHid) opens them, each with Unhide, and Show all from two. SeeTestUsageArrangeCardsHiddenandusage-cards-hide.test.cjs.A client in the Usage page's Agents list can be hidden from that list (ikunbots on X): its row's "…" button or right-click opens the row menu with Hide from this list, saved by client id in
settings.UsageAgentsHiddenthrough the samePOST /api/usage/arrange(agentsHidden), and kept by the Settings save. The ledger, the totals and the chart still count a hidden client. A quiet "{n} hidden" line under the list opens them, each with Unhide (hideUsageAgent). SeeTestUsageArrangeAgentsHiddenandusage-agents-hide.test.cjs.Usage › Overview's Agents, Models, Accounts and Gateway keys lists each fold under their heading (#2378): the heading is a
.foldbutton with its chevron, as on the Gateway page, and the click doesn't move the page (backToReader). What is folded is kept per viewer in localStoragemagpie.usageFolded(mountUsageFolds,showUsageFolds). The totals leave the cache out, as before, unless the tokens tile's label, a pop-up button (usageTokensPick, the app menu), is set to With cache: then the tile, the chart and every row's count and share add cache read and written (usageTokens), and the tile says the cache's count; kept in localStoragemagpie.usageWithCache. The Requests tab's total already counts every token (allTokens). A token line in parts (the Requests strip's Tokens card, the Overview's tokens tile) wraps between its counts and keeps each whole (usageParts,.parts); only a count wider than its card on its own is cut. Seeusage-overview-fold.test.cjs.A request's details in the Usage ledger say its tokens at every width (#1839,
ledDetail): "{i} in · {o} out · {r} cache read · {w} cache creation", 0 said as 0, with how much was written for 5 minutes and for an hour when it says so. A failure that spent nothing has no Tokens row. Seeledger-cache-tokens.test.cjsandusage-ledger-detail.test.cjs.The requests magpie makes by itself (a routing classifier's, a web search's, an image description's) are told apart from the agents' on the Usage page (#1839): magpie's row among the agents and its rows in the ledger carry a "magpie's own" mark (
ownBadge), an account's, key's or model's row adds "{n} by magpie itself" from the summary'sown, and an account's card says how many of the period's requests were magpie's own (ownLine, drawn again once the summary comes after the allowances). Seeown-requests.test.cjsandTestSummaryCountsMagpiesOwnCallsApart.Opening the allowances is asking to see them (#1588,
quotasOpenedinapp.js): the Usage page from the nav or its Overview tab picked, the window brought back to the front on the Overview, the tray panel's Allowances tab picked or the panel brought up on it, and a menu bar cell clicked each loadusage/quotas?asked=1, as Refresh now does. An asked read makes the backend read every account again (AskClaudeUsage), so an opening within 30s (QUOTAS_OPEN_GAP) of the last asked read sends an ordinary read instead, which joins one on its way; Refresh now always asks. A panel page loaded while it is put away (hidden, or without focus) doesn't ask. The timed refresh is unchanged and never asks. Seeallowance-open-read.test.cjs.The menu bar can show magpie's own totals beside the allowances (#1984):
usage:todayandusage:7dinsettings.TrayUsages, offered after the cards in the same picker.trayUsageCardssums them withusage.QueryPage(p, Filter{}, 0, 1).Sum(the Requests tab's and the panel's cached ledger sum, gateway and session-file calls together) and asks no vendor when only totals are picked;trayTotalCardmakes every token (in, out and cache, asallTokens), markedΣso it doesn't read as the input, over the cost in Settings' currency,+when some calls had no price, the cost row left out when none had one. The Mac draws them as plain cells, the bird beside them saying whose. A click opens the Requests tab at the period (quotaView,?tab=requests&period=) or the panel's Usage tab (panelUseFocus). No 3-day total: the Usage page has no such window. SeeTestTrayTotalsandtray-totals.test.cjs. Settings › Menu bar cost (settings.TrayNoCost, on by default, on every OS, per computer throughKeepOwn) turned off leaves the money out (BussanQ on Discord):trayMoneydrops the total's cost and its count of unpriced calls beforetrayTotalCardand the no-card tooltiptrayIdleTipsee it, so the cards, their tooltip and the idle tooltip say the tokens and requests alone. A relay's or subscription's balance card is money itself and stays. SeeTestTrayNoCostandtray-cost.test.cjs.The tray's icon is the bird alone where the bar's other icons are glyphs: the Mac's menu bar takes
tray.pngas a template image, and a Linux bar (StatusNotifierItemIconPixmap) gets the same silhouette in one colour on transparency (trayIconFor,linuxTrayIconintrayglyph.go), so a bar that tints its icons by their alpha tints the bird, not a tile (ylorn on Discord). A bar that doesn't tint shows it light, or dark when the portal'sorg.freedesktop.appearancecolor-schemeprefers light (traySchemeLight), and it is drawn again when that changes (watchTrayScheme). NoIconNameis set: a host that found a-symbolicname and drew it untinted would show a black bird on a dark bar, with no pixmap to fall back on. Windows' tray keeps the app's coloured icon. With no cards in the menu bar the tooltip is magpie over today's total (trayIdleTip: every token, split into input, output and cache as the today card's tooltip is, then the cost and the requests), brought up to date with the cards' refresh; the tray's menu stays Open, the version and Quit. Wails sets the tooltip only on Windows: on LinuxsetTrayTipsets the StatusNotifierItem'sToolTipand sendsNewToolTip(traytip_linux.go), and on the Mac it is the status item's button'stoolTip(trayTipNativeintrayimage_darwin.go; NextCommit on Discord: no hover there showed anything). SeeTestTrayIconPerOS,TestTrayIdleTipandTestMacTrayTipIsSet.A window's Pace is a number on its card's reset line (fflake33 on Discord): the share used less the share of the window gone by, in points, "Pace +12%" over an even pace and "−8%" under it, turned with the meter when it shows what is left, amber while more is used than an even pace would have (
quotaPace,paceLine). The window's start is the gateway's,startsAtfromprovider.WithWindowStarts(its reset less its span,QuotaWindow.Bounds); a window whose span isn't known, with no limit, or a past cycle has none. Settings › Menu bar pace (settings.TrayPace, off by default, hidden on Windows, whose tray shows no text) puts the same number beside each figure in the menu bar and in its tooltip (trayPace,QuotaWindow.Pace). SeeTestWindowPace,TestTrayUsagePaceandquota-pace.test.cjs.In Usage → Allowances, Trends → Cycle offers each account's own recorded cycle menu beside its curve (
quotaCurve,quotaRecordedCyclesinapp.js). The longest window (usually weekly) owns the menu; shorter windows are drawn over the selected dates with their own reset breaks./api/usage/quotas/history?days=45supplies all retained readings, including remote cards. Completed cycles come from observed boundaries, not seven-day arithmetic; an early reset ends the previous cycle at the vendor's new start if it fits between readings, otherwise at the first new reading. Each menu option gives its observed duration, so an early reset is not labelled as a full seven days. The selected meters, plot, legend, tooltip and dashed pace use that cycle's last readings, never today's percentages. A window without a reading in the selected interval says so instead of showing a current value. A local account's past cycle asks/api/usage/quotas/history/holds?provider=&user=&from=&to=once per selection (quotaCycleHoldsOf), which asks no vendor (#2009, NorethSea):HistoricalWindowHoldsinwindow_holds_history.goreckons each window's whole at its own last reading in that cycle, from the request log up to that reading, so the 5-hour figure is the cycle's last 5-hour window, never its short windows added up. Its tooltip names that window's start and the reading's time. It shows "Loading…" until the answer comes. A window it can't reckon says "not enough data" with the reason, as a current card does; a reply that comes after another cycle was picked is dropped, and a card's Refresh or an asked read reckons again. Historical meters show the cycle end and sampling time; current account actions, balances and policies are left out until returning to the current view. Accounts are independent, and a selection survives card refreshes in the same page. Trends → 2 days temporarily shows recent readings; Off removes the curves; the tray always shows its current cycle. Seequota-curve.test.cjsand the history limits and reset inference.The Usage page's cards are packed into columns, never all stretched to a row's height (
packUsage, #860): each card in that order goes to the leftmost column that ends highest, on 1px grid rows, so short cards stack beside a tall one. The last card in each column then reaches down to where the tallest column ends (amin-height, cleared before the cards are measured again), so cards side by side in one row are as tall as each other and a stack ends with the tall card beside it (ikunbots on X); content stays at each card's top. The page's order (DOM, dragging, Alt+arrows) staysUsageOrder. The column count is the most 260px columns that fit, or one fewer when that leaves much less empty room; it is chosen again only when the cards change or the width fits another number of columns, so a card opened or folded stays where it is, even as the scrollbar comes in. Seeusage-pack.test.cjs.The Providers page has a search box over its list (#1614,
findProvidersinapp.js): the words typed keep the rows, on and off, whose text or data say them all: name, id, preset, addresses, every model's id and name, the account's user and plan and each login's, account names and key names. The Turned off fold stays open while searching; Escape or clearing the box shows every row and the fold as it was. A row that is on reorders by dragging its logo, Alt+↑/↓, Alt+Shift+↑/↓ (top, bottom) or its right-click menu (openProviderMenu: Move to top, Move up, Move down, Move to bottom). While searching, a step or a drop moves it among the rows shown (it takes the place of the row it passes,stepProvider,shownToOn) and the hidden ones keep their order; Move to top and Move to bottom go to the ends of the whole list. Every move saves the whole order throughPOST /api/providers/arrange. Seeprovider-find.test.cjsandprovider-order.test.cjs.Hide accounts (
window.hideAccountsat the end ofapp.js, stored inmagpie.maskEmails, which the panel follows) masks every account name and address in the page's text and tooltips. While it is on, an account's name on the provider editor's row (accountNameButton, and the one-account line) and on its Usage card (quotaWho), and on the tray panel's Usage card (panelQuotaCard's.pq-who, in sight while the card is hovered), has an eye (hideAccounts.eye), in sight on hover or keyboard focus. A click shows that one account, its address and the name the user gave it together (kin), everywhere that page draws it, tooltips included, while the others stay hidden (yogurt36 on Discord, for a screen share). The accounts shown are a set held in memory thathits()skips; nothing stores them. The window and the panel are pages of their own, each with its own set: one shown in the window stays hidden in the panel and the other way round, so a screenshot of either shows only what was shown there. Closing the window hides them again: the page stays loaded while the window is hidden, sohideMainrunsmainClosedJS(hideAccounts.closed) first. Putting the panel away hides the panel's again, from itsvisibilitychange(the one that dropspanelPeek) (account-eye.test.cjs,TestClosingHidesShownAccounts).A new user's Agents page (the window's first page and the panel's Agents tab) has a Get started card above the agents in the welcome's place (wangye1644294 on X,
guideCardinapp.js). Its three steps are: add a model source; connect an agent, where the agents magpie found that can be connected are named and each is connected in one click (agents/connect); and, optional, a routing group, with the most harmless starter template that can be made from the user's models (provider.Templates, Never stuck first) added in one click throughPOST /api/groups/template. Every tick comes from the state: the models magpie serves (servedin/api/state, groups left out), an agent wired, or a group that isn't automatic. None comes from the card having been seen. The card goes once the first two steps are done. Its close button savessettings.GuideHiddenthroughPOST /api/settings/guide, so the panel, the window and a reload agree, and the Settings save keeps it. Seegetting-started.test.cjs.A connected agent's row in the window opens and closes on a click anywhere on it that isn't one of its controls, as a disclosure row does on the Mac (NG_shiyu on X,
connectRowinapp.js): the click is handed to the row's Models {n} link (expandLink), which stays the control the keyboard and a screen reader use and keepsaria-expanded. Buttons, links, inputs, anything with a role, the grip and the opened sheet (.ag-exp) keep their own clicks, and a click that ends a text selection does nothing. The panel's rows did this already (agent-row-disclose.test.cjs).An agent whose own model menu is the list picked in magpie (ZCode, Claude Desktop, Cursor Private Inference, …:
listsMenu) says that list as its ticks are, on its button and on the panel row (menuSaidinapp.js): every model ticked is All N models, one or two by their names, more as Showing x / N models, none as No models. It never says the first names and a +N: routing groups come first, so that read as a pick of one group and one model while every model was on (NG_shiyu on X). Other agents' start pickers still say the one model or group they start on (agent-menu-label.test.cjs).Every page of the window keeps to one width, at most 1200px of content centred, with a 16px gutter in a narrow window (
padding: max(16px, calc(50% - 600px))on each#view-…, #860). Routing, Usage and Sessions are in that rule too (面条 on Discord), so a large screen doesn't stretch them edge to edge while the others sit in the middle; their columns follow the room they get (byWidth). Seepage-width.test.cjs.The page must work in Chromium (Windows' WebView2) and WebKit (macOS, and WebKitGTK on Linux). GUI tests run in both engines.
In the design of macOS 26 the main window has the corners of a window with a plain title bar, and its lights stay where the toolbar had them.
TestMainWindowCorners(titlebar_darwin_test.go) measures this in a process of its own, with packagewindowshape: after a new title and size and a new system appearance, as AppKit draws that appearance, where a first press with another app in front begins a window drag, and where a sheet begins. It runs that process as linked against the macOS 26 SDK and against macOS 15's, whatever SDK the toolchain has (runAppKitSDKandstampSDKgive the copy it runs that SDK, and sign it again). In the earlier design, on an older macOS or with macOS 15's SDK, it checks that the window keeps its toolbar;TestMainWindowRightToLeftchecks that it keeps it with the lights on the right. Both run in CI's macOS job. No test coversUIDesignRequiresCompatibility: AppKit reads it from an app bundle's Info.plist, LaunchServices registers each bundle that runs, and a press sent within a process run from one doesn't always begin a window drag.On Linux the panel is frameless and the main window has a hidden title bar (
plainTitlebar). GTK 3 asks KDE's Wayland session (KWin's decoration protocol) for a frame drawn by KWin on any window without client-side decorations, an undecorated one too, soownFrametells KWin the panel draws its own on each realize (#1283). GTK 4 builds ask for none themselves. With no KWin title bar, and with a Wayland window placed by the compositor rather than by the icon, the panel's header is its drag handle on Linux, as the window's is (--wails-draggableinapp.js;panel-drag-linux.test.cjs); on the Mac and Windows the panel isn't dragged (#1430).On Linux the panel is a solid window, as the main window is, and its page paints
--bgwhole (panelOptions,body.linux.panelinapp.css). The Mac's and Windows' panels stay translucent. A see-through panel is an RGBA, app-paintable GTK window under a transparent webview, and on KDE Plasma 6 its page, painted at 93%, left a fainter copy of the old scroll position as it scrolled (Wayland and XWayland, compositing mode on or off) while the main window never did (#1803,TestPanelSolidOnLinux,panel-linux-opaque.test.cjs). Xvfb with picom on WebKitGTK 2.54 doesn't show the ghost either way, so the fix rests on the reporter's machine.A Wayland window can't place itself, so under Hyprland and niri the compositor is asked to put the panel under the bar. Under Hyprland
placePanelgives it a window rule at the cursor (omarchy.PlacePanel) and closes it on a click outside (omarchy.ReportClicks). The rule names the monitor under the cursor and moves the panel to x, y from that monitor's corner (omarchy.PanelAt): Hyprland adds the window's monitor's place to amove, so a position across the whole layout put the panel off a monitor not at 0,0 (#1785,TestPanelAtMonitorOffScreenOrigin). The cursor and the clients' places thatomarchy.ClickedOutsidecompares are both across the layout. niri (omarchy.Niri,NIRI_SOCKETset) takes no rules at runtime and doesn't report the cursor. Thereomarchy.NiriPanelwatches niri's event stream and moves the panel each time it opens: the window of magpie's pid titledpanelTitle, moved withMoveFloatingWindow(afterMoveWindowToFloatingif it was tiled). It goes 6 px under the working area's top, centred on the x the tray host passed toActivate(x, y). Wails keeps that x in its Linux tray (trayClick,TestTrayClickIsWails), and it is taken across the bar, since that's all a Wayland bar knows. With no click (magpie panel), or with one off the output, it goes top right. Wails'HideOnFocusLostcloses it, since a click on another window takes niri's focus. It still opens in the middle and slides up, and a bar at the bottom or the side isn't accounted for (#1670).Wails calls the tray's click handler both for the icon's click (
Activate) and when the tray host opens the icon's menu (dbusmenu's "opened" event). KDE opens the menu on a right-click, and the panel that click opened took the focus and shut the menu on Wayland. On Linux the handler ignores the call when it comes from the menu opening (menuOpeningintrayclick.go, which looks for Wails'(*linuxSystemTray).Eventamong its callers;TestTrayMenuOpenFrameIsWailsfails if Wails renames it or stops calling the handler there) (#1430).On GTK 3 builds, the app gives GDK a font DPI before the first webview when it has none (
fontDPI,fontdpi_gtk3.h). GDK's unset value is -1, and WebKitGTK 2.54's GTK 3 settings reader multiplies it by 1024 unchecked, so every page lays out at a negative width with a 9000000px font (#1371). An unset DPI takesgtk-xft-dpi, or 96, times a validGDK_DPI_SCALE; a positive one is left alone. Wails initialises GTK (its GtkApplication) only insideRunand makes each window from a default-idle-priority callback on the main loop, sofontDPI, called just beforeRun, queues the check as aG_PRIORITY_HIGHidle: it runs on the main thread after GTK's own start, before the first window.TestFontDPIUnsetopens a real WebKitGTK page throughmagpie_font_dpiand needs a display (Xvfb).Tests never touch a live agent config. The package's
TestMainruns undertestenv's home of its own. A macOS test that shows windows runs them in a process of its own throughrunAppKit(appkit_darwin_test.go). AppKit and WebKit take their home from the account, not from HOME, sorunAppKitgives them a temporary one withCFFIXED_USER_HOME; appearance, contrast and languages still come from the account. The test fails when that process leaves a folder in the real~/Library/WebKitor~/Library/Caches. Playwright tests serveassets/with isolated/apifixtures.POST /api/settings/codex-auto-reviewaccepts an empty value (Codex's own choice, or the session's model when Codex's sign-in is on a Free plan),session(the session's own model when it is one of magpie's; "Same as the session" in the picker), or an exact model/group ID inprovider.Served, including unlisted providers. A known provider with an unknown or empty model name is rejected without changing the saved reviewer or catalog tag. Generic gateway request resolution remains permissive; it is not the validator for this setting. SeeHandlerinapi.goandTestCodexAutoReviewSettingincodex_auto_review_test.go.Settings -> Sync and backupand/api/davsync/{action}configure and run encrypted WebDAV, S3 or GitHub setup sync. They share the CLI's operations and expose credential presence, never the secrets. State, merge, failure and compatibility behavior are described in Sync and backup.
openModal makes the background inert when an editor opens fresh, leaving
confirmations and menus interactive through redraws. closeModal releases
that background as soon as the close animation starts, so clicks reach the
page while the editor fades away. Opening an editor during that animation
protects the background again. ux-safety.test.cjs checks these transitions.
Routing's New group buttons share newGroup, which asks before replacing a
dirty group draft; Cancel retains the draft and Discard opens the new editor.
newGroupWith applies the same guard when creating a group from a model and
waits for show to accept navigation before creating its draft.
The Routing page's head also has Routing groups (#rtGoGroups), since the
groups sit below every request. Its click goes through scrollOnPurpose,
brings .rt-gsec to the top of the view and focuses it; the page's layout is
unchanged. fitGo gives it only the head's spare room: named, its arrow
alone, or left out, so nothing else in the head moves or wraps for it
(routing-groups-jump.test.cjs).
The Plugins page updates the npm search-results section when a search answers,
leaving suggested plugin cards in place so a click begun before the answer still
opens the intended plugin. plugin-market.test.cjs holds the search response
between pointerdown and pointerup to check this in Chromium and WebKit.
Routing shown by the magpie that serves the gateway
A magpie on this computer that does not serve the gateway shows the serving
one's routing in its Routing page, instead of the notice that its routing
cannot be watched here (#2606). The trigger is served.Load() being nil while
a magpie answers at the gateway's address. Then /api/gateway/trace reads
the serving magpie's GET /v1/magpie/trace over loopback
(OwnerTrace) and answers with it as its
own (mine true, so the page plays it), and /api/lanes reads
GET /v1/magpie/concurrency (OwnerLanes)
so a provider's rows show the same pills. Both are read on loopback alone
(ownerURL): a gateway address on another interface or host is never asked,
whatever MAGPIE_ADDR says, and one listening everywhere is read at
127.0.0.1. OwnerTrace lets a hung magpie go 5s past the 25s long poll, or
when the page stops asking; OwnerLanes waits 700ms, as ServedBy does, and
is asked only when a magpie answers. The state read carries the serving
magpie's serves and pid (gatewayJSON),
and the trace carries them as by. The Routing page's heading names the
magpie from by ("serve (pid 49217) is routing · 127.0.0.1:3525"), so the
name goes with the trace: when the page's trace comes from another magpie
than before (a takeover, either way), it drops the routes it had and reads
the new one's whole trace. Nothing is written; serving and takeover are
unchanged. A
magpie that serves the gateway keeps its own trace, and one older than the
endpoint keeps the notice as before (a refused or unreadable read is unknown,
never empty: OwnerTrace says so with its second result). See
TestConsoleShowsTheServingMagpiesRouting and
TestConsoleKeepsTheNoticeFromAnOlderGateway in
trace_peer_test.go, and
TestGatewayTraceIsLoopbackOnly in
trace_peer_test.go.
A restart to update hands the gateway over
On a Mac and on Linux, a restart into a downloaded update (the Update pill, Settings › Version, the tray's Restart to update, Restart automatically) starts the new version beside the running one and hands it the gateway's listening socket, rather than ending the gateway and waiting for the new one to listen again (xuanwo on X). Nothing an agent sends meanwhile is refused: the port never closes, and requests already in flight finish in the old process.
The trigger is handsOver in
handover.go: the app (Run sets
handoverHost and startExe), on darwin or linux, serving the gateway
itself, not a dev backend (whose own handover is gateway.Handover,
below) and no MAGPIE_NO_HANDOVER in the environment. restartInto in update.go
then calls beginHandover instead of the relaunch-after-exit. The steps:
- The old magpie opens an Offer (
internal/handoff): a unix socket in a 0700 temporary folder (in/tmpwhenTMPDIR's path leaves a socket's name no room,sockDir), named byhandover.jsonin the config folder with its pid, its program path and the time. Then it starts the new version beside itself:open -non the bundle on a Mac (update.OpenBeside), the binary at the path it started from on Linux (update.StartBeside;startExe, since/proc/self/exereads "(deleted)" once the update replaced it). - The new magpie's
RuncallstakeOverbefore anything else: a pointer fresh (2 minutes), of a process still running, for the same program and not its own is dialled, the new one says hello, and receives the listening socket (SCM_RIGHTS) with the address, the bridge's callback socket and the old pid (handoff.Take). The peer's uid is checked on accept.gateway.Inheritkeeps the socket for the nextListenAndServeon the same address (sameAddr; another address lets it go), which serves on it and then acks. - The old one, on the ack (
AwaitAck), withdraws the pointer, hides itself where it can (below), callsgateway.Server.HandOff, ends its backend and waits for its requests, then quits.HandOffcloses the old one's own copy of the socket at once, so every connection from then on waits there for the new one: one the old one took as its end began was closed unanswered (#3568). A handed-off server's shutdown waits up tohandedOffDrain(15 minutes) for requests in flight, not the 2s an ordinary quit gives them (shortDrain), and first lets each connection it took send its first request (unreadWait, 5s at most), sincehttp.Server.Shutdowncloses one whose request it reads after it began. ItsOnShutdownthen skips what goes with the gateway, which the new one now does: ending Codex's failover, porting Codex rollouts and installing the update. - Should the Offer not open, the new version not start, not say hello in
60s (
helloWait), not ack in 90s (ackWait), or drop the connection, the old one keeps the socket, takes its instance lock back and restarts as before: the new one opened once it has exited (fail,update.RelaunchorrelaunchBinary). It first waits, still serving, for its requests in flight to finish (at mostfallbackWait, 15 minutes), since the restart was let go without waiting for them. A second restart click while a handover is under way does nothing (pending).
Two magpies never show at once. On a Mac the old one lets go of its
instance lock before it gives the socket (releaseInstance), so the new
one's runningAlready takes it, and once the ack comes the old one hides
its menu bar icon, panel and window and leaves the Dock (onHandedOver,
leaveMenuBar). AppKit keeps a status item's setVisible:NO in the
app's defaults by its autosave name (NSStatusItem VisibleCC Item-0 on
macOS 26), which the new one's item and every later one start from, so
the hide is forgotten once it is made (forgetTrayHiddenLater,
trayshown_darwin.go). From
v0.1.1354 to v0.1.1367 it wasn't, and the icon stayed gone after the
update, through a quit and reopen too (Mitsuha, audie). bringTrayBack
forgets a kept hide once per computer before the tray is made, and a
magpie handed over to by an older one forgets it again once that one has
quit (awaitExit), unless a hide was kept when it started: one kept after
the bring-back is the user's (TestHandoverLeavesTheMenuBarIconForTheNextMagpie).
On Linux the D-Bus name Wails holds can't be let go, so the new one serves
the gateway at once but waits for the old pid to end (awaitExit, at most
handedOffWait, 16 minutes) before it makes its app and tray; the old one
keeps its tray icon until it has drained.
What the old process alone has:
- Sticky routing (which account each conversation stuck to) is flushed to
disk before the socket is given (
gateway.FlushSticks). - Claude Code runs the subscription bridge started send their tool calls
to the gateway's port, which the new one now serves. The old one serves
them on a unix socket in the Offer's folder (
ServeCallbacks), and the new one forwards a claude-mcp token it doesn't know there (ForwardCallbacks,forwardCallback;ownCallbacklets them in while forwarding is on). See Claude subscription bridge. - Bridge turns can't move to another process, so a restart that hands
over waits only for them (
restartBusy,blocking:Busy.Bridgeas Requests,Tools,BridgeLastas Last). The page is told (updateJSON.Handover) and says it waits for the Claude subscription's replies, with other requests carrying on across the restart. - Refreshes of rotating OAuth tokens hold a file lock across both processes (see Providers and accounts).
Not carried over, accepted: each process counts its own requests per minute and concurrency, so for the drain a provider's limits can be exceeded by what the old one still has in flight; a bridge run idle between turns ends with the old process, and the next turn starts a new run as after any restart; the new one's start-up migrations run while the old one still serves its last requests.
Windows has no SCM_RIGHTS for a listening socket in this form, and
magpie web re-executes itself in place; both restart as before, waiting
for the gateway to be idle (#577). make dev keeps its own handover, a
new backend listening beside the old one (gateway.Handover, devBackend).
See TestRestartHandsTheGatewayOver (the new version a second process,
a stream across the restart finishing whole, requests during it answered,
and the old one quitting only after its stream) and
TestHandoverNotMadeRestartsAsBeforeOnceIdle in
handover_unix_test.go,
TestRestartWaitsForWhatAHandoverCantCarry in
handover_test.go, the gateway's
handover_test.go, the
socket passing in handoff_test.go,
and update-wait.test.cjs.
Verification
The session readers include Cursor CLI chat stores, Cursor editor project
transcripts and older editor cursorDiskKV conversations. CLI stores win
when the same session ID has a project transcript. Editor conversations are
read only, including at the delete API, and cannot be resumed by cursor-agent.
Project transcripts contain no message timestamps or billing data; their
existing file modification time supplies the activity date, and tokens and
cost are not inferred. Database bubbles retain their own timestamps.
The editor database is opened as one read-only snapshot per listing, shared
by its chats and removed when the listing ends. Metadata changes invalidate
the cached summary even if the project transcript has not changed. See
cursor_editor.go,
TestCursorEditorTranscript and TestCursorEditorLiveDatabaseAndMetadataRefresh
in cursor_editor_test.go.
Messages without tokens or an active-time estimate still count as sessions
in the overview. Cursor and OpenCode conversations can be opened through
the existing transcript API, including CLI reasoning and tool calls. So can
Kimi Code's main agent, from its wire.jsonl: a turn's turn.prompt and
loop events from protocol 1.4 on (so a turn still running shows), and the
untimed context.append_message records of a session imported from
kimi-cli; Kimi Code's own timed messages repeat those and are skipped
(transcript_kimi.go,
TestKimiCodeTranscript). Each reply in the conversation names its model
(#2253), muted after its first part and again where it changes inside a
reply: a part's model is what its own line in the agent's file names,
Claude Code's message.model (the model that answered; none for its own
<synthetic> lines), Codex's turn_context.model (the model the turn was
sent to), Pi's and omp's message.model, OpenCode's modelID or OpenCode
2's model.id. Kimi Code (whose model is only on a usage.record after
the reply), Cursor and a gateway transcript (which records the model asked
for, not the one that answered) name none, and nothing is guessed in their
place. The Usage page's per-request content doesn't repeat it. See
TestTranscriptModel* and sessions-talk-model.test.cjs. When the
selected date range is empty but
matching history exists, Usage offers All sessions, preserving the agent,
model, folder and search filters. See sessions-empty-range.test.cjs.
go test -tags nogui ./internal/gui
go test -run TestMainWindow ./internal/gui
GOARCH=amd64 CGO_ENABLED=1 go test -run TestMainWindow ./internal/gui # as for an Intel Mac
go test -run TestWebView2 ./internal/gui # on Windows: Wails' runtime lookup, missing and present
go test -v ./internal/fonts # native discovery on each desktop OS
make test-ui # every internal/gui/tests/*.test.cjs, Chromium and WebKit
BROWSER=webkit node --test internal/gui/tests/click-scroll.test.cjs
make test-ui needs Node.js and Playwright (playwright install chromium webkit). Set NODE_PATH when Playwright is installed outside the repo. The
Test workflow in CI does not run this suite, so a GUI change must run it
locally and report the result. See tests/README.md.
TestMainWindowCorners and TestMainWindowRightToLeft run on a Mac with a
desktop session, as CI's macOS job has, and show a few windows for some
seconds. On macOS 26 they check both designs, whatever SDK the toolchain
links against. CI builds them for arm64. Built for amd64 (under Rosetta on
Apple silicon), they check a program that names its SDK in
LC_VERSION_MIN_MACOSX, as go test links one for an Intel Mac. Their
presses are sent within the test's own process, and no system setting
changes.
Agent visibility management
The Agents page's Manage button sits inside the list's footer beside the fold
control, and stays available when nothing is folded. The tray panel keeps its
existing fold control. The Manage agents dialog includes folded and hidden agents.
Search matches names and IDs; select all and invert apply to the search results,
while Select unconnected agents replaces the selection with matching agents not
on magpie (neither wired, added nor drifting). Selection survives search changes.
Hide selected and Unhide selected each save one arrangement through the existing
POST /api/agents/arrange, preserving order and agents outside the operation.
Only a successful save changes the list; a failure keeps the selection for retry.
While saving, Done, Escape and the backdrop cannot close the manager and expose
conflicting row actions. Closing is restored on either success or failure.
A completed save invalidates older in-flight state reads for the arrangement
fields only. Fresh reads still accept other windows' visibility changes; bulk
unhide does not add a lasting client-side override. These races are covered by
agent-visibility-saving.test.cjs.
While the manager is open, state refreshes update its visibility labels and
action availability in place, preserving the search, selection and keyboard focus.
These operations never connect, disconnect or edit an agent's files. Unhiding
still follows the existing Not set up folding rules. The dialog explains that
restoring visibility does not pin an unconfigured agent into the main list.
See agent-bulk-visibility.test.cjs for persistence, partial selection, failed
saves, narrow layouts and all five languages in Chromium and WebKit.