Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.
Library: instructions, MCP servers, skills, hooks, subagents and RTK
The library keeps what every agent should know in one place: the
instructions each agent reads before a conversation, the MCP servers it can
call, the skills it can load, the hooks it runs at points of its turn, and
the subagents it can hand a task to.
magpie writes these into each agent's own
files in that agent's format, and takes back only what it wrote. Everything
else in those files stays as it was. Package internal/library also gives
agents RTK, a CLI that cuts shell output down before the model reads it.
Responsibilities and sources of truth
| Part | Responsibility | Source |
|---|---|---|
| library.json | Library holds the instruction sets, the MCP servers, the skills, the projects, skill groups and copy settings. Applied records what magpie last wrote into each agent, so it only ever takes away its own. The instruction texts and skill folders live under Dir (library/ in magpie's config folder). |
library.go |
| One change | change locks the library, loads it, applies one edit, saves, syncs every agent and saves again. Every exported mutation (SaveServer, InstallSkills, SetSkillHow and the rest) goes through it. One change runs at a time, whether from the page or the CLI. |
library.go |
| Targets | Targets lists the detected agents (agent.Detected), a folder an agent shares with its vendor's other app when only that app is here (agent.SharedHere: the Cursor editor's ~/.cursor, whose mcp.json and skills it reads, listed as Cursor; TestCursorEditorAloneKeepsItsLibraryRow), plus apps like Claude Desktop, with where each keeps its instructions file (and an Override it reads instead), its MCP file and its skills folder. An agent whose CLI is gone (CLIMissing: an uninstall that left the folder behind, #2177, #2254) is no target: it is given nothing it can't read. One that isn't a target but still has skills, servers or hooks magpie gave it (in Applied, or listed in an item's Agents) is held (held, a Target with Gone): a sync takes edits from its copies and then only takes out of it (syncSkills, syncMCP and syncHooks give a gone target nothing new), and Read lists it with gone: true while it has any. The page shows a gone agent's chip only on the rows of what it has, lit, so a click takes it out (withGone in plugins/library/client.js), leaves it out of All, the per-agent How sheet and every picker, and lists it in By agent as Not installed here with Turn all on off (@jiahao_jayden on X: an uninstalled WorkBuddy was on every skill's row; TestGoneAgentListedToTakeOut, library-gone-agents.test.cjs). On a Mac WorkBuddy and WorkBuddy AI are detected by their apps' bundle ids (com.tencent.workbuddy.mac, com.workbuddy.workbuddy-ai, macBundle), not by ~/.workbuddy, which an uninstall leaves and magpie itself writes into (TestWorkBuddyOnMacIsItsApp); off a Mac the folder still counts. everyTarget keeps it for the guards that refuse an agent's own places: a project folder whose skills folder or MCP file is the agent's, and an instruction set kept in its instructions file. An agent in a running WSL distro has its places under the distro's home (wslTargetOf): Claude Code, Codex, Pi, OmO, Gemini CLI, Antigravity CLI, Crush, Cline, CodeBuddy Code, Kimi Code and Goose each by its own rule, never reading this machine's variables (Kimi Code's and Goose's shared ~/.agents/skills there isn't given), Pi's MCP file chosen by piMCP as on this machine from the version the distro's pi --version gave its probe (InstalledVersion) and the distro's npm folders (wslPiRoots; leokon on Discord: only the Windows Pi was offered MCP servers, TestWSLPiMCP, TestWSLMCPSiblings), and every agent that keeps all of them in its own folder (Hermes Agent, omp, OpenCode, Droid and the rest of ownFolder, #1323) by the same rule as on this machine, its MCP file marked as WSL's so a Windows program isn't given to it. An agent a plugin adds (a.Plugin) has the places its plugin's agent.library names (pluginTarget): an instructions file, an MCP file in one of agentplug.MCPFormats (each the mcpFormat of the agent it is named for, pluginMCP) and a skills folder, ~ and $VAR expanded as its config is; one that names none is no target. Before, a plugin's agent got models and keys only. |
targets.go |
| Stopped WSL distro | A stopped distro's agents are no targets: opening their files would start the distro, or the read fails (#3896). While a distro runs, keepShape keeps each agent's places and what its MCP file takes in wsl.json (agent.WSLKeep, key library:<kind>). While it is stopped, Read lists its agents from that (asleepView, asleep: <distro>), ticks as library.json has them; one magpie never saw there is listed only on the rows that name it, as unseen, its ticks not shown (cybercaius on Discord: the MCP page knew a distro's agents only once WSL had started). A tick on a stopped agent is kept in library.json as any is (Takes accepts one with a known shape; serversAgents judges it by shape.reaches), nothing is written and nothing in the distro runs; Woken, from KeepLinked's loop (and the app's start-up sync), syncs when a distro the library names is seen go from stopped to running (wsl.exe -l --running, which starts nothing). The page greys a stopped agent's chip, says so in its tooltip and in one line per distro (.lib-asleep); an unseen chip is aria-disabled and kept by every click on its row (keptOf). The CLI says the same on stderr (AsleepIn). Queued, not a start button: a start costs the memory #3896 is about, and All or a bulk tick would start every distro. The Instructions, Hooks and Subagents pages leave a stopped distro's agents out still (#4182, #4237, #4238). |
wsl_asleep.go, targets.go, plugins/library/client.js |
| Sync | sync writes each target's instructions and MCP servers. It then takes edits made in agents' skill copies into the library (takeEdits) and links or copies the skills. ~/.agents/skills goes first, so an agent that reads it gets no second link. Then it syncs projects' skills. |
sync.go |
| Projects | A project (Project) is a folder given some of the library's skills and MCP servers, each for some agents. A skill is linked (or copied) into the folder the agent reads a project's skills from (projectSkillsDirs): .claude/skills for Claude Code, .qoder/skills for Qoder and Qoder CN, .codebuddy/skills for CodeBuddy Code, .commandcode/skills for Command Code, and .agents/skills for Codex, Gemini CLI, OpenCode, Pi, Cursor, Copilot CLI, Antigravity, Kimi, Goose, Grok, Droid and Cline. A server is written into the file the agent reads a project's servers from (projectMCPFiles), in the shape its user-wide file has: .mcp.json for Claude Code and CodeBuddy Code (CodeBuddy's mcp.json when the project has that and no .mcp.json, since it reads only the first of the two), .codex/config.toml, .gemini/settings.json, .cursor/mcp.json, opencode.json, .zcode/config.json, .pi/mcp.json, .qoder/settings.json's mcpServers for Qoder and Qoder CN, and .factory/mcp.json for Droid. Claude Code, Qoder and CodeBuddy ask the user to approve a project's server before using it. Only targets whose vendor source or docs name them are listed (each map's comment cites them); an agent with none (Copilot CLI's MCP, Zed, WorkBuddy, Command Code's MCP, whose .mcp.json has its own transport shape) can't be picked for a project (eirc on Discord). Placed, Wrote, Made and MadeFiles record what magpie put there, the only things it takes away, and what it made is listed in the project's .gitignore. |
projects.go, project_mcp.go |
| Instructions | magpie's part of an agent's instructions file sits between two marker lines. The rest of the file is the user's. Several named sets can be switched between (#106). A set can be kept in a file of the user's own instead of instruction-sets/ (InstrSet.File, 新v学员 on Discord): ~/.agents/AGENTS.md, which Droid and omp read too. textPath reads it, putText keeps it aside and writes it but never removes it, removing the set lets go of it, and linkable refuses a file magpie writes into (an agent's own instructions, a file with the marker line), the library's own and another set's. The app's KeepLinked looks at the file every 30 s and writes a change into the agents (SyncLinked). A set's text is read without magpie's part (setText), and an agent whose instructions file is, links followed, the file the set on is kept in (isSetFile: instructions.md linked to ~/.claude/CLAUDE.md, or both linked to one dotfile) gets no part written into it, and one written before is taken out with every part nested in it: read with its part, each sync wrote the whole file into that part again and it doubled, to gigabytes (#2349, TestInstructionsSetLinkedToAgentsFile). Collect carries the set's text, not where its file is; Put keeps this computer's file for the set and never empties it for a text not carried. Alma's file is ~/.config/alma/USER.md, which its main chat reads into its system prompt as its owner's profile (0.4.164's out/main/index.js; a workspace's USER.md is read instead), and whose leading front matter (name, telegram_id, discord_id) is who its bots answer to (#2315, Jie211). The target is a Profile: magpie's part goes after the user's, so the front matter stays first, and ImportInstructions refuses it, as moving it out would take that front matter out of the file and into every agent's (TestAlmaInstructionsKeepTheProfile, TestAlmaProfileIsNotImported, library-alma-profile.test.cjs). |
instructions.go |
| MCP servers | A Server is a command or a URL (http, sse). mcpFile encodes it in each agent's own format (one mcpFormat per agent family) and merges it with the user's own fields for that entry. A server's StartupTimeout (#3168) goes to Codex alone, as startup_timeout_sec in seconds (RawMcpServerConfig in codex-rs/config's mcp_types.rs; 0 leaves Codex's own 30s), in the user-wide config.toml and a project's alike. magpie keeps the value it wrote (Applied.Startup, Project.Startup): one in the entry other than that, or a startup_timeout_ms, is the user's and stays as it is (startupTheirs), and once it is taken out magpie's goes in again. The editor shows the field only when an agent that takes it is here (AgentView.Startup, mcp_startup_test.go, mcp-startup-timeout.test.cjs). Also files get the same servers; Extra files are only read when importing. CheckServers connects as an agent would and keeps the result in memory only: with each tool's name and the first paragraph of its description (ToolList, at most maxToolList, a description cut at maxToolDesc runes), which the page lists when the server's "N tools" is clicked, following tools/list's nextCursor up to maxToolPages pages (listTools). Each step (initialize, notifications/initialized, tools/list; connect for SSE) has its own budget, 60s for a URL and 30s for a command (remoteStep, stdioStep), and a timeout names its Step and how long it Waited; a timeout isn't kept, so the next look asks again (#1467). A command named bare that magpie's PATH lacks is started from where proc.FindTool finds it (fnm's Nodes on Windows among the folders), with that folder on the check's PATH, since npx's package runs the node beside it by name (stdioProgram, #2685, TestStdioProgramFindsWhatPathLacks). The page asks once a session for the servers some agent or project has (inUse in plugins/library/client.js); one no agent has shows "not checked" and is checked only when its status is clicked (#1597, library-mcp-health.test.cjs). A server checked once is checked again when it changes, its sign-in included, so a server signed in to after a click's "needs sign-in" isn't left showing both (新v学员 on Discord, mcp-signin-health.test.cjs). The check sends magpie's sign-in as the gateway does: on a 401 it renews the token once and asks again, and a server that refuses even the renewed token has the sign-in marked run out (mcpauth.Rejected, also from the gateway's /mcp/<name>), which ServerHealth.SignIn carries back so the row's tag says "Sign-in ran out" rather than "Signed in" beside "needs sign-in". A server that refuses the check (401 or 403) but that an agent signed in to on its own is named so (ServerHealth.AgentSignIn, readOwnSignIns in mcp_agent_signin.go): each Claude Code target's .credentials.json beside its settings.json, a WSL distro's under the distro's home, is read for a mcpOAuth entry of the server's name and URL with a token, and the row says "signed in in Claude Code (Ubuntu)" instead of "needs sign-in" (CyberCaius on Discord: signed in to with Claude Code's /mcp in WSL). The tokens are never sent or kept; a file that can't be read or parsed names nobody, a stopped distro isn't started for it, and on a Mac only the file is read, never the Keychain Claude Code keeps them in. They are part of the check's key, so a sign-in in the agent since is checked anew (TestCheckNamesAgentsSignedInThemselves, library-mcp-health-wsl.test.cjs). A server that needs OAuth is signed in once in magpie, and agents reach it through the gateway's /mcp/<name> (#615). The editor's Sign in saves the form first only when the sign-in is to another server than the saved one (a new server, a name or URL changed), and its button then reads "Save and sign in"; anything else edited (headers, env, arguments) stays unsaved until Save, so Cancel leaves the server as it was (新v学员 on Discord, mcp-editor-cancel.test.cjs). A server whose authorization server refuses magpie's dynamic client registration with 401 or 403 admits only the clients it lists (Figma's, #1619): the sign-in fails with mcpauth.ErrClientRefused, which says so and that each agent signs in itself, and the agents keep the server's own address. A server whose authorization server has no registration endpoint at all (GitHub's remote server, 新v学员 on Discord) fails with mcpauth.ErrNoRegistration, which says to make an OAuth app with the vendor and give it in the editor; the editor then opens its "OAuth app" fields. The app is the server's oauth (OAuthApp: clientId, clientSecret, callbackPort, Claude Code's names for --client-id, --client-secret and --callback-port), checked on save (HTTP only, a client ID, a port from 1 to 65535), and SignInServer signs in as it through mcpauth.StartWith without registering. The callback is Claude Code's, http://localhost:<port>/callback (its docs' "Use pre-configured OAuth credentials"; 2.1.296 builds it so), listened for on 127.0.0.1 alone as Claude Code does, so an app made for Claude Code signs magpie in as it is; a server that matches the registered URL exactly refuses another host, which is why Claude Code's 2.1.231 went back to localhost from 2.1.229's 127.0.0.1 (TestAppMadeForClaudeCode). Without a callbackPort the port is any free one, which a loopback callback registered without a port takes (GitHub's, RFC 8252); a fixed callbackPort is for a vendor that matches the port too. magpie's own registration, when a server has one, still names 127.0.0.1. The client secret is kept in library.json, as a header's or env's value is: a backup without keys leaves it out, and WithSecrets puts back this computer's secret only for the same client ID; no agent is given the app, and the TUI's editor, which doesn't show it, keeps it. GitHub answers a token request's error with a 200 and error in the body (bad_refresh_token, incorrect_client_credentials), which tokenRequest reads as the error it is, and a dead refresh token marks the sign-in run out (github_app_test.go, mcp-oauth-app.test.cjs). magpie never registers under another client's name; one that reaches the gateway from another machine (a WSL distro under NAT) is given it with the LAN sharing key as its Authorization (agent.KeyAt), as its models are, which the gateway takes in place of a sign-in and never passes on; turning sharing on or off, or a new key (access.LANChanged), writes such entries again. ConfigOfServers is the servers picked as an agent's project file (projectMCPFiles) would hold them, written by the same code into a folder of its own and read back, with those the agent can't take there named; the page's Copy config… puts it on the clipboard for a project magpie doesn't keep (#1478). Each listed tool has a switch: the tools turned off are the server's DisabledTools, set by ServerTools, and written into each agent given the server that can leave out a single tool (see the constraint below). A server run as npx -y <package> args (a registry package, no other npx flag) is given to an agent on this machine as node <the package's bin> args (npxDirect): magpie installs the package with npm into a folder of its own under mcp-npm in the background, the next sync writes the node form, and until then, or when npm fails (tried again after an hour), the agent keeps npx. npx otherwise stays as the server's parent for its whole life, a node and two cmd.exe beside each instance on Windows (#3885). An unpinned spec is installed again after a day, as npx would fetch the newer one; an install no library server runs goes a day after its last. The library, a server's check, Copy config… and agents in WSL keep npx (TestNpxServerRunsByNode, TestReadNpx). |
mcp.go, mcp_npx.go, mcp_check.go, mcp_signin.go, mcp_agent_signin.go, mcp_copy.go, mcp_tools_off.go |
| MCP hub | With MCPHub on, syncMCP gives each agent that can take it one entry, magpie, at the gateway's /mcp/magpie/hub/<agent>, in place of the servers ticked for it; magpie runs those servers itself, once for every agent. |
MCP hub, mcp_hub.go |
| Skills | A skill is a folder with a SKILL.md. It goes by the name its front matter gives, made fit for a file name (ASCII letters, digits, _ and -); a name that would lose a letter or digit that way (one in another script, CTF•密码学) or none goes by its folder's name instead, and a skill at a repository's top by the repository's (nameFor, srcFolder). Two skills a probe names alike are listed once (unhiddenFirst), so names that fell to CTF, Strix and nothing listed asdfgh1445/ctf-super-hub's 35 skills as 16 (tnt1223 on Discord, TestSkillsNamedInAnotherScriptAllListed). It comes from GitHub, from any other git repository, from a folder on this machine (linked, so editing the folder edits the skill) or from the market. A git repository (kind: git, sunset on Discord: GitLab, a company's own GitLab) is any https, http, ssh or file:// address, git@host:group/repo.git, a bare host.name/group/repo, or a GitLab or Gitea page of a folder (/-/tree/<ref>/<path>, /-/blob/…, /src/branch/…; a branch with a / in its name is read as its first segment) (gitSource). It is fetched by the user's own git (proc.FindTool), so their credential helpers and SSH keys reach an intranet host: git init, then fetch --depth 1 --no-tags -- <url> <ref> and checkout FETCH_HEAD into a magpie-skill-* folder, then its .git is removed (fetchGit). What the user typed is data: an address starting with - and a transport:: address (ext::, fd::, file::) are refused before git runs, the address follows --, git runs with protocol.ext.allow=never and core.symlinks=false, no shell, GIT_TERMINAL_PROMPT=0 and (unless the user set an SSH command) ssh -o BatchMode=yes, so a sign-in it can't make fails instead of waiting. An address with a password or token in it is refused: library.json is shown and backed up. Git missing, a sign-in refused, a host key unknown, a branch missing and a host unreachable each say so (gitError; TestGitSourceReads, TestInstallFromGitRepo, TestGitTreeURLInstallsFolder, TestGitMissingSaysSo, TestGitSignInRefusedSaysSo, TestGitRefusesOptionsAndTransports, TestGitErrorsSaid). Each agent gets a link or a marked copy (#896, SkillHow). An agent in a WSL distro always gets a copy. A copy's mark keeps the hash of what was copied, so a sync knows a copy unchanged since then is current without reading its files (copyIsFresh, #1031); other copies are hashed. A skill an agent has of its own (foundSkills, the page's "In your agents") is brought in with ImportSkill, or taken out of every agent that has it with RemoveFoundSkill (#1303): its folders and copies of the very same files, its shared ~/.agents/skills entry and a folder of it in the library's own folder go to the backups, its links are taken away, and a folder elsewhere it only links to, or another skill by that name, stays. Several go at once with RemoveFoundSkills (POST /api/library/skills/remove-found-some, wongxy on Discord): the "In your agents" heading's own Select picks them, and Remove… asks once, naming the count, before one change takes each out as RemoveFoundSkill would. A name that can't be taken out is left as it was, in Result.Unremoved, and stays picked with its error in its row's place (foundErrs); when none can go the change fails and nothing is touched. This Select and the library's are never on together: while one is on the other is dimmed, saying why, so neither click takes the other's bar away from above the pointer (TestRemoveFoundSkills, found-skill-pick-remove.test.cjs). A repository is fetched as one tarball of at most maxFetch (200 MB); a bigger one is fetched file by file from its tree (fetchSkillFiles), only as far as the caller reads: a link to a folder and an update ask GitHub for that folder's own list (treeUnder, git's ref:path; the whole list when that fails), the market fetches only the skills whose folder is the one it installs (#2794, sickn33/agentic-awesome-skills' 8,589 skills are 287 MB together), and a fetcher keeps such a part apart from another skill's of the same repository, which would otherwise read as removed (fetcher.get, TestMarketSkillFromAHugeRepository). GitHub's list is read up to maxTree (64 MB; that repository's is 11 MB) and an answer over the cap a caller gives apiGet, or one cut off, is an error saying so, never a body cut short for JSON to trip on (ye4241's TestRepoTreeBigList, TestApiGetWholeAnswer); a list GitHub truncated itself is too big (TestTruncatedListIsTooBig). And a skill over 200 MB on its own is left out rather than failing the rest: the probe lists the others and names it in Probe.Left, under the list in the page and in the TUI's flash. Only when every skill is too big does the fetch fail (#2062, mikubaka88/CCFA-Skills' 297 MB ccf-paper-writer; TestOneSkillTooBigLeavesTheOthers, skill-too-big.test.cjs). A probe keeps its download for the install from it for 15 minutes (keepProbe, probeLife), and removes it when it is probed again or that time is up, not at the next probe, which may never come. A download a magpie that quit left in the temp dir goes at the next probe once it is an hour old (sweepStaleDownloads). The package's TestMain gives the tests a temp dir of their own and fails a run that leaves a magpie-skill-* in it (#2321, TestProbeDownloadEndsWithIt, TestStaleDownloadsSwept). |
skilltree.go, skills.go, skillgit.go, skill_how.go, skill_edits.go, skill_from.go |
| Skills market | MarketSkills lists skills.sh's most installed and what its search finds. magpie's own skills (featuredSkills), in magpie-community/plugins, go first, marked official: magpie-setup has an agent set magpie up as the user asks through its commands (providers, accounts, agents, routing groups and rules, gateway keys and limits, models, the library), and magpie-quota lets an agent read magpie quota --json and wait with magpie quota wait. Their commands live in magpie's CLI, so a change to a command either uses gets the skill updated in that repository. Until skills.sh lists one it has no count of installs and no skills.sh link (featured). InstallMarketSkill installs any of them from its repository. |
market.go |
| Skills a repository added | A check for updates (CheckSkills) also asks, for each GitHub repository and ref the library has skills from, GitHub's list of its files (repoTree, one API request, free when the ETag still matches). Only when that list has a skill folder beside the installed ones (under newBase, their deepest common folder) that the library doesn't have and hasn't offered does findNew fetch the repository for the skills' names and descriptions. SeenSkills records per repo@ref the paths the install picker showed and the ones set aside, so they aren't offered again. The finds live in memory (newFound) and reach the page as View.NewSkills; AddNewSkills gives each to the agents that have its repository's other skills, and IgnoreNewSkills sets it aside (/api/library/skills/{add-new,ignore-new}). |
skillnew.go, skillcheck.go |
| Skill groups | The page groups skills by SkillView.Repo, the repository each came from (tracer.repoOf): its GitHub source, CC Switch's Origin, From, the skills CLI's lock or the git checkout a linked folder is in. A lock entry of sourceType: well-known (a site's kit at its /.well-known/agent-skills/) is grouped by its sourceBaseUrl as host/path (wellKnownBase), not by each skill's own sourceUrl: Feishu's lark-* skills are one group and Fish Audio's another, while two kits under one host with different base URLs stay apart. An older entry with no base URL takes the part of its sourceUrl before /.well-known/, and one with neither is grouped by its sourceUrl as before. Such a kit is never fetched from GitHub by Group again, even when it reads like owner/repo (a GitHub owner has no dot), and its heading's link opens the site (#1862, TestWellKnownKitGrouped). From is written when a repository is probed (installing from it again, noteFrom): for a skill with the very same SKILL.md, and for one traced to nowhere by a name the repository has when the library has others from there, since a pack added a while ago is mostly older copies edited there since (White Immortal on Discord: 20 of mattpocock/skills' 38). Group again (RegroupSkills, POST /api/library/skills/regroup) fetches each GitHub repository the skills are traced to and does the same; it fails only when none could be fetched. A skill traced to another repository is never moved. A group's (or part's, or the Select bar's) agent chips count, give and take only the skills magpie decides for each agent: one kept in ~/.agents/skills is in SkillView.Always for the agents that read that folder themselves, so a chip's agents-some for such an agent leaves it out, its tooltip and the status after a click say how many it still reads itself, and an agent that reads every one of them itself has a lit, locked chip as the row's is, which sends nothing (groupChips in plugins/library/client.js). The heading says how many of its skills are in ~/.agents/skills. A row's locked chip is lit with a lock on its corner, not greyed like a chip that can't be given the skill (#1862, skill-group-shared.test.cjs). Collapse all / Expand all, beside the sort, folds or opens every group the list shows at once (foldAllButton): without a filter it sets each group's kept fold (magpie.libSkillFolds), as a click on each heading would; while filtering, only the groups the filter shows, till the filter changes (unfiltered), leaving the kept folds alone. It reads Collapse all while any shown group is open, is hidden with fewer than two groups (A→Z, or a filter one group matches), leaves a part's own fold as it is and sends nothing (#1862, skill-fold-all.test.cjs). |
skill_from.go, plugins/library/client.js |
| Skill updates | A skill from GitHub (kind: github, a market install among them) keeps the commit it was fetched at and Hash, the hash of its files as fetched. CheckSkills asks GitHub for each one's last commit and keeps the result in memory; View.CheckDue says none was checked since magpie started, or not for checkEvery (12 hours), and the page then checks by itself as the skills open (#1449). editState says a skill was changed here when the library's folder no longer hashes to Hash (.DS_Store aside), or an agent's copy was edited since its mark and not yet taken in; the view's edited says so. What installing a skill's dependencies or running it writes in its folder is no change (fromInstall: node_modules, .venv, venv, __pycache__, .pytest_cache, .mypy_cache, .ruff_cache folders, *.pyc/*.pyo, and package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, bun.lockb, uv.lock written again; ggbr on Discord): Own is the hash of the files as fetched leaving those aside (ownHash), and onlyInstalled compares the folder with it, or for a skill fetched before Own was kept with Hash (so a lock file the install wrote again still reads as changed until its next update). An update carries those entries over to the version fetched where it has none of its own (carryInstalled), so they aren't installed again. UpdateSkill refuses such a skill with *EditedError unless told to replace it (the page's own Update asks first; the CLI takes --replace-edits), and UpdateSkills/UpdateSomeSkills leave it as it is, in Unupdated. A replaced version that was changed, or that can't be told (no Hash), is moved to the backups (keepReplaced). Skills the skills CLI manages (npx skills, ~/.agents/.skill-lock.json, or $XDG_STATE_HOME/skills/.skill-lock.json when that is set, both read with the XDG one winning) are only grouped: the CLI updates them (npx skills update). A linked folder, a skill imported from an agent and a From-only skill have no remote to check; one CC Switch installed (Origin) can be updated by hand but isn't checked. A skill from another git repository (kind: git) keeps the repository's head commit it was fetched at in Commit, and Hash. A check runs git ls-remote for the ref (gitRemoteHead): the same head is current; another one is fetched shallowly, once per repository and ref in a check, and the skill's folder hashed, so a commit that left the skill as it was is current and its head is kept as Commit (checkGitSkill). Its *EditedError and the page's Changed here, Update and the question before replacing a change name that repository, not GitHub (editedError, skill-git-source.test.cjs). New skills in such a repository (findNew), Group again, icons and the market are GitHub's only. A skill whose source was read whole and no longer has its folder or SKILL.md was removed there (goneFrom; スライム on Discord): UpdateSkill returns *GoneError, UpdateSkills/UpdateSomeSkills list it in Result.Gone, not Unupdated, and a check gives it status gone. Each records Skill.Gone (the view's gone), cleared when a check or an update finds it there again. A fetch that failed, a skill left out of a fetch as too big (leftOutAt) and a folder that can't be read are unknown, never gone. Nothing is taken out by itself: RemoveGoneSkills (POST /api/library/skills/remove-gone, magpie library skill rm --gone [--yes], the TUI's d on the row) takes the ones named, or every one marked, as RemoveSkills does, folders to the backups, and keeps one found in its source again. The page tags such a row Removed upstream with no Update, says them apart from failures after Update all, and offers Clean up N in the group's heading (in the bar with one group), which asks first, naming each one and which was changed here (confirmRemoveGone, skill-gone.test.cjs). |
skill_changed.go, skillcheck.go, skillgit.go, skills.go |
| Hooks | A Hook (#1790) is a command, an event, an optional matcher, a timeout and the agents ticked for it. Its optional Description (#2011) says what it is for in any language, since its name is letters, digits, - and _: one line of at most maxHookDescription (200) characters, shown under the name; only library.json keeps it, and no agent is given it. Its event is portable (HookEvents: turn-end, after-tool, before-tool, prompt, session-start, each under the agent's own name) or an agent's own ("codex:PermissionRequest"), which only that agent is given. A portable tool event can be narrowed to shell or edit tools, each agent's own tool names for them. syncHooks writes each into the agent's own file and shape (hookSpecOf): Claude Code <claude dir>/settings.json, Codex hooks.json beside its config.toml, Gemini CLI ~/.gemini/settings.json (timeout in ms), Cursor ~/.cursor/hooks.json (flat entries, version: 1), and Grok Build ~/.grok/config.toml and Grok App agent-home/config.toml as [[hooks.<Event>]] array tables with a [[hooks.<Event>.hooks]] child. Grok Build and Grok App run the one CLI, so a grok:<Event> own event goes to both (sameHookFamily). Every other agent, and an agent in WSL, is refused with why, and the page greys its chip with that reason. The page also says when an agent has every hook turned off (hooksOff: Claude Code's disableAllHooks, Gemini's hooksConfig.enabled, Codex's [features] hooks). |
hooks.go |
| Subagents | A Subagent (#2283) is a name (lowercase letters, digits and -), a one-line description, a prompt, and the library's skills and MCP servers it uses, given to the agents ticked for it. syncSubagents writes it as a file of its own in each agent's user-level folder, in that agent's format (subagentSpecOf): Markdown with YAML front matter in ~/.claude/agents (with skills and mcpServers), ~/.factory/droids (with mcpServers), ~/.config/opencode/agents (mode: subagent), ~/.gemini/agents, ~/.qwen/agents, ~/.grok/agents, ~/.cursor/agents and ~/.copilot/agents (<name>.agent.md); a TOML role (name, description, developer_instructions) in $CODEX_HOME/agents. Skills and servers are named only where the agent's file can name them, and only those the library has. The page lists, per agent, whether it binds skills and servers (SubagentAgentView) and greys out an agent that takes none. |
subagents.go |
| Backups | Before a change first writes an agent file, backups copies it to BackupDir, one folder per change. The last keepBackups (30) changes are kept. The Backups button at the top of every tab, beside Library folder, opens that folder (libHead; Dade on Discord found it at the foot of a long page). |
backup.go |
| RTK | SetRTK runs rtk's own installer (rtk init -g …) for an agent being switched on. For one being switched off, it removes exactly what the installer wrote, using magpie's own code, which works even with rtk gone. ReadRTK reads each agent's files to say which have the hook. An agent gone for its CLI (CLIMissing, #2254) isn't offered rtk, but one that still has the hook is listed so it can be taken out. rtkSpec.blocked stops the installer where it would break an agent. rtkSpec.env tells the installer the agent's folder where rtk would pick another: Hermes Agent's is appdir.HermesHome (%LOCALAPPDATA%\hermes on Windows), which rtk is given as HERMES_HOME, since rtk 0.51 knows only $HERMES_HOME and ~/.hermes. Antigravity CLI (agy, #2202) gets rtk 0.51's own plugin for Antigravity, plugins/rtk in its global customization folder ~/.gemini/config (plugin.json, hooks.json with PreToolUse → rtk hook antigravity, rules/AGENTS.md), which agy plugin list lists; switching it off takes that one folder out. rtk 0.50 knows Antigravity only per project and fails rtk init -g --agent antigravity, so an older rtk is blocked (agyBlocked) and the row says to update RTK. OpenCode 2 loads only the plugin rtk 0.52 on writes (one default object with id and setup(), rtk-ai/rtk#4187); an older rtk's plugin is for OpenCode 1 and OpenCode 2 refuses it, so with an OpenCode 2 here an older rtk is blocked (openCodeBlocked) and the row says to update RTK (#2295). Under OpenCode 2, an old plugin left from before an rtk update counts as off once the rtk here can write the new one (openCodeHas), so switching it on writes the new one over it; with an older rtk it counts as on, so it can be switched off. A detected agent RTK has no hook for at all is still listed, from rtkNoHook, with the reason and a switch that can't be turned on (dsh: its hooks can allow or deny a command but not rewrite it, and rtk init has no --agent dsh; Grok Build and Grok App: rtk init has no Grok or Grok App agent, so both are listed with the switch off). The page's No RTK hook tag gives each agent's own reason and rtk-ai/rtk issue (rtkNoHookWhy in plugins/library/client.js: dsh #3847, Grok Build and Grok App #2136), and an agent with no entry gets no link; TestRTKNoHookIssuesAreEachAgents fails when the page and rtkNoHook cite different issues, or two agents cite the same ones without a reason in sharedRTKIssues. |
rtk.go |
| RTK in WSL | An agent in a WSL distro (claude@wsl:Ubuntu) is listed by its kind (rtkKind), and its hook runs in the distro, where Windows' rtk.exe is no command, so it gets the distro's own rtk (lex on Discord). rtkDistroOf asks the distro with wsl.exe -d <distro> -e sh -lc where rtk is (a login or interactive shell's PATH; else ~/.local/bin or ~/.cargo/bin, offPath), kept 15s; ReadRTK lists one RTKDistro for each distro its agents are in. Install RTK in WSL <distro> (InstallRTKIn, POST /api/library/rtk/install with distro, magpie library rtk install <distro>) runs RTK's own Linux installer in the distro (curl -fsSL …/install.sh | sh, wget where there's no curl). Switching an agent on runs the distro's rtk there (rtkInstallWSL: rtk init -g … with its folder on PATH, Claude Code pointed at a folder of its own for the OpenCode and Cursor installers), and reads and edits its files under the distro's home as magpie opens it (rtkClaudeDir, rtkCodexDir, rtkHome). A distro that isn't running is never started (#3896): rtkWSLLive and rtkDistroOf check agent.WSLRunning first, its agents are listed asleep with the switch off, and switching or installing says to start it (TestRTKWSLAsleep). The page gives each distro a card (rtkDistroCard in plugins/library/client.js; library-rtk-wsl.test.cjs). |
rtk_wsl.go |
Runtime path
- Edit. The Library page or
magpie librarycalls an exported function such asSaveServer,ServerAgents,InstallSkills,SkillAgentsorSetSkillHow. The skills and servers pages each have Select, Turn all on, Turn all off and Remove all. Select's bar callsSomeSkillsAgentsorSomeServersAgents(/api/library/{skills,servers}/agents-some), Turn all on or off callsEverySkillAgentsorEveryServerAgentsfor the agents shown, and Remove all callsRemoveSkillsorRemoveServers. The hooks page has Select and Remove all too (SomeHooksAgents,RemoveHooks). Each of these is one change that takes every item out as a single removal would (#1027). Select's bar also has Remove… (#1852), which asks first, naming the count, and sends only the picked names toRemoveSkills,RemoveServersorRemoveHooks; ticking a group's or part's header picks all of it. A name that wasn't removed stays picked, with its error in its row's place (pickErrs), and the status names it; when every name fails the endpoint answers 400 and the sheet stays open. A row's agent chips start with All (allChipinplugins/library/client.js), which gives the item to every agent shown that can take it, or takes it from them all; the pickers that choose the agents before an item is added (installing skills from a repository or the market, adding, bringing in or installing a server) have the same All: most start with every agent lit, and one agent alone took a click on each of the others (#1531). - Change.
changeeditslibrary.jsonunder the lock and callssync. - Write. For each target,
syncInstructions,syncMCP,syncHooksandsyncSubagentswrite magpie's part in the agent's format and record it inApplied. Skills are linked or copied into the agent's skills folder. A copy edited since it was made is taken into the library first. - Result. The
Resultlists the agents changed, aProblemfor each thing that couldn't be given, and the backup folder. Each change's folder is its own (freshBackup): named by the millisecond, with-2,-3… after it when another change took that millisecond, so a change's copy is never another's (TestBackupsInOneMillisecond).
Constraints and failure behavior
- magpie takes away only what
Appliedor its mark says it wrote. A folder of the user's with a skill's name is never touched. The user's own fields in an MCP entry are kept. - An edit never silently loses. When an agent's copy of a skill and the library both changed, the newest edit wins, and the losing one is kept with the backups.
- An update from GitHub or a git repository never silently replaces a skill changed here. It is refused, or skipped in an update of several, until the user says to replace it, and the version replaced goes to the backups.
- A copy's mark establishes that it is unchanged only after its whole folder was scanned. If a subtree or its metadata can't be read, the copy stays in place and the sync reports a
Problem; it isn't replaced, relinked or removed. A later sync tries again once it can be read. The same scan failure stops replacing a project's or Claude Desktop's copy. - A failure for one agent is a
Problemin the result. It doesn't stop the others. - An MCP OAuth sign-in canceled or timed out before its callback commits never saves a late token or changes an existing sign-in. The callback's write and the flow's ending share a lock (
flow.keepinmcpauth.go); if the write wins first, it completes and tells the agents before saying done. A cancellation is not a sign-out of credentials already committed. - A server an agent can't reach is not written there, and
mcpFile.supportssays why. For example, Claude Desktop takes no remote server, and Codex, Goose, dsh, Grok, Command Code and Zed take no SSE. - A server's headers (remote) or environment (command) can name a variable as
${NAME}(#1250).library.jsonkeeps the placeholder, andrefsOfgives each MCP format the agent's own syntax, with the agent's source cited beside it:${NAME}for most,{env:NAME}for OpenCode and MiMo,${env:NAME}for Cursor, and Codex's own keys (bearer_token_env_var,env_http_headers,env_vars). Goose gets${NAME}plusenv_keys. dsh (DeepSeek Harness) gets a!!jsexpression it evaluates as it loads the server (#1435): a whole${NAME}is!!js process.env.NAME, and a value mixing text and variables is the text as JSON string literals joined with(process.env.NAME ?? ""), so the user's text is never run as code and an unset variable inside it is empty. A whole variable that isn't set makes dsh leave the server out as invalid. magpie reads only those forms back as${NAME}; any other!!jskeeps the entry the user's. An agent with no syntax (Claude Desktop, Antigravity, Kimi, Cline, ZCode, Zed, Devin, Alma, Pi with pi-mcp-extension) is never written the value:refsProblemmakessupportsrefuse the server, a magpie entry already there is taken out, andAgentView.NoEnvRefsgreys its chip with the reason. Codex and Goose's extra keys are magpie's only while the server names a variable there (refKeys), so the user's ownenv_varsorenv_keysare kept.CheckServersexpands the variable from magpie's own environment, and one that isn't set isnovar, naming it. The page paints that as not checked (a ring,lib-health unknown), not red: it says nothing of the server, which the agent may start with the variable set, as Codex does its host-onlycodex_app(#2308). It starts a command server in home, withPWDset to it (not on Windows), as an agent started from home would, never in magpie's own working folder: a magpie started from the Windows Start menu hasC:\Windows\system32, where a server that writes into.exits before it answers (#1727,TestCheckStdio). - A command server is checked where the agents given it run (loong on Discord: a WSL program, given only to agents in WSL, was checked on Windows and "exited (1)").
checkSidesreads each agent id's@wsl:<distro>: with none, or off Windows, or a Windows path for the command (windowsPath, magpie's own image server among them), or Settings' Detect agents in WSL off, it is this computer as before. Otherwise each distro is a side, after this computer when an agent here has it too. In a distro the command is found as the agents' shell finds it (wslrun.In: a login shell, then an interactive one for nvm's node, the probewslrun.Finduses) and started throughwslrun.Tool.Command(wsl.exe -d D --exec /usr/bin/env PATH=… <path> args), its env passed byWSLENV. A distro that isn't running is never started for a check: it iswsldown, naming the distro, painted as not checked likenovar; beside a side that was checked it is left out.ServerHealth.Checkedlists where it started,""for this computer; the first failure ends the check and is the last place's, which the row names (" · WSL Ubuntu") and the tooltip says (TestCheckWSLOnlyServerInItsDistro,TestCheckWindowsServerHere,TestCheckMixedServerEachSide,library-mcp-health-wsl.test.cjs). Agents moved between sides is a check anew (healthKey, both sides). In a distro the command runs in the folder wsl.exe gives it (the Windows home under/mnt), not the Linux home. - A server's tools turned off on the page (nf1qaz2w on Discord) are kept by their names as the server gives them, in
Server.DisabledTools, and written only to the agents that read a setting for it (toolsOffOf), each in its own form, checked against its source:- Codex:
disabled_toolsin the server's table in config.toml (codex-rs/config/src/mcp_types.rs, applied byToolFilterincodex-rs/codex-mcp/src/tools.rs, openai/codex cc7ba336). - Gemini CLI:
excludeToolsin the server's entry (docs/tools/mcp-server.md;mcp-client.tsdrops a tool by its own name, google-gemini/gemini-cli 9b6e0265). - Crush:
disabled_toolsin the server's entry (MCPConfigininternal/config/config.go,filterTools, charmbracelet/crush df5b024a). - Hermes Agent:
tools.excludein the server's entry, the original names (tools/mcp_tool_registration.py,mcp-config-reference.md, NousResearch/hermes-agent c5733167).tools.include,promptsandresourcesbeside it are the user's. - Claude Code: a rule
mcp__<server>__<tool>inpermissions.denyof its settings.json (Target.Settings, beside.claude.json; for a WSL distro the distro's). A bare tool name in deny takes the tool out of Claude's context (code.claude.com/docs/en/permissions). Both names are spelt as Claude Code 2.1.296 spells them, each character but a letter, a digit,_and-an_. - OpenCode:
"<server>_<tool>": falsein the top-leveltoolsof opencode.json (opencode.ai/docs/mcp-servers, "Manage"), the names spelt asname()inpackages/core/src/tool/mcp.tsdoes;migrateToolsinpackages/core/src/config/normalize.tsmakes each a deny rule (sst/opencode 0d61729b). - Every other agent (Cursor, Copilot and Goose, whose lists are allow-lists only, Zed, Kimi, Pi, Grok, Devin, Antigravity, Alma, dsh, omp, ZCode, Command Code, Cline, WorkBuddy, CodeBuddy, Droid, Claude Desktop, MiMo Code, DevEco Code, a plugin's agent) gets the server whole.
AgentView.ToolsOffis false for it, and the open list of tools names those given the server as unable to turn off single tools. A project's file and Copy config… carry no tools turned off either. magpie records what it added (Applied.ToolsOffper server for a list in an entry,Applied.ToolRulesfor Claude Code's rules and OpenCode's keys) and takes back only that (offList): a name, rule or key the user had already is theirs and stays when the tool is turned on again, and an OpenCode key the user set totrueis never written over. A list orpermissions.denythat isn't a list of names is a problem, never taken as empty, and the file is left as it is. The key, and Claude Code'spermissionsor OpenCode'stools, goes when magpie's were the last in it. The editor's save sends no tools, soSaveServerkeeps those turned off.
- Codex:
- With the MCP hub on (
MCPHub), an agent that takes a Streamable HTTP server is given magpie's onemagpieentry in place of the Library servers ticked for it, and each server's own entry again when it is turned off. One that can't, or has an entry called magpie of its own, or whose library has a server called magpie, keeps each server's own entry, and the page says why (MCP hub). - magpie's own MCP server (
magpie-image, and anymcp …run by a program named magpie) runs this computer's magpie (#1439).InstallServergives it magpie by full path (update.Program: the AppImage, not its mount; Homebrew's opt link, not the Cellar), and that path is right only on this computer. When the library is read, and after every change,healpoints such a server whose program isn't on this computer (another system's path, a magpie moved out of Downloads, a baremagpie) at this magpie, so the agents andCheckServersget it; a magpie program that is here (another build) and a server run by any other program stay as they are. A carried library (Collect, for a backup or a WebDAV or S3 sync) names it as plainmagpie, so two computers carry the same bundle and a sync doesn't write one's path over the other's;Putthen reads it as that computer's magpie.self_here.go - A carried library (
Collect) has every file of each skill, its templates and other binaries included, up tomaxCarried(16 MiB) a file andmaxCarriedAll(32 MiB) in all, chosen smallest first across the skills (readSkills), so every skill's text goes before any big file. The total keeps a sealed backup under the 64 MiB a sync reads: the files are base64 twice in it. What is left out is named inLeft, andPutkeeps this computer's copy of such a file in the skill it puts (keepLeft).carry.go - A skill can be turned off on this computer alone (
OffHere,SkillHere; the row's power button,magpie library skill off-here <name>andon-here; hanslin1666 on Discord). No agent here gets it, whatever itsAgentssay (gives, which every reader ofAgentsfor giving goes through:syncSkills,desktop_skills.go,skill_changed.go,skill_edits.go,behind,Targets).Agentsstays what a sync carries, and the page leaves its chips as they are, faded.Collectnever carriesOffHere, so turning it off changes no part a sync uploads, andPutkeeps this computer'sOffHerefor a skill it puts, so a sync from a computer that has it on, or gives it to more agents, never turns it on here. A library.json from before has nooffHereand every skill stays on. Not covered: a project's skills; a library skill kept in~/.agents/skills, which agents read in place, until it is handed over (below); and a skill another computer removes, which takes the flag with it.skills.go,carry.go - An MCP server can be kept to this computer (
Server.Local; the editor's "This computer only" switch,magpie library mcp add --local,magpie library mcp local <name> on|off; huhuy72219405 on X).Collectnever carries it (carriedServers), so a sync or a backup file never takes it to another computer, and turning a shared server local takes it out of what is carried: the other computers drop it at their next sync.Put(sync, join, Restore, Undo, a backup file) keeps every local server here, with its agents, and clearsLocalon what comes in (putServers). Another computer's server by the name of a local one doesn't take its place: it goes toLibrary.Away, given to no agent, not in the hub, not checked, and carried on as it came, so a push from here never takes it from the computers that have it.settleAwayruns on every change: while the name is local here the away copy stays; once no server of that name is left here (removed or renamed) it comes in as a sync would bring it; once a shared server has the name (local turned off) this computer's is the one carried. The hub serves local servers like any other, since it runs on this computer. Subagents aren't carried, so one that names a local server keeps it here. The TUI keeps the flag on edit and marks the row. (TestLocalServerNotCarried,TestPutKeepsLocalServer,TestPutSameNameAsLocal,TestRestoreKeepsLocalServer,TestLocalServerThroughSync,mcp-local-server.test.cjs)mcp_local.go,carry.go - A skill kept in
~/.agents/skillsis handed over to the library on the user's click (HandOverSkills,POST /api/library/skills/hand-overwithnames; the row's Manage in magpie in its source line, Manage {n} in magpie in the skills' heading, each asking first;magpie library skill hand-over <name…>|--all; tnt1223 on Discord). "Kept there" issharedEntry: the entry in that folder that is the library skill's own folder, by its name or, for a library link into it under another folder's name, by that folder's (SkillView.Shared;SharedElsewherewhen the entry only links to a folder kept elsewhere). Every reader ofsharedHas/sharedEntryfollows:Always,syncSkills'inShared, and the shared folder's own target (Goose, Kimi Code, Cindy), which is given no second link beside such an entry (TestSharedUnderAnotherName). Handed over, a folder in~/.agents/skillsmoves into the library's skills folder (moveIn: renamed, or copied, read back the same withsameTreeand only then set aside with the backups; a failure leaves it where it was and the library's link as it was,TestHandOverFailureKeepsOriginal), and an entry that only links elsewhere is taken away while the library links past it to that folder. The user's own links to it in agents' folders, which would point at nothing, go too. Every agent here that read it (readsSharedHere, and the agent of each such link) is ticked, so each keeps it, now from the library, till it is unticked or turned off here. A skill found there and not in the library yet is brought in first. One that can't be handed over is left as it was, inResult.Unmoved, and the others are handed over all the same.HandBackSkill(magpie library skill hand-back <name>, CLI only; the sheet names it) moves the folder back and links the library to it, its ticks as they are. Not covered: another computer whose skill is still in its own~/.agents/skillsgets the library's copy from a sync beside its own, until it is handed over there too; and the skills CLI's lock (npx skills update) may put the entry back (TestHandOverSharedFolder,TestHandOverSharedLink,TestHandOverFound,TestHandOverWithGoose,TestLibrarySkillHandOver,skill-handover.test.cjs).skill_handover.go - WorkBuddy's servers go in
$WORKBUDDY_CONFIG_DIR/mcp.json(default~/.workbuddy; WorkBuddy AI, the international build, keeps its own in~/.workbuddy-ai, #1494), and CodeBuddy Code's go in the first of.mcp.json,mcp.jsonand~/.codebuddy.jsonthat exists, asresolveMcpFilePathreads them (#1266). WorkBuddy connects a server only after the user has switched it on once in its own MCP settings. It keeps that approval inmcp-approvals.json, keyed by the command, args and env names or the URL's origin, so changing those asks again. magpie never writes the approval, and the servers page says so, by the build's name, when a server is given to WorkBuddy or WorkBuddy AI. - Alma's servers go in
~/.config/alma/mcp.jsonon every system (its home, not its data folder), as its own MCP settings write them:command/args/env, orurl/headerswithtransport: "sse"only for SSE (#1292). Alma reads the file as it starts and when its MCP settings refresh, so a server given to it while it runs reaches it after one of those. - Grok App's independent home (Use on a custom provider,
GROK_HOMEatagent-homeunder its data folder) gets instructions inAGENTS.md, MCP servers in[mcp_servers]of the sameconfig.tomlmagpie's channel is in, skills inskills/, and hooks as[[hooks.<Event>]]tables in that config, and it also reads~/.agents/skills. Shared mode stays on Grok Build's~/.grokrow. RTK lists Grok App, and Grok Build, with the switch off:rtk inithas no Grok agent. - Zed's servers go in
context_serversof the settings.json magpie sets its model in (agent.zed:~/.config/zedon macOS,$XDG_CONFIG_HOME/zedon Linux,%APPDATA%\Zedon Windows, or$MAGPIE_ZED_CONFIG_DIR), ascommand/args/envorurl/headers(ContextServerSettingsContent, zed-industries/zed 2c99f547). The file is JSONC: it is edited in place, so the user's comments, other settings and own servers stay, andenabled,remote,timeoutandoauthin magpie's entry are the user's. Zed speaks streamable HTTP only (itshttp.rsonly POSTs), so no SSE. An entry Zed's extensions configure (settingsand no command or url) is never written over: a server by that name is refused for Zed (mcpFile.foreign), and asks for another name. Zed reloads the file as it changes. - An agent with no place for an item is refused by
Takes, never recorded as given it. The refusal lists the agents here that take that item (takenBy), and says where it goes instead (noPlace): OpenChamber reads OpenCode's global AGENTS.md, skills folder and opencode.json (its server'sshared.js), so it gets them from OpenCode; Claude Desktop's chat keeps its instructions in its own settings, with the Claude account, and its Code tab reads Claude Code's. A plugin's agent is refused an item itsagent.librarynames no place for, and the refusal names the key its plugin would set. - Removing RTK never uses
rtk init --uninstall. That command deletes Gemini'sGEMINI.mdwhole and removes Claude Code, OpenCode and Cursor together. - A hook is recorded entry by entry, as written (
Applied.Hooks, compared as canonical JSON). magpie takes out only an entry still exactly as it wrote it; one the user edited is theirs from then on, and the user's own hooks beside it stay. A hooks file that doesn't parse is a problem and is never written. Codex keeps each hook's trust in config.toml as[hooks.state."<path>:<event>:<group>:<handler>"], keyed by position, so when magpie takes a group outcodexRekeymoves the user's trust for the groups after it to their new place. - A carried library (backup, WebDAV, S3, profile bundles) doesn't carry hooks yet.
- A subagent file is recorded by the hash of what magpie wrote (
Applied.Subagents). magpie writes over or takes away only a file still exactly as it wrote it; one the user edited is theirs from then on, and the page says so. A file of the user's own by the same name is never written over: the agent gets a problem instead. A file of magpie's the user deleted is written again on the next sync. Cursor's~/.cursor/agentsis read by the Cursor app only; the cursor-agent CLI reads only a project's.cursor/agents. An agent in a WSL distro gets no subagents, nor do agents with no user-level subagent folder (Kimi, Goose, Crush, Qoder, CodeBuddy, iFlow, Kiro). A carried library doesn't carry subagents yet. - CC Switch's own skills folder is only ever read.
- Reading the page never waits on reading skills through (#541).
Readcompares an agent's own skill with the same name in another agent (sameTree) and hashes each library skill given as a copy (hashFiles, forbehind). Both are kept against a stamp of the folders (each file's and link's path, type, size and mtime,stamperintreememo.go), taken by the same walk that compares or hashes them, before a file is opened; a later read walks the folder without opening a file, and while the stamps match reuses the answer. Only an answer from a whole read of folders untouched forsettleFor(3s) is kept: a folder that couldn't be walked or read, or was written a moment ago, is read again next time, never taken as unchanged. A rewrite that keeps a file's size and mtime isn't seen.Glance(GET /api/library?glance=1) is the page without those two, markedpartial; the page draws it first, then the whole read, which runsbehindandfoundSkillsafter the library's lock is let go, so a change doesn't wait on them either. - A read of the page (
Read,Glance) follows the links on the way to a few hundred paths, most of them many times over: each agent's skills folder for each skill, CC Switch's and the shared folder for each source. While the read holds the lock,resolvelooks at each entry on the way once (lookPartinlinkmemo.go): oneLstat, and aReadlinkfor a link. Nothing is kept past the read, so a link made or moved on disk between two visits shows on the second. An entry that couldn't be looked at for another reason than its not being there is unknown and looked at again. One read had taken ~10,000 looks; on oxyuan's Windows machine that was ~1.3s a visit (#1771). - Skills installed together (
InstallSkills,InstallMarketSkill,AddNewSkills, throughinstallFromandinstallChange) install each on its own. One the library lists from the same source, or a folder in the library's own skills folder holding exactly that skill's files (left by an install that stopped before the library was saved), is had already and goes inResult.Had. Its files are never written, so the user's edits stay. Another skill by that name, listed or only in the folder, or a folder that can't be read, is left as it is and goes inResult.Skippedwith why. The rest are installed and named inResult.Installed. Only when nothing was installed or had does the change fail, with the first reason.
Verification
go test -tags nogui ./internal/library -run 'TestGit|TestInstallFromGitRepo|TestReadLooksAtEachFolderOnce|TestLinkChangedBetweenVisitsShows|TestUnreadablePartIsLookedAtAgain|TestCheckSkillsFindsNewOnes|TestNewBase|TestUpdateKeeps|TestCheckDue|TestCheckSkillsMarksItDone|TestTargets|TestWSLPiMCP|TestWSLMCPSiblings|TestServer|TestHub|TestImportServer|TestCheck|TestInstructions|TestInstructionsSetLinkedToAgentsFile|TestInstructionSets|TestTakesAlma|TestAlma|TestLinkedSet|TestLinkRefused|TestSkill|TestRemoveFoundSkill|TestInstallSet|TestInstallLists|TestEverySkillAgents|TestEveryServerAgents|TestSomeServersAgents|TestRemoveServers|TestRTK|TestEnvRefs|TestDshRefRoundTrip|TestDshImportKeepsJS|TestAgentMCPFiles|TestCodeBuddyMCPFile|TestZedMCP|TestOwnServerFromElsewhereRunsThisMagpie|TestUsersOwnServerStaysAsItIs|TestCarriedOwnServerIsEachComputersMagpie|TestCarry|TestPageReadDoesntReadUnchangedSkillsAgain|TestJustWrittenSkillIsReadAgain|TestUnreadableSkillIsntRememberedAsDifferent|TestGlanceLeavesOutTheAgentsSkills|TestPluginAgent|TestPluginMCPFormatsAreWritten|TestToolsOff|TestOffList|TestHooks|TestSubagent|TestCheckRenewsMagpiesSignIn|TestCheckWSLOnlyServerInItsDistro|TestCheckWindowsServerHere|TestCheckMixedServerEachSide|TestCheckSaysSignInRanOut|TestCheckNamesAgentsSignedInThemselves|TestSignInAsTheUsersOwnApp|TestOAuthAppChecked|TestOAuthAppSecretCarried|TestGoneAgentListedToTakeOut|TestUpdateFindsSkillsRemovedUpstream|TestGoneFromNeedsTheSourceRead'
go test -tags nogui ./internal/library -run 'TestSkillOffHere|TestLocalServerNotCarried|TestPutKeepsLocalServer|TestPutSameNameAsLocal'
go test -tags nogui ./internal/backup -run 'TestRestoreKeepsLocalServer'
go test -tags nogui ./internal/library -run 'TestHandOver|TestSharedUnderAnotherName|TestSharedAgentsSkills'
go test -tags nogui ./internal/davsync -run 'TestSkillOffHereThroughSync|TestLocalServerThroughSync'
go test -tags nogui ./internal/cli -run 'TestLibrarySkillRm|TestLibrarySkillHandOver'
go test -race ./internal/mcpauth
go test -tags nogui ./internal/library
go test -tags nogui ./internal/library -run 'TestWSLStopped'
go test -tags nogui ./internal/library -run 'TestRTKWSL'
node --test internal/gui/tests/library-rtk-wsl.test.cjs
node --test internal/gui/tests/library-wsl-asleep.test.cjs
node --test internal/gui/tests/skill-off-here.test.cjs internal/gui/tests/mcp-local-server.test.cjs internal/gui/tests/skill-handover.test.cjs
node --test internal/gui/tests/library-items.test.cjs internal/gui/tests/library-mcp-hub.test.cjs internal/gui/tests/library-alma-profile.test.cjs internal/gui/tests/library-rtk-gain.test.cjs internal/gui/tests/library-rtk-nohook.test.cjs internal/gui/tests/library-servers-bulk.test.cjs internal/gui/tests/library-pick-remove.test.cjs internal/gui/tests/library-env-refs.test.cjs internal/gui/tests/library-zed-mcp.test.cjs internal/gui/tests/library-workbuddy-trust.test.cjs internal/gui/tests/skill-new-in-repo.test.cjs internal/gui/tests/skill-update-edited.test.cjs internal/gui/tests/skill-gone.test.cjs internal/gui/tests/skill-git-source.test.cjs internal/gui/tests/remove-found-skill.test.cjs internal/gui/tests/found-skill-pick-remove.test.cjs internal/gui/tests/library-loading.test.cjs internal/gui/tests/library-mcp-tools.test.cjs internal/gui/tests/library-mcp-tool-switch.test.cjs internal/gui/tests/library-hooks.test.cjs internal/gui/tests/library-subagents.test.cjs internal/gui/tests/library-mcp-health.test.cjs internal/gui/tests/library-mcp-health-wsl.test.cjs internal/gui/tests/mcp-signin-health.test.cjs internal/gui/tests/mcp-signin.test.cjs internal/gui/tests/mcp-editor-cancel.test.cjs internal/gui/tests/mcp-oauth-app.test.cjs internal/gui/tests/library-ime-scroll.test.cjs
The package's TestMain runs in a home of its own (testenv), never the
user's real agent files.