Skip to main content
Glama

⚡ Swarm Engine

Turn your AI assistant into an entire engineering team.

A pure Agent Skill for Antigravity, Claude Code, OpenCode, Kilo, and Roo Code · Unbounded parallel subagents · Zero Git collisions · Live Web Board & Terminal Dashboard

License: MIT Tests: 96 Passing Antigravity Parity: 100% TypeScript Node.js Zero Vulnerabilities Concurrency: Unlimited

Installation Guide • Pure Skill Architecture • How It Works • Using with Your AI Tool • The Swarm Board • FAQ


💡 What Makes Swarm Engine Different?

What Happens Normally

What Swarm Engine Does

Why You Win

One Agent at a TimeTasks run sequentially. 5 tasks take 5× longer.

Unlimited Parallel Subagents ($\infty$)Decomposes missions into 5 to 20+ specialized subagents.

5x to 10x faster execution. True concurrent throughput.

Git Conflicts & OverwritesAgents edit the same files and corrupt code.

Direct Workspace Execution (Zero Worktrees)Coordinator partitions files cleanly (workspace: "inherit" by default).

Zero git collisions. Direct workspace editing without worktree bloat.

Silent Down-Tiering to Weaker ModelsCoding workers downgraded to low-spec models.

Automatic User Model InheritanceCoders automatically run on your session model (Gemini 3.5 Flash, Gemini 3.8 Pro, Claude 3.7 Sonnet, DeepSeek V4.1).

Zero quality compromise. Never downgraded.

Clunky External Apps & Manual OverheadForced to run separate CLI apps and watch spinners.

Pure Agent Skill (Native in Chat)Operated 100% natively inside your AI assistant's chat.

Zero context switching. No terminal windows needed.

Fragile Framework-Specific MCPsBespoke configs that break across tools.

Universal Dynamic Harness SupportAutomatically adapts to Antigravity, OpenCode, Claude Code, Kilo, and Roo.

Works everywhere. Install once, run anywhere.


Related MCP server: forge-orchestrator

📦 Installation Guide

You can install and use Swarm Engine in multiple ways depending on your preferred workflow:

The fastest way to install the skill across all coding assistants on your machine (Google Antigravity, OpenCode, Claude Code, Kilo, Roo Code, Cursor, Continue):

# 1. Clone the repository
git clone https://github.com/PRIYAGDEV/swarm-engine.git
cd swarm-engine

# 2. Install dependencies & build
npm install
npm run build

# 3. Synchronize the skill to all detected AI environments
npm run sync:skills

What this does: Automatically discovers installed agent environments and installs the swarm-engine skill package into their canonical directories (~/.gemini/config/skills, ~/.claude/skills, ~/.config/opencode/skills, ~/.config/kilo/skills, ~/.roo/skills, etc.).


Method 2: Global CLI & Live Web Board 🌐

Install the swarm-engine CLI globally to access the command-line tools, live HTTP Web Board server, and interactive terminal dashboard:

# Clone and install globally
git clone https://github.com/PRIYAGDEV/swarm-engine.git
cd swarm-engine
npm install -g .

Verify the installation:

swarm-engine --help

Method 3: Direct Manual Skill Copy (Zero Build Needed) 📂

If you want to use Swarm Engine purely as an AI prompt skill without running Node.js build commands, simply copy the skills/swarm-engine folder directly into your tool's skill folder:

AI Assistant

Target Skills Directory

Google Antigravity

~/.gemini/config/skills/swarm-engine

OpenCode

~/.config/opencode/skills/swarm-engine

Claude Code

~/.claude/skills/swarm-engine

Kilo Code / Kilo CLI

~/.config/kilo/skills/swarm-engine

Roo Code / Cline

~/.roo/skills/swarm-engine (or ~/.cline/skills/)

Cursor / Continue

~/.cursor/skills/swarm-engine (or ~/.continue/skills/)


Method 4: Model Context Protocol (MCP) Server Setup 🔌

Swarm Engine includes a full Model Context Protocol (MCP) server exposing 15 tools for swarm orchestration, atomic directory locking, blackboard memory, and board telemetry.

Add it to your MCP configuration (e.g. opencode.jsonc, claude_desktop_config.json, or IDE MCP settings):

{
  "mcpServers": {
    "swarm-engine": {
      "command": "swarm-engine",
      "args": ["mcp"]
    }
  }
}

Or execute via Node directly with the built distribution:

{
  "mcpServers": {
    "swarm-engine": {
      "command": "node",
      "args": ["/absolute/path/to/swarm-engine/dist/index.js", "mcp"]
    }
  }
}

🚦 Quick Start Verification

Once installed, simply open your AI assistant inside any project workspace and ask:

"Run a swarm to build the authentication service, database models, and unit tests in parallel."

To monitor the swarm in real-time, launch the visual board:

swarm-engine board --open

🎯 Pure Agent Skill Architecture

Swarm Engine is designed from the ground up as a pure AI Agent Skill (SKILL.md). There is no complex terminal setup required to use it—your AI assistant loads the skill and uses four standard tools:

Tool

What It Does

swarm

Manages the swarm: title, add (spawns workers), models, model (hot-swap), kill, and channel.

post_message

Posts immutable messages to the shared message board (.swarm/board.jsonl) with @doorbell mentions.

read_board

Reads messages, diff summaries, and test outputs filtered by sequence number (since) or channel.

swarm_wait

Puts the coordinator to sleep with zero token consumption until a worker posts an update.


🚀 Using Swarm Engine with Your Favorite AI Tool

Swarm Engine installs natively as an Agent Skill across all major AI agent environments:

  1. Pre-installed globally at ~/.gemini/config/skills/swarm-engine/SKILL.md.

  2. Antigravity discovers the skill and activates the Swarm Coordinator protocol.

  3. Simply instruct Antigravity in chat:

    "Run a swarm to build the authentication service, database models, and unit tests in parallel"

  4. The coordinator automatically uses your active session model (e.g. Gemini 3.5 Flash or Gemini 3.8 Pro) for all technical coders.

  1. Swarm Engine automatically detects active workspace sessions and subagents directly from OpenCode's runtime database (~/.local/share/opencode/opencode.db).

  2. Active editor models (DeepSeek V4.1 Flash, GLM-5.3-Flash, Nara, Apinex, etc.) and spawned subagents (sched-worker, fs-worker, syscall-worker, gui-apps-worker) sync directly to the live Swarm Board.

  3. Subagents run with direct workspace file ownership and real-time status reporting.

  1. Installed at ~/.claude/skills/swarm-engine/SKILL.md.

  2. Claude Code automatically delegates multi-file tasks into parallel subagents.

  3. Technical workers automatically inherit Claude 3.7 Sonnet without quality compromise.

  1. Installed at ~/.config/kilo/skills/swarm-engine/SKILL.md.

  2. Kilo reads your active model directly from kilo.jsonc or editor state (e.g. MiniMax-M2.7, GLM-5.3-Flash, DeepSeek).

  3. Agents run concurrently with zero file collisions.

  1. Installed at ~/.roo/skills/swarm-engine/SKILL.md.

  2. Operates via shared workspace protocols and isolated branches.


⚙️ How Does It Work?

               User Request in Chat
                         │
                         ▼
             ┌────────────────────────┐
             │   Coordinator Agent    │  (Uses swarm-engine skill)
             │   (Sizes & Splits DAG) │
             └───────────┬────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
   ┌───────────┐   ┌───────────┐   ┌───────────┐
   │  Worker 1 │   │  Worker 2 │   │  Worker 3 │  ... (5 to 20+ parallel agents)
   │  Schema   │   │  API Dev  │   │  Tests    │
   └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
         │               │               │
         ▼               ▼               ▼
      prisma/        controllers/      tests/     (Direct in-place file ownership)
         │               │               │
         └───────────────┼───────────────┘
                         ▼
             ┌────────────────────────┐
             │  Shared Message Board  │  (Doorbell @mentions & topic channels)
             │  (.swarm/board.jsonl)  │
             └───────────┬────────────┘
                         ▼
             ┌────────────────────────┐
             │ Verified Milestone OK  │  (In-place review & testing)
             └────────────────────────┘
  1. Size & Split: The coordinator deconstructs the mission into independent pieces (one per file or module).

  2. Direct Workspace Execution (Zero Worktrees): Workers operate directly in your project repository (workspace: "inherit" by default) without creating git worktree folders.

  3. File Ownership: The coordinator assigns distinct, non-overlapping files so agents collaborate in-place without collision.

  4. Coordinate: Workers communicate via @doorbell mentions on the shared message board.

  5. Optional Worktree Sandboxing: Isolated Git worktrees (workspace: "share") remain available if an isolated experimental git branch is ever explicitly requested.


🔮 Google Antigravity Swarm Parity (Enhanced)

Swarm Engine delivers 100% architectural parity with Google Antigravity's native /swarm and /teamwork skills, enhanced with production-grade isolation:

  1. Automatic Model Inheritance (Zero Quality Compromise):

    • Technical coders, builders, and authors automatically inherit your active conversation model (Gemini 3.5 Flash, Gemini 3.8 Pro, Claude 3.7 Sonnet, DeepSeek V4.1).

    • Operational stall monitors and background narrators automatically use lightweight models to save quota during checks.

    • Down-tiering to smaller models is strictly opt-in.

  2. Doorbell Mentions & Monotonic Sequences:

    • Every message is given a sequential #seq ID (#1, #2, #3).

    • Mentioning @name wakes only that worker from swarm_wait.

    • Mentioning @all broadcasts to all active workers.

    • Channel mentions (@#ui) alert only subscribers to that topic stream.

  3. Workspace Isolation & Fallback:

    • inherit: Shared working directory for direct in-place editing.

    • share: Isolated Git worktrees for parallel authors when branch isolation is desired.

    • branch: Independent clones for experimental refactoring.

    • Non-Git fallback for directories without Git history.

  4. Stall Watchdog (monitor):

    • An independent monitor wakes when the swarm goes quiet and alerts @coordinator [stall] with the specific stuck sequence numbers.


📊 The Swarm Engine Board (Split-View UI & CLI)

Swarm Engine provides real-time observability through both a live Web Board and an interactive Terminal Dashboard:

  • Header: Swarm title (stats and dedupe packages), animated ● Live status pulse, and manual refresh trigger.

  • Tab 1: Board <count>: Live monotonic sequence of immutable board posts with avatar chips, @sender → @targets mentions, sequence numbers (#1, #2, #3), timestamps (2:24 PM), path chips (internal/stats/), and real-time search.

  • Tab 2: Members <count>: Real-time team roster displaying status dots (🟢 Working, 🟡 Standing By / Sleeping, ⚪ Completed / Retired), assigned models (e.g. Gemini 3.5 Flash, Claude 3.7 Sonnet, DeepSeek V4.1), target files, and token telemetry.

  • Tab 3: Graph: Interactive visual DAG node graph showing live communication channels, dependency edges, and collaboration sequence timeline.

# Start live reactive HTTP board with SSE auto-refresh on http://localhost:3456
swarm-engine board

# Launch directly in default web browser
swarm-engine board --open

# Export standalone, self-contained HTML artifact styled with Tailwind CSS
swarm-engine board --html

# Render aligned ANSI terminal board view
swarm-engine board --plain

# View live auto-refreshing terminal status dashboard
swarm-engine watch

❓ Frequently Asked Questions

No. Swarm Engine is a pure Agent Skill. You interact with your AI assistant in chat as usual. The assistant activates the skill, splits the work, and manages the swarm autonomously. The web board and terminal dashboard are completely optional observability interfaces.

No. By default, Swarm Engine runs with workspace: "inherit" just like Antigravity's /teamwork and /swarm. Workers operate directly in your project directory with zero git worktrees created on disk, zero git branch switching, and zero merge overhead. File conflicts are designed out upfront by assigning distinct files or modules to each worker.

Swarm Engine uses atomic POSIX/Windows directory file locks (.swarm/state.lock). If Worker 1 is editing auth.ts, Worker 2 is blocked from reserving auth.ts until Worker 1 finishes and releases the lock.

Run npm run sync:skills from the project repository to synchronize the canonical SKILL.md across Antigravity, Claude Code, OpenCode, Kilo, and Roo Code.


📄 License

MIT © PRIYAGDEV

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for orchestrating a fleet of CLI coding agents in isolated git worktrees. It exposes tools for spawning workers, sending instructions, reviewing diffs, and merging changes, with full terminal visibility.
      7 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables orchestrating multiple AI coding tools (Claude Code, Codex CLI, Gemini CLI) on shared repositories with file locking, knowledge capture, task planning, and drift detection via an MCP server.
      166
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coordinating Claude Code and Codex on one machine by fanning out tasks to multiple agents in isolated Git worktrees, comparing results, picking a winning candidate, and handing off work between harnesses. It provides MCP stdio tools, a CLI, and a local loopback web cockpit.
      Apache 2.0