swarm
This server coordinates a multi-agent swarm on a shared message board: manage workers, exchange messages, read board/roster state, and wait for new activity.
Inspect swarm status and list available models.
Add one or multiple named workers with briefs, model pinning, task slices, history forking, workspace isolation, and initial channel subscriptions.
Change a worker's model, kill workers, and set a swarm title.
Create, list, subscribe/unsubscribe, and archive channels.
Post messages to the board with @mentions (
@name,@all,@#channel) and optional channels.Read messages by sequence range, exact sequences, limit, channel, or retrieve roster status instead.
Wait for new board messages with mention-only filtering and timeout, consuming zero tokens while sleeping.
Use an optional caller name override when sharing one server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@swarm start a swarm to split this migration into parallel tasks and coordinate via the board"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pt-swarm: Multi-Agent Parallel Collaboration System
This package is a complete port of the Antigravity Swarm architecture, packaged and adapted for the Polytoken harness.
Unaffiliated project. This is an independent, unofficial port. It is not affiliated with, endorsed by, sponsored by, or supported by Polytoken, Google Antigravity, or their maintainers. Product names are used only to describe interoperability and provenance.
Third-party assets. Files adapted from Antigravity —
sidecar_ui/,skills/,plugin.json, andassets/logo.svg— are included for interoperability and may be subject to separate upstream terms. The MIT license in this repository covers the code authored for this port, not those upstream assets. See NOTICE for the file-by-file breakdown.
It enables multiple autonomous AI agents to work in parallel on separated tasks, synchronized via an append-only shared message board with @mentions, channels, zero-token sleep parking, and stall monitoring.
Package Contents
pt-swarm/
├── README.md # Architecture guide & integration instructions
├── AGENTS.md # AI agent guidance, invariants, and TDD commands
├── docs/ # Provenance, specs, and review history
│ ├── PORTING_MANIFEST.md # Detailed provenance (rebuilt vs adapted breakdown)
│ ├── SPEC_NATIVE_SUBAGENTS.md # Native-subagent design spec
│ ├── REVIEW_FINDINGS.md # Code review findings ledger
│ ├── REVIEW_REMEDIATION.md # Findings disposition ledger
│ └── POLYTOKEN_SIGKILL_BUG_REPORT.md # polytoken 0.9.8 macOS plugin-runtime crash report
├── .gitignore
├── LICENSE # MIT
├── NOTICE # Third-party provenance and terms
├── MANIFEST.in # Source distribution contents
├── package.json # npm manifest (dashboard binary)
├── pyproject.toml # Python package & CLI entrypoints
├── plugin.json # Antigravity upstream plugin descriptor (legacy/attribution only — the live Polytoken manifest is plugin/polytoken.plugin.json)
├── assets/
│ └── logo.svg
├── pt_swarm/ # The single installed package
│ ├── __init__.py
│ ├── board_manager.py # File-locked board, @mention parser, wait loop
│ ├── swarm_tools.py # Tool dispatch and validation
│ ├── tool_defs.py # TOOLS built from tool_schemas/ + argument gate
│ ├── worker_runner.py # Cross-process worker supervisor
│ ├── workspace_manager.py # Git worktree / clone isolation
│ ├── stall_monitor.py # Deadlock and unaddressed-post detection
│ ├── cli.py # Terminal board & roster viewer
│ ├── model_selection.py # Model request resolution
│ ├── model_hook.py # Session model hook
│ ├── plugin_bridge.py # CLI bridge used by the Polytoken plugin tools
│ └── tool_schemas/ # JSON Schemas for function calling
├── plugin/ # Polytoken plugin package (tools, hooks, resources)
│ ├── polytoken.plugin.json # Plugin manifest (capabilities, tools, config schema)
│ ├── src/index.ts # Tool + hook handlers (Extism JS PDK)
│ ├── vendor/plugin-framework/ # Vendored framework shim (unpublished npm package)
│ └── resources/ # Copies of subagents/ and skills/ shipped as plugin resources
├── skills/ # Skill runbooks (source of record)
│ ├── native_swarm/SKILL.md
│ ├── swarm_monitor/SKILL.md
│ └── swarm_narrator/SKILL.md
├── subagents/ # Polytoken subagent manifests
├── .polytoken/ # Project-local Polytoken config (auto-discovered)
│ ├── subagents/*.md
│ └── skills/*/SKILL.md
├── schemas/ # On-disk format specs (documentation)
│ ├── board_jsonl.md
│ ├── members_json.md
│ └── view_json.md
├── sidecar_ui/ # Real-time Web dashboard (Node.js + HTML)
│ ├── main.mjs, channels.mjs, app.js, hive.js, index.html
│ └── sidecar_sdk/index.mjs # Standalone shim for the host sidecar SDK
├── tests/ # Python unittest & Node.js test suites
├── test_adapter.py
├── test_board.py
├── test_cli_and_schemas.py
├── test_model_selection.py
├── test_plugin_bridge.py
├── test_plugin_definitions.py
├── test_polytoken_only.py
├── test_tool_defs.py
├── test_worker_review.py
├── test_workspace_preservation.py
├── test_plugin_shim.mjs
├── test_sidecar_frontend_review.mjs
└── test_sidecar_ui.mjsEverything the runtime needs is inside pt_swarm/, so an installed copy is self-contained. plugin/resources/ holds byte-identical copies of the top-level subagents/ and skills/ trees (the sources of record) so the plugin package ships them; a test fails if the copies drift. .polytoken/ holds the project-local copies Polytoken auto-discovers from this repo root; they carry the same content and are covered by the same parity tests.
Related MCP server: connectr
Porting Provenance (Rebuilt vs. Adapted)
See PORTING_MANIFEST.md for full technical rationale and architecture mapping.
Adapted Verbatim from Antigravity:
Skill runbooks:
skills/native_swarm/SKILL.md,skills/swarm_monitor/SKILL.md,skills/swarm_narrator/SKILL.mdLive UI dashboard:
sidecar_ui/*Metadata and icons:
plugin.json,assets/logo.svg
Rebuilt / Reverse-Engineered for Polytoken:
Tool Schemas (
pt_swarm/tool_schemas/*.json): formalized from internal RPC definitions.Board & Tool Engine (
pt_swarm/board_manager.py,swarm_tools.py,tool_defs.py): replaces Antigravity's compiled Go backend.Role Prompts (
subagents/*.md): standalone role prompts, shipped as plugin resources.Runtime Glue (
pt_swarm/worker_runner.py,workspace_manager.py,stall_monitor.py,plugin_bridge.py).
How It Works in Polytoken
1. The Coordinator Loop
The user talks to the Coordinator.
For a multi-faceted task, the Coordinator splits the work into independent chunks.
The Coordinator calls
swarm(action="add", name="<worker>", brief="...").The brief is posted to the board as
@<worker> <brief>. With no process spawner configured,swarmreturns aswarm-workerdelegation and the coordinator starts it as a native subagent; configured external spawners continue to launch workers themselves.
2. The Worker Loop
Workers run in separate sessions with their own tools. Native workers are started by the coordinator; external workers can be spawned by
worker_runner.pywhen configured.When finished or handing off, the worker posts to the board with
@<next_peer>.The worker calls
swarm_wait(since=LAST_SEEN)to sleep with zero token consumption until pinged.
3. The Monitor (swarm-monitor)
On a timer, it detects unaddressed posts and unanswered @mentions, then tags the responsible agent (e.g. @coordinator [stall] #14 unaddressed).
4. Real-time UI (sidecar_ui)
The dashboard visualizes the live board feed, the member roster and states, the @mention graph, and narrator overview cards from view.json.
Board identity (important)
All agents in a workspace share one swarm entry point, so every tool call accepts a caller roster name. There is no persistent server process — each plugin tool call carries its caller explicitly and the bridge defaults to POLYTOKEN_AGENT_NAME or coordinator. The worker prompt and the spawn prompt both instruct workers to pass caller="<name>"; without it, a worker's posts and read cursors are attributed to the coordinator.
Model selection
A member's model is a request, not a literal selector. swarm(action="add", model=...)
records it on the roster, and WorkerProcessManager resolves it once per spawn into a value
polytoken exec --model accepts:
Request | Runs on |
unset, | the member's role tier: |
| that reserved Polytoken tier group |
| the model this Polytoken session is running, as recorded by the hook below; the role tier when nothing is recorded |
anything else | passed through unchanged: a model name, a |
The roster keeps both halves: model/desired_model is the request and applied_model
is the selector the process launches with. polytoken exec rejects the default sentinel
("model 'default' is not configured"), so a member with no resolved model starts without
--model at all. swarm(action="models") lists the models this install can run and
repeats these rules under selection.
The plugin records the model the session is running: its session_start and
pre_user_prompt hooks (exports polytoken_hook_session_start /
polytoken_hook_pre_user_prompt) run python3 -m pt_swarm.model_hook, which writes
POLYTOKEN_MODEL_NAME into <swarm_dir>/session_model.json.
Note (polytoken 0.9.8): whether the plugin hook's shell environment carries
POLYTOKEN_MODEL_NAMEcould not be verified live — the plugin runtime crashes the polytoken daemon on macOS (seedocs/POLYTOKEN_SIGKILL_BUG_REPORT.md). If the variable is absent, the hook is a harmless no-op andsessionfalls back to the role tier.
The plugin wires these hooks for you. To record the session model without the plugin —
for example when driving the engine from your own harness — add the same two hooks
manually: hooks.json is environment-local (gitignored), so add the block to
.polytoken/hooks.json in the project or to ~/.config/polytoken/hooks.json for a
global install:
[
{
"name": "swarm-session-model",
"event": "session_start",
"handler": { "bash": "python3 -m pt_swarm.model_hook; echo '{\"outcome\":\"allow\"}'" }
},
{
"name": "swarm-session-model-switch",
"event": "pre_user_prompt",
"handler": { "bash": "python3 -m pt_swarm.model_hook; echo '{\"outcome\":\"accept\"}'" }
}
]Without the hook everything still works — session just falls back to the role tier.
Quickstart Integration Example (Python)
The board engine is plain Python, so a harness that is not Polytoken can drive the same tools directly:
from pt_swarm.board_manager import BoardManager
from pt_swarm.swarm_tools import SwarmToolHandlers
# 1. Point the board at a swarm directory (one per workspace).
bm = BoardManager("./.swarm/default")
# 2. Build the handler stack; the caller name is the roster identity.
tools = SwarmToolHandlers(bm, caller_agent_name="coordinator")
# 3. Dispatch tool calls from your agent loop.
tools.handle_swarm(action="add", name="parser", brief="Parse the config format")
tools.handle_post_message(text="@parser start with the lexer")
tools.handle_read_board(since=0)Installation & Setup (Polytoken plugin path)
The Polytoken integration ships as a single installable plugin package, plugin/, which
provides the four swarm tools as plugin tools (plugin__pt-swarm__swarm, …__post_message,
…__read_board, …__swarm_wait), records the session model via plugin hooks, and ships the
subagent manifests and skills as plugin resources. No server block and no manual
copying are needed.
Plugin architecture
model ──▶ plugin tool (WASM, plugin/src/index.ts)
│ serializes input JSON, base64-encodes it on the bridge command line
▼
host shell capability (polytoken_plugin_shell_exec)
│ python3 -m pt_swarm.plugin_bridge <tool> --args-base64 <b64>
▼
pt_swarm.plugin_bridge ──▶ SwarmToolHandlers ──▶ BoardManager
│ one JSON line on stdout
▼
plugin tool parses and returns ok/err envelope to the modelAll board logic (file locking, cursors, wake modes, worker supervision) stays in the
tested Python engine; the WASM layer is a thin bridge. The bridge also accepts raw JSON
arguments on stdin (used by tests and manual invocation). Because plugin shell runs in
the daemon's environment, no environment-clearing or pass_env plumbing is needed.
1. Build toolchain (one-time)
polytoken plugin-dev doctor # lists missing tools
npm install -g esbuild@0.25.11 # JS PDK bundler
brew install binaryen # wasm-opt / wasm-merge
# extism-js: pinned download from https://github.com/extism/js-pdk/releases (v1.7.0)
polytoken plugin-dev doctor # must exit 0 (version warnings are fine)2. Build, pack, verify, install
cd plugin
polytoken plugin-dev build --project .
polytoken plugin-dev pack --project . --out dist/pt-swarm.pt-plugin
polytoken plugin-dev verify dist/pt-swarm.pt-plugin
polytoken plugin-dev install dist/pt-swarm.pt-pluginThe package is unsigned (built locally), so plugin_trust.allow_unsigned_local = true in
~/.config/polytoken/config.toml is required, and the plugin's capabilities (shell,
emit_message) are approved interactively on first load. polytoken plugin list shows
the installed package and its resource counts; /reload picks up a rebuilt package.
3. Per-project setup
The plugin resolves the swarm directory as:
plugins.pt-swarm.swarm_dir in the plugin config (optional) → POLYTOKEN_SWARM_DIR →
<project>/.swarm/default. A session creates the directory lazily on first use, so no
config file is required. Set plugins.pt-swarm.python if the bridge must run under a
specific interpreter (default python3).
pt_swarm must be importable by that interpreter — pip install --user . (see
Global Installation below) or pip install -e . from a checkout.
4. Subagents & skills
The plugin ships subagents/ and skills/ as plugin resources (referenced via
plugin+pt-swarm://<path>). Whether Polytoken auto-loads plugin resources as session
subagents/skills is not yet verified live (blocked by the polytoken 0.9.8 plugin-runtime
crash, see docs/POLYTOKEN_SIGKILL_BUG_REPORT.md), so this repository also keeps the
project-local .polytoken/subagents/ and .polytoken/skills/ copies, which Polytoken
auto-discovers from the repo root and which carry plugin__pt-swarm__* tool references.
A parity test keeps both copies byte-identical to the top-level sources.
5. Uninstall
polytoken plugin-dev remove pt-swarm # or delete the .pt-plugin from the project's plugins dir, then /reload
pip uninstall pt-swarm # if the Python engine was installed for the bridgeGlobal Installation (Available in Any Project)
The plugin path above is per-project. To make the swarm available in every Polytoken project, install the Python engine and the plugin package globally.
In this repository: the plugin resolves
.polytoken/subagents/and.polytoken/skills/from the repo root, so a checkout works with no extra config — install the engine and build the plugin (see Installation & Setup (Polytoken plugin path)).In another project: install the package (
pip install /path/to/pt-swarm), copy this repository's.polytoken/into that project's root, and install the packed plugin package.
1. Install the Python engine & CLI entrypoints
pip install --user .
# Homebrew and most distro Pythons are PEP 668 "externally managed" and
# reject a bare `pip install .`:
# pip install --user --break-system-packages .
# `--user` keeps the install in ~/.local and leaves the interpreter's own
# site-packages untouched. This registers pt-swarm-cli (pt_swarm.cli:main) and pt-swarm-plugin-bridge (pt_swarm.plugin_bridge:main) on your PATH, and installs the tool schemas inside the package. The plugin bridge is what the plugin's tool layer shells out to.
2. Install the plugin package globally
Build and pack it once (see Installation & Setup (Polytoken plugin path)), then install
the resulting .pt-plugin into the user plugin directory so every project picks it up:
polytoken plugin-dev install dist/pt-swarm.pt-plugin
polytoken plugin list # shows pt-swarm and its resource counts The plugin resolves the swarm directory per project: plugins.pt-swarm.swarm_dir in the
plugin config (optional) → POLYTOKEN_SWARM_DIR → <project>/.swarm/default. Because the
last fallback is relative to the project, ./.swarm/default isolates each workspace's
board to that project and a session creates the directory lazily on first use.
To enable the swarm in selected projects only, install the package into that project's plugins directory instead of the user-wide one.
3. Environment variables
Plugin shell runs in the daemon's environment, so no environment-forwarding plumbing is
needed: variables exported in your shell are visible to the bridge. Workers inherit that
environment too, so polytoken on PATH is enough for polytoken exec spawns to load the
same config the session uses.
A spawn that fails anyway reports the exit code, the log tail, and a hint naming the
environment variables your config references — an empty model list with spawned: false
and mode: unconfigured usually means polytoken was not found on PATH.
4. Subagents & skills
The plugin ships subagents/ and skills/ as plugin resources, so no copying is needed.
This repository additionally keeps project-local .polytoken/subagents/ and
.polytoken/skills/ copies, which Polytoken auto-discovers from the repo root; a parity
test keeps them byte-identical to the top-level sources.
The manifests' polytoken.tools lists reference the plugin tool names
(plugin__pt-swarm__*), which resolve when the plugin is installed.
5. Install the Web UI globally (optional):
npm pack
npm install -g --prefix ~/.local ./pt-swarm-1.0.0.tgz
rm -f pt-swarm-1.0.0.tgz
# run it with:
POLYTOKEN_SWARM_DIR=./.swarm/default pt-swarm-ui The dashboard binds 127.0.0.1:5388 by default; override with HOST and PORT.
Two packaging details matter: installing from the folder (npm install -g .) creates a symlink back to this checkout, so the global command breaks if the checkout moves — install the packed tarball for a self-contained copy. And when npm's default prefix is not writable (common with Homebrew or distro Node), pass --prefix ~/.local; its bin/ directory must be on PATH.
6. Worker process spawning:
WorkerProcessManager launches workers with polytoken exec "<prompt>", which needs polytoken on PATH. To override the default command (which includes exec --model {model}), set POLYTOKEN_WORKER_CMD in the environment the session runs in, for example:
env:
POLYTOKEN_WORKER_CMD: "polytoken exec {prompt}" Supported placeholders: {prompt}, {name}, {model}, {workspace}, {swarm_dir}.
{model} is the member's resolved selector (see Model selection). When a template puts
{model} after a --model/-m flag and nothing resolved, both tokens are dropped, so
polytoken exec --model {model} {prompt} degrades to polytoken exec <prompt> instead of
failing on an invalid model name.
A worker that exits during startup is reported as a failed spawn (spawned: false with its exit code and log tail) rather than a running agent.
7. Uninstall:
# remove the installed plugin package, then /reload
rm -f ~/.config/polytoken/plugins/pt-swarm.pt-plugin # or the project's plugins dir
pip uninstall pt-swarm
npm uninstall -g --prefix ~/.local pt-swarmRunning the CLI, UI & Tests
# Watch the board in a terminal
python3 -m pt_swarm.cli --swarm-dir ./.swarm/default --watch
# Launch the live web dashboard (http://127.0.0.1:5388/)
POLYTOKEN_SWARM_DIR=./.swarm/default node sidecar_ui/main.mjs
# Run all tests (Python unittest discovery and Node.js test runner).
# The Python packaging regression builds an sdist; install its build requirement first:
python3 -m pip install 'setuptools>=77.0'
python3 -m unittest discover -s tests -v
node --test tests/test_sidecar_ui.mjs tests/test_sidecar_frontend_review.mjs tests/test_plugin_shim.mjsNotes:
Use
python3; many systems do not provide apythonalias.The dashboard accepts
POLYTOKEN_SWARM_DIR(direct board directory),SWARM_CONVERSATION_ID,HOST, andPORT. WithoutPOLYTOKEN_SWARM_DIRit falls back to./.swarm/default..polytoken/hooks.jsonand.polytoken/context.py, if present in a checkout, are environment-local session hooks; they are git-ignored and are not part of the distributable package.
Available Tools
4 toolspost_messageB
Post a message to the shared swarm message board.
Inputs: text (required), caller, channel.
read_boardC
Read posts from the shared swarm board or retrieve member states.
Inputs: seqs, limit, since, caller, +2 more.
swarmC
Manage the swarm of agents working on the shared message board. Actions: status, models, add, model, kill, title, channel.
Inputs: action (required), n, op, all, +11 more.
swarm_waitA
Sleep until a new message is posted to the board. Consumes zero tokens while sleeping.
Inputs: since (required), caller, mentions_only, timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
post_message, read_board, and swarm_wait have reasonably distinct purposes, but the catch-all 'swarm' tool with seven bundled actions (status, models, add, model, kill, title, channel) overlaps with read_board's 'retrieve member states' capability. An agent must guess whether to use swarm(status) or read_board for member info, and whether add/kill belong to swarm or a separate membership tool.
All names are snake_case, but conventions are mixed: post_message and read_board are verb_noun, swarm_wait is noun_verb, and 'swarm' is a bare noun with no verb at all. The grouping is still readable, but there is no predictable pattern for predicting a new tool's name.
Four tools is compact and appropriate for a messaging-board server, and each top-level tool earns its place. However, the 'swarm' tool hides seven sub-actions, meaning the effective surface is larger than the count suggests and would be clearer as separate tools.
The surface covers the core loop: manage membership/lifecycle, post, read, and block for new messages. Minor gaps exist — no edit/delete of messages, no targeted/direct messaging, and no way to filter or paginate the board — but agents can work around these.
Maintenance
Related MCP Connectors
Privacy-first coordination for autonomous agents: rooms, messaging, inbox, and per-agent memory.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Multi-agent coordination for AI agents: shared spaces, tasks, search, mailbox and persistent state.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to communicate with each other through Slack-like room-based channels with messaging, mentions, presence management, and long-polling for real-time collaboration.44 npm5MIT
- AlicenseNot gradedqualityDmaintenanceCoordinates multiple AI coding agents by providing a shared task board, memory, and advisory file claims, letting agents work on the same repo concurrently without duplicating work or overwriting each other.29 npm1MIT
- AlicenseNot gradedqualityBmaintenanceLocal OS for your AI Agents fleets. ——————- Enables AI agents to coordinate through a durable local board with shared state, ticket lifecycle, evidence-based approvals, and journal-woken handoffs.3Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents on different accounts or machines to communicate via shareable rooms, with structural anti-prompt-injection defenses and optional autonomous cowork (autoloop) where agents alternate turns toward a shared goal.MIT