Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.
Claude subscription bridge: turns across Claude Code runs
A Claude subscription's requests are answered by the local claude binary
(internal/gateway/claude_subscription.go, serveClaudeSubscription). This
page covers how a conversation's turns find the Claude Code process, or the
saved session, that had its last turn, and what a run leaves on disk. Tool
calls within a turn (match, continueWith) are only touched on where they
meet it.
Which Claude Code runs
claudeBinary (and the sign-in's claudeExecutable) take
claudecode.Find: the machine's own claude (proc.FindTool), else the
one magpie claude-code install downloaded into
<cache>/claude-code/<version>/ (internal/claudecode), else, on Windows,
one in WSL. The download is Anthropic's native build from
downloads.claude.ai/claude-code-releases, the "latest" channel, as
claude.ai/install.sh takes it: the release's manifest.json gives the
platform's SHA-256 and size, and a build that doesn't match both is not
kept. It is only made when the user asks (magpie claude-code install, or
yes to magpie accounts add claude's offer on a machine without one), for
a server or a container (Jorben on Discord). It is not on PATH and stands
in for no agent. It doesn't update itself (the bridge sets
DISABLE_AUTOUPDATER); installing again takes the newest and removes the
older one.
A run is started with --dangerously-skip-permissions (claudeCLIArgs):
its only tools are magpie's MCP ones, answered by the client, and
Anthropic's web search. Claude Code run as root refuses that flag ("cannot
be used with root/sudo privileges") unless IS_SANDBOX is 1 or
CLAUDE_CODE_BUBBLEWRAP is set, so a run as root, magpie's own euid 0 or
a WSL distro whose default user is root (the probe's uid,
wslrun.Tool.Root), is given IS_SANDBOX=1 (claudeCLI.asRoot;
FrierenF on Discord). A run as anyone else has its env as before. Only the
bridge's run gets it; the warm-up and /usage runs don't skip
permissions.
Every Claude Code magpie starts for the subscription (a turn's run, the
warm-up and model test askClaude, /usage, and the sign-in's
auth login and auth status) is given its proxy through one helper,
claudeCLI.proxied in each package, which is
netproxy.EnvForBunWith: the account's own proxy, else the
subscription's, else the global one (netproxy.EnvWith), with a SOCKS5
proxy replaced by magpie's loopback HTTP bridge to it (netproxy.Bridge,
as for every bun magpie starts, #1409). Claude Code is built with Bun,
which takes only http:// and https:// proxies: given socks5://, every
request failed as UnsupportedProxyProtocol, after about three minutes of
Claude Code's own retries, as a 502 (#2651). A Claude Code in a WSL
distro that doesn't share Windows' loopback (wslrun.Tool.Host set)
can't reach the bridge, so there, and where the bridge can't start, a
SOCKS proxy is refused before Claude Code starts, with an error that says
to use an http:// proxy. The settings.json env that magpie writes for the
user's own Claude Code sessions leaves a SOCKS proxy out (see
Providers and accounts).
The helper offers each of the client's tools under bridgeToolName
(bridgeTools), which Claude Code calls mcp__magpie__<name>. Claude Code
keeps only [A-Za-z0-9_-] of an MCP tool's name, so a name it would change
(spawn.agent, fs/read), one longer than 51 (64 with the prefix) or one
ending as a changed name ends (_ and 12 hex digits) is cut, made of those
characters and given a hash of the whole name: unique (a.b and a_b
stay apart), the same in every run, so a resumed session, the history
(renderParts) and the tool-choice line (toolChoiceAsk) name it as the
run was offered it. subscriptionRun.names (bridgeNames) maps it back
to the declared name in toolStart, for streamed and whole messages, and
in mcpCall (#2649).
The run's MCP server is magpie itself (magpie claude-mcp-helper,
internal/claudebridge), which hands each tool call back to the gateway
at POST /_magpie/claude-mcp/<token> (mcpCall), where the call is
registered in b.calls for the turn with its results to find. The token
is randomToken (24 bytes from crypto/rand), one per run. The callback
URL is written to callback in the run's own temp folder (0600) and the
helper is given that file's path, so the token is never on Claude Code's
command line. The helper calls the address the gateway listens on
(callbackBaseURL: MAGPIE_ADDR, 0.0.0.0/:: as 127.0.0.1), which,
pinned to one interface's address, isn't loopback, and it sends no
gateway key. lanGuard therefore lets in exactly that path, by POST, with
the token of a run now live (ownCallback: addCallback when the run is
registered, dropCallback in removeRun, compared in constant time).
Every other request, and this path with a wrong, spent or encoded token,
is judged as any other. Without it the call was refused 401, never
reached the run, and every turn with tool results found no run waiting and
started a new Claude Code told the whole conversation (#1546).
Why turns go on in one run
A run started anew is told the whole conversation in one user message
(renderClaudePrompt), a prefix the prompt cache has never seen, so the
conversation is written to the cache again and its images are sent again.
By default, that message holds the history in blocks of historyChunk
messages, and magpie's one mark (Claude Code keeps three of Anthropic's four) is on the
last whole block, else on the caller's instructions: a later run started
anew for the same conversation within the hour reads the history up to an
earlier run's mark, found within Anthropic's 20-block lookback. A
conversation with no history (no reply that calls no tool, as a sub-agent's
loop of tool calls that Claude Code's AgentSummary asks a summary of) has
its every message but the last chunked instead. The turn to answer after a
history is not chunked, and image blocks count toward the lookback.
A turn that goes on in the run that had the last one is told only the
messages since (renderClaudeTurn), and Anthropic reads the rest from the
cache.
Client-placed cache marks (#1717)
A client can send X-Magpie-Cache-Marks: client on a /v1/messages
request to a Claude subscription. Without that header, the bridge behaves
as before. Chat Completions and Responses ignore the header. The mode is
part of the run's identity, including rewritten conversations and tool-result
handoffs: opted-in and ordinary requests never share a run.
An opted-in run sets DISABLE_PROMPT_CACHING=1. Its four cache slots belong
to the client. claude_cache.go validates the marks before run selection;
renderClaudePrompt places them in a new run's first user message.
| Client mark | Bridge behavior |
|---|---|
cache_control without ttl |
Uses 5m. |
| System block | Ends its own instruction block with the same TTL. |
Top-level cache_control |
Sets the request-level tail through CLAUDE_CODE_EXTRA_BODY. |
| Last message block | Sets the same request-level tail. |
| Earlier message block, new run | Ends a block at that point in the rendered history with the same TTL. |
| Earlier message block, running or saved run | Dropped and reported; the existing history cannot be edited. |
| Tool definition | Dropped and reported; Claude Code owns the tools. |
| Bridge history-chunk mark | Uses only a free slot and never a longer TTL than a preceding mark. |
setSafeguards updates the tail before each turn or tool-result handoff
that changes its TTL, and clears it when a request no longer asks for it.
An explicit last-block mark and a top-level mark both count toward the
request limit. The bridge represents their shared boundary with one tail
when their TTLs match. Different TTLs at that boundary are rejected. Marks retained
in the first user message survive shelving. A new tail that cannot fit
the retained slots or TTL order starts a new session with the rendered
history.
More than four marks, or a 1h mark after a 5m mark in tools → system →
messages order, returns HTTP 400 with Anthropic's type: error and
invalid_request_error shape. The count includes top-level
cache_control. Both error messages and the omitted-TTL default were
checked through a relay to the live Anthropic API.
X-Magpie-Cache-Marks-Dropped lists counts by section, such as
tools:1,messages:3. It is absent when nothing was dropped. A mark on a
system block removed with the billing header is reported as system.
The bridge also reports marks on content it cannot render. Cache usage
retains Anthropic's cache_creation.ephemeral_5m_input_tokens and
ephemeral_1h_input_tokens values.
The dropped-mark header and its keepalive hold belong only to a Claude subscription try. An API-key member keeps the client's marks and clears any report or hold left by an earlier subscription try. Validation still applies before routing among the members.
The dropped-mark header is best-effort on streaming responses. Validation and tool-drop counts are known before headers are sent. An opted-in Claude subscription try waits at most two seconds for run selection to decide the other drops. Selection releases that hold before process startup or upstream output. If selection takes longer, the gateway logs the missing report and sends keepalives without the dropped-mark header. Later fallback can also change the selected run after headers have been sent. Reporting never fails the request or delays an ordinary request's keepalives.
The caller's instructions as the system prompt (claudeLeanPrompt)
Every run is the real Claude Code. By default it keeps Claude Code's own
system prompt, and the caller's instructions go in the run's first user
message inside <external_system_instructions>. Settings › Models ›
Replies › Short Claude system prompt (claudeLeanPrompt, off by default)
starts a run with --system-prompt-file instead. The file is system.md
in the run's temp folder, under the distro's mount in WSL (claudeCLI.file).
It holds leanSystem: the caller's instructions without a client Claude
Code's billing line, plus the tool-choice line. The first message then holds
the conversation alone. Claude Code still sends its billing block and its
identity line, so requests come from the real binary. They no longer carry
Claude Code's prompt, and that is the ban risk the setting names.
A request with client cache marks (#1717) is never lean: its system marks
are placed in the first message. The mode is part of the run's identity
(cacheIdentity, and the tool-results check in serveSubscription), so a
run started in one mode never takes a turn of the other. After the setting
changes, the next turn starts a run with the rendered history.
Measured on 2026-10-16 with a real Claude subscription on Sonnet 5.5, Claude Code 2.1.301:
| Client | Off | On |
|---|---|---|
| Chat client, ~600-token prompt, 2 tools, 3 turns | 10,048 input tokens | 6,580 (−35%) |
claude -p as the client, Read and Bash, 4 requests |
85,453 / 85,471 | 81,948 / 81,977 (−4%) |
The saving is a fixed ~0.9–1.2K tokens a request. It is large for light
clients and small for clients with Claude Code-sized prompts. Without any
tool, Claude Code's built-in tools are already off (--tools ""). A run
told the whole conversation again costs far more, because it writes the
history to the 1h cache at 2×.
Runtime path for a new turn
serveClaudeSubscription's start tries, in order:
subscriptionBridge.resume: an idle run waiting at the conversation the request goes on from (b.idle). It is written the turn's messages on its stdin, as a user message with a uuid it is rewound to if the client gives up on the turn (letGo).subscriptionBridge.unshelve: the saved session of a run let go pastidleMost(b.shelf, at mostshelfMost), which a new Claude Code starts from with--resume, told the turn's messages alone. It is sentinitializefirst, which Claude Code answers only once it has loaded the session; one that can't load it exits 1 ("No conversation found with session ID") without answering.startthen lets the session go and goes on to step 3 in the same request, logged "Claude Code could not go on from the conversation's saved session". Before, the turn got 502 "Claude Code ended" with the safety context set, and an empty reply without it.retire, then a new run told the whole conversation. When it has replies in it, the turns already answered are wrapped in<conversation_history>, with a note that the images and files in them were sent with those messages, and the turn to answer (from the message after the last reply that calls no tool,historyEnd) in<current_turn>(#1365). Told as one stretch of Human:/Assistant: text, earlier images read as just sent. A first turn, or messages with no reply among them, are told as before.startlogs "a new Claude Code is told the whole conversation" with the message and image counts. Claude Code notes every image of the message after it, so after the turn to answer:[Image: source: …/images/N.png]where it keeps the images (the session kept on disk), or the size it showed a large one at. When the history has images, the turn's opening says those notes are the history's, or the history's first and then the turn's (currentTurnOpen, #1751). Told nothing, the model said a text-only turn had an image attached and offered to open the path.
A Claude Code that ends before it answers a control request
(cliControl: initialize, the safety context) is reported with its
exit status and the end of its stderr (endedBefore), as one that ends
before it reads its input is (whyEnded). The tool-results path and
resume already start a new run when the one they found has ended.
magpie ends a run (abort) by asking Claude Code to end with SIGTERM
(proc.Tree.Stop) and kills its tree only once it has exited or
stopGrace (5s) has passed; Windows kills the job at once. Claude Code
removes ~/.claude/.oauth_refresh.lock as it exits on SIGTERM (2.1.299
exits within half a second), and the SIGKILL magpie sent before left the
lock for the next requests to fail on (#2195). The run counts as ended at
once; the gateway stopping (abortAll) waits for every tree. Covered by
TestClaudeAbortAllowsLockCleanup and TestTreeStop*.
A side question after a reply (#1638)
After each turn Claude Code 2.1.290 asks its prompt suggestion: the
conversation so far, with the turn's system prompt, tools and thinking so
it shares the cache, and one more user message, "[SUGGESTION MODE: …",
with no system message after it. Its request goes on from the turn's
reply like a next turn, so resume gives it the conversation's run, and
the run waited at the suggestion's reply. The user's real next turn then
found no run and was told the whole conversation in a new Claude Code
(the reporter's 41 messages, 88k tokens written to the cache, minutes
after the last reply, with nothing in the log).
ended now keeps, beside the run's new key, the key it went on from
(behindKey) and the uuid of the turn that took it there (behindTurn).
A turn that finds no run under its own key takes one whose behindKey is
its key, rewinds it to behindTurn (as letGo does) and tells it only
the turn's messages ("taken back from the side question it answered
since"). The run is marked rewound, so it isn't shelved. A run that
can't be rewound is let go and the turn told whole to a new run, as
before. Tried with the real 2.1.290 client in -p --prompt-suggestions
and the real 2.1.290 as the run, against a local mock of Anthropic: one
run for the whole session, and the turn after each suggestion went on
from the reply before it. Other side requests that go on from the
conversation (extract_memories, away_summary, /btw) take the same path;
they weren't tried.
A turn after a reply that starts a new run logs why none waited
(whyNoRun, "claude: no run waits for this turn: …"): its run went on
with a turn this one doesn't follow, waits under another key (the model,
settings, system prompt or tools differ), waits at an earlier turn, is
busy with another request, ended (how long ago, and why: endWhy, set by
abortFor, kept in b.lost by conversation), or no run here has had the
conversation. Tool results that find no run waiting add what became of
the run that made the calls ("the run that made the calls ended …",
whyCallsLost, from b.lostCalls, which removeRun fills with the calls
the run waited on and the results it was last handed).
A turn the client gives up on (letGo, #780, #1365)
When the client goes away mid-reply, a run resumed for the turn is told to
rewind (rewind_conversation) to the turn's user message, and waits at the
conversation before the turn (backKey). The turn's id lasts until its
reply ends without calling a tool: ended keeps turnUUID and backKey
over a reply that calls tools, so a client that goes away while the run
answers its tool results also has the whole turn taken back, its tool
rounds with it. Its next request (the same results sent again, or the next
turn) then finds no run waiting on the calls ("tool results no run
waiting"), is resumed in that run at backKey and told the turn since its
user message (logged "a turn taken back goes on in its run"). Before, the
turn's id was dropped with the reply that called the tool, the run was
ended, and that request was told the whole conversation in a new run.
Claude Code 2.1.295 rewinds past a tool round mid-reply (tried against a
local mock of Anthropic). A run started anew for the turn has nothing to
rewind to and is still ended; so is one with a call still in the client's
hands (pending). Rewinding it to its first message would leave nothing,
and its results were already handed over its MCP calls, so the results
sent again go to a new run told the whole conversation (#1638's first
case: a 499, then "tool results no run waiting" and 17 messages told).
Keeping its cache would mean taking it back to Claude Code's own
tool_result message and telling the results again as text, which wasn't
done: the reporter's requests aren't known, and a fork that took the
lead's calls (claimResume) looks the same from here. The log now says
which run ended and why.
One key per waiting run
A run waits under one key (keepIdle, the only writer of b.idle);
kept again, a run leaves the key it waited at, unless another run now
waits there. Which order of calls kept one run twice in the reporter's
gateway isn't known: ended and letGo of one request exclude each
other (serveSubscription's ended callback runs only when gone()
stopped the AfterFunc that calls letGo), so it isn't those two of one
request. keepIdle holds the rule whichever caller it was (#1596). Past idleMost, the
eviction loop takes out the key it found as oldest, not the run's own.
Before (X, Sma1lboy: magpie at 158 GB after two days of omp agents), one
run under two keys was the oldest on every pass, the pass took out only
its newer key, and the loop never ended: it held b.mu, stopping every
Claude subscription request, and grew its list of runs to let go without
bound. claude_idle_test.go (TestClaudeIdleEvictionEnds runs the loop
in a child process, which on the old code fails on what the loop
allocates, not on a deadline).
keepIdle refuses a run that has ended, and its callers then leave the
run's timer alone (#1667). A resumed turn's 30-minute timer can end a run
(abort → finish → removeRun) while its reply is going out, and the
reply's last event, already in the segment, still reaches the client
whole, so ended is told it went well. Before, the ended run was kept,
held one of idleMost places until pushed out, and its re-armed timer
found it closed and never took it out. finish sets closed before
removeRun takes b.mu, and keepIdle reads it under b.mu, so a run
is either refused or kept and then taken out by removeRun.
TestClaudeRunEndedMidReplyIsNotKeptIdle fires the timer before ended.
Finding the run: keys
nextTurnsplits a request at its last reply that calls no tool: the conversation up to it, and the messages since (with any calls and results the client made itself after it).endedkeeps a run whose reply was whole underturnKey(owner, req, messages + reply): the account, model, whether an effort was asked, thinking off, tool choice, system prompt, the tools, web search, schema, and the messages ashashMessagesreads them. The system prompt is taken without the client Claude Code'sx-anthropic-billing-headerline (withoutBillingHeader), which the run is never told and whose fields (cch,cc_prompt_id,cc_prev_req…) change every turn; with it in, no next turn found its run (#1638). The exact match is that key, fromnextTurn's split of the next request.- It also keeps a
looseTurn: the same settings without the tools, the message count, the conversation before the last turn (hashed; its system prompt also without the billing line), and the last turn's messages one by one (messageWords), the reply last. Shelving copies it, with the tool names the run's agent had, to thesavedSession.
Claude Code's own sign-in before it has a name
The owner in every key is the provider, the account's name and, for Claude
Code's own sign-in, own (ownHome). claude auth status gives no email
until Claude Code puts the account's profile (oauthAccount) in its
config, which its first run does. Until then the account is named from its
plan ("Claude Max", Account.Unnamed), and its owner ends in unnamed
(unnamedOwner).
The first run on such an account then names it, mid-turn. Its tool
results came under the email, the owner no longer matched, and the run
was let go ("tool results account changed"). A new run was told the whole
conversation again, about 8k more cache writes. Now a run whose owner is
unnamed takes the named owner of the same provider's own sign-in
(takeNamedOwner), and goes on: a run in Claude Code's own home runs as
whatever that home is signed in to. A turn that ends without a tool call
takes the name before its keys are made (nameOwner, from
provider.ClaudeOwnName), so the next turn finds the idle run. Every
other change of owner still lets the run go. The owner is an atomic
pointer (owned), read by the run's reader without a lock.
A conversation the client rewrote (#912)
Some clients send a turn's conversation back changed. Alma takes the
[Context: …] block it gave the latest user message out once the turn is
over, and its <alma_notification> block out of the end of the reply, and
picks the tools for each turn. When the exact key misses, rewritten
compares the request's looseTurn with every idle run's and saved
session's. The request matches one when all of these hold:
- the same owner, settings and conversation before the last turn
(
looseTurn.key); - the last turn has the same messages, roles, tool calls and results, and
only these changed (
looseTurn.rewrote):- a user message had one part taken out (
cutFrom), not all of it; - the reply is a non-empty start of what the run said.
- a user message had one part taken out (
It is taken only when exactly one run or saved session matches. Two that could be it are two conversations alike as far as their words go, and a run handed the other one would answer from what that one was told.
An idle run is taken only when its agent was told every tool offered now
(offers). Claude Code is not told of new tools at a turn's start, only
with tool results. A saved session is taken only when the tools offered now
include every one its agent had (toolsCover). It is resumed with the new
list, and its earlier calls name no tool that is gone.
The run goes on with the conversation as it told it. Its Claude Code still holds the context block and the notification. The client's next turn brings its own context.
Images the client took out (#1382)
Hana replaces each image before the last reply with a line of text
([图片已省略:…]) in the tool result or user message that held it. Over
Chat Completions, pi-ai sent a tool's images in a user message after the
results ("Attached image(s) from tool result:" and the images); that
message is gone, and each result's text has the line added to its end. So
the step after one that read an image missed the run both ways: its tool
results failed follows, and its next turn failed turnKey and
looseTurn.rewrote (the message count changed).
lostMedia (claude_lost_media.go) tells this rewrite by its shape, not
by Hana's words. It compares the conversation the run had (kept as each
part's hash, heardRuns) with the request's, a role's messages in a row
at a time, and takes it when images or files were taken out and nothing
else changed:
- each image or file is still there, gone, or has text in its place;
- a tool result has text added to its end only when it carried images, or the images after the results went;
- the text before those images goes with them only when a result before it had text added;
- at least one image or file was taken out.
follows checks it when the hash misses (toldRuns, logged "tool results
go on in their run, the images before them taken out by the client"), and
looseTurn.rewrote when cut doesn't match; the looseTurn key no longer
has the message count, which cut compares itself. The run's Claude Code
still holds the images; it is told only what came since.
A client that drops the images' message without adding text to a result goes on only when that message held images alone, no text. A tool result of an image alone (pi-ai's "(see attached image)") whose text is replaced by the line is not this shape, and starts anew.
How many Claude Code processes run (claudeRoom, #2956)
Every Claude Code magpie starts for a Claude subscription takes a place in
claudeRoom (claude_room.go) before it starts, and frees it once its
process has exited: each conversation's run (startRun), busy, idle or
parked on tool results, and each one-off test, warm-up and /usage read
(runClaudeTree). Nothing bounded them before. Claude Code 2.1.303 holds
about 205 MiB RSS idle on Linux arm64, 86–112 MiB of it its own, and a
512 MiB systemd service had 2 busy runs and 14 starting at once when the
kernel's OOM killer ended them. In Docker under a 512 MiB memory cgroup,
six idle runs were enough for two OOM kills.
How many may run (claudeRunsMost):
- the user's
claudeRunsMostin settings.json, set withmagpie claude-code runs N(autoclears it). It is this machine's own setting (KeepOwn): a sync never brings a desktop's number to a server. - otherwise, on Linux,
(limit − 256 MiB) / 128 MiB, at least 1, where the limit is the least of MemTotal, the cgroup v2memory.maxandmemory.highof magpie's cgroup and every one above it, and the cgroup v1memory.limit_in_bytes(memLimit). 512 MiB gives 2, 1 GiB 6, a 964 MiB machine with no cgroup limit 5. It is read once per process. - otherwise no bound: macOS, Windows, and a Linux whose limits can't be read. A limit not known is not a small one.
An ask that finds no room (take):
- lets go of the run idle longest, of any bridge. Its session is shelved,
as a run pushed past
idleMostis, so its conversation's next turn resumes it (--resume) and is told only the new messages. - otherwise lets go of the run parked longest on tool results, once it has
waited
parkLongest. Busy runs, and runs waiting on tool calls made recently, are never let go. - otherwise waits for one to end: woken when a process exits or a run
goes idle (
nudge), and it looks again everyroomLook(5s) for a parked run that has come to waitparkLongest.
A run being ended counts as leaving, so several waiting asks don't each
let one go for the same room. After claudeRoomWait (2 minutes), or once
the request's context ends, the ask gives up. A conversation's turn is
answered 503 with "N Claude Code processes are running, as many as may run
at once (why); none ended within …" and how to set the number. start
doesn't retry without the saved session after such an error. A /usage read
returns it as its error.
Routing treats that 503 (claudeNoRoom) as a protected failure. No
account is rested, no other Claude account is asked next (each would wait
for the same room), and the request isn't tried again after a moment. A
member of the group at another provider answers it. Alone, the client gets
the 503.
Which ones run (ClaudeRunsPath)
Each run is two processes: Claude Code, and the MCP helper it starts for
the caller's tools (magpie claude-mcp-helper, internal/claudebridge).
Claude Code's parallel subagents are conversations of their own, so a
session that starts eight has eight pairs running while they work and
idleMost (6) pairs kept for an hour after. Those still waiting on tool
calls stay for runTimeout (30 minutes) once their caller stops. A task
manager names Claude Code by its version (its binary is
versions/2.1.311), so on macOS Activity Monitor shows these as "2.1.311" and
"magpie", with nothing to say what they are (@Candydidi3 on X).
GET /v1/magpie/claude-runs (claude_runs.go, loopback only, as the
heap profile) lists each run with its pid, model, account, state
(answering, idle for its next turn, tools waiting on the caller's
tools) and since. It also gives ends, when its timer lets it go
(endIn records it at each reset), and Claude Code's RSS. live is
claudeRoom's count, one-off asks included. magpie claude-code runs
prints the list under the bound and says what the processes are.
On 10-27, a sandbox magpie serve with a made-up Claude sign-in and real
Claude Code 2.1.311 against a mock API got 8 concurrent subagent-like
requests. It kept 6 Claude Code and 6 helpers, and the list named the same
6 pids that ps showed. Quitting magpie ended all 12 within a second.
How large one Claude Code process may grow (claudeRunBudget, #3256)
claudeRoom bounds how many Claude Code processes run, not how large each
is. A run is kept for its conversation's next turn, turn after turn, and a
service that is never restarted kept one for days: on a 31 GiB host a
node-MainThread in magpie.service reached 8 GiB RSS and the kernel's OOM
killer took the machine's other work with it.
Each time a run's reply ends, oversized (claude_rss.go) reads the
resident memory of its process tree (proc.Tree.RSS: /proc/<pid>/status
VmRSS on Linux, ps -o rss= on macOS, the working sets of every process in
its job on Windows, where an npm install's claude.cmd is a cmd.exe with
the node under it) and logs it with the pid. The budget is an eighth of the
memory magpie may use (memLimit on Linux, proc.MemTotal elsewhere), at
least 1 GiB, 4 GiB where neither is known. It is read once per process.
- A whole turn (
ended, stop) over the budget: the run is not kept idle. Its session is shelved at the conversation's key (letGoOversized), and the next turn resumes it in a new Claude Code (--resume), told only the new messages, so Anthropic's cache is read as before. - A reply that called the client's tools (
park) over 1.5× the budget: the run is let go, and the results start a new run told the whole conversation. It has no session to shelve there, so it waits for more.
Each Claude Code a run starts logs its pid and model when it starts, and its
run time, how it ended and its peak RSS (proc.PeakRSS, rusage
ru_maxrss; not on Windows) when it ends: an OOM report's pid can be found
in magpie's log.
The run's working folder (clientWorkDir)
Claude Code tells its model the folder it runs in as the "Primary working
directory". A run has no tools of its own: the client's run in the
client's folder. Run in magpie's shared work folder (claudeWorkDir,
<tmp>/magpie-claude-work-<uid>), the model was told that folder. It then
wrote the client's files there, through the client's own tools, while the
client's own prompt named another folder. Under a real Claude Code client,
pelican.html landed in magpie's folder.
A run therefore starts in the folder the caller names. clientWorkDir
reads the system prompt and every message that is not the model's, and
takes the last folder named. It knows four ways of naming it:
- Claude Code: "Primary working directory: X";
- Codex:
<cwd>X</cwd>; - OpenCode: "Working directory: X";
- pi: "Current working directory: X".
The folder is taken only when it is an absolute path to a folder on this computer. Otherwise, as for a caller elsewhere, a Windows path on a Mac, or no folder named, the run starts in the shared folder as before. A Claude Code in WSL always takes the shared folder.
A run in the shared folder for a caller that names a folder
(Request.envElsewhere) has Claude Code's prompt give this computer's
platform, OS and the shared folder, and the caller's give another's. A
model told both spent tool calls finding out which is real (vv_nil on X:
a Mac client of a Linux gateway). Since every tool is the caller's,
renderClaudePrompt ends the caller's instructions with
envElsewhereNote: the environment they describe is where every tool
runs, and goes before one given earlier. It names no app or vendor, since
it goes upstream. Not measured: how many tool calls it saves on a real
run.
A caller on another computer (Request.remoteCaller, not local) that
names no folder (Request.envUnknown) has only Claude Code's environment
to go on, and that is the gateway's. packinggoods on Discord, a Mac
client of a Windows gateway, had every command wrapped in PowerShell.
Such a caller's instructions end with envUnknownNote: the environment
given elsewhere is not where the tools run, so no platform, shell or path
is taken from it. A caller with no instructions of its own gets the
block for the note alone. A caller on this computer that names no folder
is told nothing more: Claude Code's platform and shell are its own.
Claude Code has no option to leave its environment out. In 2.1.312 it
is a <system-reminder> in the run's first message, before magpie's
text, with --system-prompt-file too; the SDK's excludeDynamicSections
only moves it there. So a lean run (claudeLeanPrompt) is told the same
in its system prompt (leanSystem), the named-folder note worded as
envElsewhereLeanNote since the environment comes after it there
(envNote picks the note).
Nothing else of the folder reaches the run. --setting-sources "" loads
no CLAUDE.md, settings or skills from it. Auto memory is off, and
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1 keeps the repository's status out
of the prompt, which would change it, and Anthropic's cache with it,
whenever a file changes. The system prompt magpie sends is unchanged; only
the folder Claude Code runs in is.
A run's sessions are saved in that folder's project
(<config>/projects/<the caller's folder>), beside the user's own Claude
Code sessions there when the run is on the user's own sign-in. Claude
Code's --resume picker lists them while they last. That project is never
swept: only magpie's own folder is (sweepSessions). A run's session is
removed there by its id, when it ends or is discarded (removeSession).
A session that a stopped gateway left there, and its temp files, stay
there as the user's own sessions do; a sweep can't tell them apart.
Files a run leaves
- Its session:
<config>/projects/<work project>/<session>.jsonl, for--resume(claudeSessions). It is removed when the run ends unless shelved, and when a saved session is discarded (removeSession).sweepSessionsremoves those a stopped gateway left in magpie's own work folder's project, once older thanidleLongest; a caller's folder is never swept (clientWorkDir). - Claude Code's temp files for the session, the images it was given:
<CLAUDE_CODE_TMPDIR or /tmp>/claude-<uid>/<work project>/<session>(claudeTempDir, not on Windows). They are removed with the session (removeSession). The sweep removes those whose session file is gone and in which nothing changed fortempLongest(a day). The folder is the run's work folder's for every account, and another account's session files are in its own config folder.
A run started anew still sends every image in the conversation. Replacing earlier images with a placeholder would change what the model sees, and magpie doesn't do it.
Tool results another request answers first
A request with tool results finds the run waiting on those calls (match)
and claims it (claimResume) until the reply it is resumed for ends. More
than one request can carry results for the same calls: Claude Code's fork
sub-agents each start from their lead's conversation as it stands, its
reply's calls answered with the placeholder "Fork started — processing in
background" and the fork's directive after, and they come at once with the
lead's own next turn; a client may also send a turn again while the first
is still answered. The first to claim the run goes on in it. Each of the
others, and one whose run has ended, is a conversation of its own from
there and gets a run started anew (answeredElsewhere in the log). It is
never refused: Claude Code doesn't retry a 409, and the agent that sent it
stops (ylorn on Discord).
The user's words beside tool results (#872, #1878)
A user message can hold tool results and, after them, text blocks of the user's: Claude Code's AgentSummary asks for its sub-agent's progress label that way ("Describe your most recent action in 3-5 words. Do not use tools.", JinJieBeWater), a fork its directive, and an older Claude Code a message sent while a tool ran (#872). The words are the user's, and both ways a run is told them keep them apart from the tool's output:
- A run told the messages as text (
renderParts, for a run started anew and for a resumed turn): a text or file part after a tool result in the same message closes the result,[end of tool result id=…], and is marked[user message]. Before, it ran on after the tool's last line (SOURCE_LAST_LINEDescribe your…), and the model read it as tool output and went on with the task. A result followed by nothing, or by another result, is told as before. - Results that go on in their run (
match,continueWith):matchno longer adds the words to the last result's text, which made them part of the MCP result.saidWithResultstakes them, andcontinueWithwrites them to Claude Code's input as a user message (queue) before it hands the results over, and waits for Claude Code'scommand_lifecycle"queued" for that message's uuid (at mostqueuedWait, 2s; a version that doesn't say goes on after it). Claude Code then tells its model the message with the result, as one the user sent while it worked ("The user sent a new message while you were working: …"), within the turn. Tried with the real Claude Code 2.1.296 against a local mock of Anthropic: the next request holds the tool's output, then that reminder, and the turn ends with oneresult. Handed over after the results, a message could come after the model's reply and start a turn of its own.
What the client's agent puts beside the results is not the user's (#2060).
Claude Code 2.1.296 sends its hooks' notices ("PreToolUse:Bash hook
additional context: …"), its <total_tokens> count and a message the user
sent mid-turn as one {role: "system"} message after the results; older
versions send them as <system-reminder> text blocks in the results'
message. saidWithResults takes from a system message only the words
after "The user sent a new message while you were working:" (or "The user
sent the following message:"), without Claude Code's ask around them, and
leaves out a text that agentNotice knows: empty within its reminder
tags, a hook's notice of a known kind, a token count, or a lead userWords
drops (injected). Before, nearly every call of a client with a hook was
followed by "The user sent a new message while you were working:" and the
hook's output, or nothing (the run's Claude Code doesn't show a bare
<total_tokens>). renderParts closes a result before such a notice
without marking it [user message]. A reminder with other words in it is
still the user's, as #872's was.
A background sub-agent's <task-notification> (with its "[SYSTEM
NOTIFICATION - NOT USER INPUT]" head) is not the user's either, but the
run's model must hear it. Claude Code 2.1.310 sends one that finishes while
its main agent is mid-turn as a {role: "system"} message after the
results (several that finish together share one text block), or as text
after them in their message. withTaskNotices appends each to the last
result, inside <system-reminder>, as Claude Code itself does for a
notification that lands in a tool's result, and saidWithResults strips
them before judging what is left. Before, agentNotice dropped them
whole, the run never heard the sub-agent finished, and the main agent
waited for it (stones_2026 on Discord). A notification after a reply is a
turn of its own and is told as it is.
Where the result ends is said by the message's parts alone. A tool whose output says "Do not use tools." has it told as its output, inside the result. The words of a message that holds images (pi-ai's "Attached image(s) from tool result:" over Chat, #1382) still go with the result before them, with the images.
A request with words beside the results still takes the run waiting on
the calls when it comes first (claimResume). An AgentSummary that does
is answered in the sub-agent's run, and the sub-agent's own next request
then gets a run started anew, as any request after another answered the
calls does. Starting such a request anew instead would tell the whole
conversation to a new run, a prefix the cache has never seen (#1716,
#1717), for every message sent mid-turn.
Tool calls written as text
A run told the conversation as text (renderClaudePrompt, and
renderClaudeTurn with the client's own calls in the turn) is shown each
past call as a [tool call <name> id=… args=…] line and each result as
[tool result id=…]. The model can copy that form and write its calls as
text: Claude Code has no call to make, the turn ends with end_turn, and the
client shows the lines as the reply's words while nothing runs (Zhenzhen on
Discord: Claude Desktop on Fable 5.1 got
[tool call mcp__magpie__Bash id=toolu_0Validate bash args={…}]).
- Such a prompt ends with a note (
pastCallsNote) that the lines record earlier calls and that writing one calls nothing. A prompt with no call in it is told as before. readOutputholds back a reply's words from the first line that opens with[tool call(textCalls); words before it, and lines that only start like it, go on as they come. A reply that ends there with end_turn and calls none of the client's tools isn't ended: once its turn'sresultis in, the run is toldtextCallsAskas a user message, and the reply goes on in the next message (onemessage_start, as after Claude Code's own call), so the client gets the realtool_useand its results go on in the run. It is asked once per reply: written as text again, the words reach the client as written. A run with no input to write to, or a reply that called the client's tools too (the text is left out), is not asked.
The account's allowance on the reply (#1257)
Claude Code tells a run's account allowance in its stream-json
rate_limit_event, not as HTTP headers. The bridge keeps it
(provider.NoteClaudeLimits) and says it again on the reply as the
anthropic-ratelimit-unified-{5h,7d,7d_oi}-{utilization,reset} headers
Anthropic sends (limitHeaders, from provider.KeptClaudeLimits): a share
from 0 to 1 and a Unix-seconds reset, for each kept window that says when
it renews. They are set when the request comes in, from what is kept, and
again as the reply begins (relay's begin), once the turn's own
rate_limit_event is in. A run on Claude Code's own home that has moved to
another account says nothing (ClaudeCodeMovedOff), as its event isn't
kept either.
A Claude Code signed in to claude.ai (its sign-in field set to
claudeai, claudeSignIns in internal/agent/claude.go) reads these into its status line's rate_limits, which
claude-hud shows. One that signs in to magpie with magpie's key
(ANTHROPIC_AUTH_TOKEN) ignores them: Claude Code 2.1.293 reads the
headers only for a claude.ai subscriber. A reply another provider answered
carries none.
A restart to update
A run is a Claude Code process of this magpie's, so a restart to update
that hands the gateway to the new version (GUI shell)
waits for the bridge's turns, and for none of the gateway's other requests
(restartBusy in handover.go: Busy.Bridge,
Tools, BridgeLast). A run's tool calls go to the gateway's port, which
the new one serves once it has the socket; a claude-mcp token the new one
doesn't know is forwarded to the old one's callback socket
(ForwardCallbacks, forwardCallback), which serves it until it quits
(ServeCallbacks). A run idle between turns ends with the old process,
and the next turn starts a run in the new one, as after any restart.
Verification
go test -tags nogui ./internal/gateway/ -run '^TestClaudeClientCache' -count=1
go test -tags nogui ./internal/gateway/ -run '^TestClaudeLeanPrompt' -count=1
go test -tags nogui ./internal/claudecode/ -count=1
go test -tags nogui ./internal/gateway/ -run '^TestClaudeCodeGivenTheBridgeForASOCKSProxy$' -count=1
go test -tags nogui ./internal/provider/ -run '^TestClaudeSignInBridgesASOCKSProxy$' -count=1
go test -tags nogui ./internal/netproxy/ -run '^TestEnvForBunWith' -count=1
go test -tags nogui ./internal/gateway/ -run '^TestClaudeToolNamesComeBackAsDeclared$' -count=1
go test -tags nogui ./internal/gateway/ -run 'TestClaudeRunsHeldToTheRoom|TestClaudeRoom|TestClaudeOneOffsTakeRoom|TestClaudeMemRuns|TestClaudeRunsMost|TestClaudeNoRoom' -count=1
go test -tags nogui ./internal/cli/ -run '^TestClaudeCodeRuns' -count=1
go test -tags nogui ./internal/gateway/ -run '^TestClaudeRunsNamesEachProcess$' -count=1
go test -tags nogui ./internal/settings/ -run '^TestClaudeRunsMostIsMachineLocal$' -count=1
go test -tags nogui ./internal/gateway/ -run 'ClaudeSubscriptionRunsTheDownloaded|ClaudeSubscriptionWithoutClaudeCode|ClaudeRewritten|LostMedia|ImagesTakenOut|RunLetGoWhenTheClientRewrote|ClaudeSessionTempFiles|ClaudeLetGo|ClaudeSessionFiles|ClaudeOldSessions|ClaudeSubscriptionReplySaysTheAllowance|ClaudeAllowanceHeaders|ClaudeForksAnsweringTheLeadsCalls|ClaudeTurnGivenUpOn|ClaudeToolResultsGivenUpOn|ClaudePromptMarksEarlierTurns|ClaudeHistoryCachedAcrossNewRuns|ClaudeUnloadableSession|ClaudeEndedRunSaysWhy|ClaudeIdle|ClaudeSideQuestion|ClaudeNoRunSaysWhy|ClaudeToolResultsNoRunSaysWhy|ClaudePromptToldUserText|ClaudePromptKeepsInstructions|ClaudeToolResultsGoOnWithTheUsersWords|ClaudeToolResultsKeepInstructions|ToolResultKeepsUserTextSentMidTurn|ClaudeTextToolCalls|ClaudeTextCallsHoldsOnlyTheLine|ClaudePromptSaysPastCallsAreARecord' -count=1
go test -tags nogui ./internal/gateway/ -run 'TestClaudeTaskNotification|TestWithTaskNotices|TestClaudeTurnToldTheTaskNotification' -count=1
claude_rewritten_test.go has a case for each relaxation and one for each
rule that keeps another conversation out; claude_lost_media_test.go does
the same for images taken out, from Hana's request bodies. claude_resume_test.go's harness
stands in for Claude Code with a script that keeps sessions as it does.