The so-called Agent swarm /swarm runs on just three text files at its core
When Chasen was fixing garbled PDF text, he handed the task to Antigravity /swarm. After it finished, out of curiosity he dug through the source code and found that the shared blackboard consists of only two JSON files and one JSONL log. This article breaks down this minimalist design, including the zero-idle mechanism, deadlock-prevention monitoring, and the hidden pivot in the source code that removes the resident narrator.
A few days ago, Chasen was fixing a PDF export tool (called resume-skills on GitHub). The page looked completely normal, but copied text was often garbled, missing characters, or even had entire paragraphs reversed in order. He handed this task to Antigravity's /swarm; 7 members ran in two waves for 2 hours and 7 minutes, left 24 posts on the blackboard, and wrapped up after fixing it. Once it finished, his curiosity got the better of him, so he went through the source code of the built-in plugin swarm_board and found that the shared blackboard was supported by just two JSON files and one JSONL log.
The entire Swarm's shared state lives under the local directory <appData>/brain/<coordinatorConv>/.system_generated/swarm/:
board.jsonl: an append-only ledger, with one post per line, carrying a globally increasing sequence numberseq, posteragent, bodytext, and timetime.members.json: a roster plus read cursors, recording each member's session ID, role, model, workspace mode, and four post cursors for tracking progress.swarm.json: the signpost anchor, recording the version number, backend type, andswarm_id.
Each of the three files minds its own business. board.jsonl is append-only and never modified, naturally avoiding concurrent write conflicts. The four cursors in members.json—last_read_seq, wait_since, last_nudged_seq, and last_park_blocked_seq—record respectively the last post actually read, the post from which waiting for a wake-up begins, where the read-nudge reminder has been pushed, and the most recent post at which a member tried to sleep but was blocked. swarm.json is like a signboard, indicating the backend type and swarm identifier.
The channel mechanism does not require a separate configuration table either. When there are more than 8 members or too many modules, the blackboard can be split into channels like #parser and #ui. Creating, subscribing to, unsubscribing from, and archiving channels are all written as control messages into the same board.jsonl log. The sidebar replays the control frames in the log to determine whether a member could see a given post when it was sent; the channel list in members.json is only a cache. The source code also embeds a protocol for cross-machine distributed Swarm: if swarm.json points to a remote backend, the panel subscribes to an NDJSON incremental stream, attaches affiliation badges to members running on different machines, and triggers a resync when incremental posts have gaps.
How to choose among the multi-Agent entry points
Antigravity has four multi-Agent entry points. A regular Subagent is good for single-point verification; /boost is good for hammering away at hard-to-reproduce bugs through multiple rounds of iteration around one problem; /teamwork is good for a full set of changes advanced by milestones; /swarm is good for work that, after multi-line investigation, needs a third party to cross-check the same sample. For something like garbled PDF text, the export script and the HTML templates can be investigated separately, but the verifier must retest both sides' evidence using the same sample, so he turned on /swarm.
Zero idle spinning, without missing a single message
The thing most likely to blow up the bill in a multi-Agent system is polling. Swarm cuts polling out entirely and relies on three layers working together:
After a member finishes its work, it calls swarm_wait{since: N}. Once DONE is returned, the current round ends immediately, the session is suspended, and it truly idles at 0 tokens. Only when the member is named via @name, @all, or @#channel does the system inject a wake-up message into the conversation.
But there is a classic race condition here: a member finishes reading #10, thinks there is nothing else, calls swarm_wait(since: 10) to prepare for sleep, and in the instant it closes its eyes, #11 lands on the blackboard. The Stop Hook is designed for exactly this. At runtime it directly blocks the sleep request, injects the prompt [board] new messages arrived; read_board before waiting again, and updates last_park_blocked_seq. The original uses a vivid analogy: it is like a subway exit gate—you just swipe your card to get off work, then discover a new work order coming in; the gate locks and forces you to finish reading the new post before deciding whether to sleep.
Liveness detection, by contrast, does not consult the registry. The sidebar directly parses the tail of each member session's transcript.jsonl; only when the last entry is a reply with no tool calls, or a tool batch that contains swarm_wait and returns DONE, is it judged waiting; otherwise it is always working. Along the way it can also extract "which file is being read / which command is being run" and push it to the panel in real time.
In practice: 2 hours 7 minutes, 24 posts
That PDF investigation ran in two waves. Wave 1 had 4 people doing read-only investigation: pdf-pipeline checked the script, fonts, and glyph mapping; template-dom checked 6 sets of HTML templates; verifier did hands-on reproduction; and a monitor was attached in the background to prevent deadlocks. All shared the main workspace. After 9 and 15 minutes, two investigation results went onto the board one after the other. The verifier followed #5 and #6, used Playwright to render and pypdf to reproduce, submitted evidence at #7, and then everyone was killed for a clean reset.
Wave 2 was parallel fixing: fixer-templates, fixer-code, verifier-fix, and monitor-2. Three incidents in between decided success or failure:
- fixer-code discovered that some directories had been moved away, posted to @coordinator, and after they were restored, notified everyone uniformly to avoid everyone changing things separately.
- fixer-templates went silent for 38 minutes, and monitor-2 posted to nudge it awake. Later the whole group got stuck at #16, and the monitor nudged the Coordinator again.
- verifier-fix caught the validation script falsely reporting failure at the font switch in mixed Chinese/English text, directly named @fixer-code and sent it back for rework; 9 minutes later it was fixed and unit tests were added.
The original says that the Graph topology view makes it clear which round was sent back and who has crossed swords with whom; the Board posts let you check the raw test output. This combination is far more trustworthy than a single sentence saying "everything has been verified."
Five guardrails against runaway behavior and two major fallbacks
Long-running multi-Agent work fears three things most: the context snowball growing ever larger, getting stuck halfway or blowing through the quota, and two people fighting to modify the same file. Swarm's specification breaks these down in detail:
- A public Brief serves as the single ledger; new members' cursors skip the opening noise, so they do not swallow thousands of words of the task brief as soon as they open their eyes.
#seqreferences plus@namedoorbells; copying and pasting reports to B is forbidden, and peers hand off directly by pinging each other.- Read/write separation plus worktree working-copy isolation; the official recommendation is one read-only verifier for every 2-4 authors.
- Forking to clone conversation history and recursively recruiting helpers is supported, but permissions are kept tight: a Worker can only kill people it recruited itself.
- The anti-deadlock inspector monitor is itself an independent Agent. It checks five kinds of deadlock every 3 minutes, and if the blackboard has been quiet for 5 consecutive rounds, it stops its own alarm clock and sleeps, then revives when new messages arrive.
There is also a fallback for quota exhaustion: members.json splits desired_model and applied_model into two fields. If a member blows through its quota, there is no need to kill it; it can switch models in place, keep its conversation memory, and continue working.
There is also a real boundary: by default, Swarm Worker sessions do not have subagents permission and cannot call image-generation tools or browser subagents; they can only post to @coordinator to invoke them on their behalf. For tasks that need tools interleaved, this step must be left to the coordinator.
The hidden pivot in the source code
The most interesting part is Google's pivot on the "war room dashboard." The first-generation Swarm had a resident narrator role that watched every post and maintained view.json, and even allowed the AI to write view.html to customize the page. Because view.html is untrusted code generated by the model, Google welded a zero-trust sandbox around it: capped at 64KB, citations checked one by one, external-link allowlist, and the page runs in an offline CSP srcdoc iframe; even redirect requests must pass four gates.
As a result, the beginning of the latest SKILL.md says directly: Don't add a narrator; this Overview replaces it. No more narrator; the new Overview has replaced it. The reason is candid: a resident member adds token cost, and every time a message pops onto the blackboard it wakes a large model to rewrite a summary—burning money and lagging half a beat. The new approach uses a static plan.json plus deterministic front-end code hive.js to assemble the dashboard. The Coordinator only needs to write a few dozen lines of plan.json when work starts and when responsibilities change; the UI uses code to stitch board.jsonl and transcript.jsonl into a dynamic dashboard, and even draws a pixel queen bee and worker bees.
Behind this is an iron rule: for any view that can be computed from a static protocol plus deterministic code, never feed an extra resident LLM to watch it.
When is it worth turning on Swarm
Chasen now judges whether to turn on /swarm by only two conditions: Can the task be split into at least two independent lines that do not fight each other? Is the result after splitting worth having a third person cross-check with a real sample? For cross-module troubleshooting, parallel multi-file changes plus regression testing, a shared blackboard can keep context isolation and process traceability clean. But for a small, clearly single-line change, or work where two people would both rush to modify the same core function from the start, handing it directly to a single Agent is faster. Cost also needs to be kept in mind: each additional member adds a complete conversation and inference consumption; if no model is specified when creating a member, it defaults to the main session's high-end configuration, and the quota drops fast.
Original link: https://x.com/i/article/2122991361402228736
发布时间: 2026-11-22 22:40