Skip to main content
Glama

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, and assets/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.mjs

Everything 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.md

    • Live 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

  1. The user talks to the Coordinator.

  2. For a multi-faceted task, the Coordinator splits the work into independent chunks.

  3. The Coordinator calls swarm(action="add", name="<worker>", brief="...").

  4. The brief is posted to the board as @<worker> <brief>. With no process spawner configured, swarm returns a swarm-worker delegation and the coordinator starts it as a native subagent; configured external spawners continue to launch workers themselves.

2. The Worker Loop

  1. Workers run in separate sessions with their own tools. Native workers are started by the coordinator; external workers can be spawned by worker_runner.py when configured.

  2. When finished or handing off, the worker posts to the board with @<next_peer>.

  3. 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, default, auto

the member's role tier: @mg:polytoken:default_model_full for workers and verifiers, @mg:polytoken:default_model_mini for the monitor and narrator

full, mini, nano

that reserved Polytoken tier group

session

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 name(level) reasoning variant, or a @mg:<group> group reference

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_NAME could not be verified live — the plugin runtime crashes the polytoken daemon on macOS (see docs/POLYTOKEN_SIGKILL_BUG_REPORT.md). If the variable is absent, the hook is a harmless no-op and session falls 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 model

All 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-plugin

The 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 bridge

Global 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.

  1. 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)).

  2. 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-swarm

Running 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.mjs

Notes:

  • Use python3; many systems do not provide a python alias.

  • The dashboard accepts POLYTOKEN_SWARM_DIR (direct board directory), SWARM_CONVERSATION_ID, HOST, and PORT. Without POLYTOKEN_SWARM_DIR it falls back to ./.swarm/default.

  • .polytoken/hooks.json and .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 tools
post_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

    B3/5.0

    Scored across 4 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Coordinates 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 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local 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.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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