unclebob/swarm-forge

SwarmForge – A tmux‑based orchestration layer for AI‑agent teams

What it is – SwarmForge is a locally‑run tool that lets you run a swarm of large‑language‑model (LLM) agents as if they were a disciplined software‑engineering team. It wires together multiple agents (e.g., Claude, Codex, Copilot, Grok) inside a single git worktree, gives each a dedicated tmux pane, and lets them hand‑off work to one another via a simple file‑based protocol. A lightweight web dashboard (the pack cockpit) shows the whole process as a Kanban‑style board.

Why it exists – Building non‑trivial software with a single LLM is fragile. SwarmForge splits the development pipeline into clear roles—specifier, coder, cleaner, architect, hardender, QA, etc.—and enforces a hand‑off flow so each role can focus on a specific quality gate. The system is deliberately local‑only (no cloud services required) and uses familiar tools (git, tmux, zsh) to keep the setup lightweight and reproducible.

Core concepts

Concept	What it does
Pack	A pre‑defined workflow template stored on a branch (`two-pack`, `four-pack`, `six-pack`). Each pack defines a set of roles, prompts, and a `swarmforge.conf` that describes the swarm topology.
Role	An individual agent (e.g., `coder`, `cleaner`). Each role has a prompt file (`swarmforge/roles/<role>.prompt`) and runs in its own tmux window (visible or invisible).
Constitution	A hierarchy of prompt files (`constitution.prompt` + articles) that encode shared engineering policies and hand‑off rules.
Dashboard	A local web UI (`./swarm`) that shows projects, tasks, attention items, and a chat with the lieutenant (the top‑level overseer agent).
Handoff protocol	Agents exchange work via validated JSON‑like files placed in `.swarmforge/handoffs/`. The daemon `handoffd.bb` moves files between inboxes/outboxes and notifies the recipient tmux pane.

How it works (step‑by‑step)

Install the helper – copy get-swarm-forge to a folder on your $PATH and run it in an empty directory. It pulls main plus all pack branches, creates packs/, projects/, and host scripts under swarmforge/.
Start the host – ./swarm launches the dashboard and a single lieutenant agent (by default Grok). The UI prints a URL (also saved to .swarmforge/dashboard-url).
Create a project – via the dashboard click New Project, give it a name, pick a pack (e.g., four‑pack), optionally link a GitHub repo, and edit the generated mission.md and swarmforge.conf.
Swarm launch – SwarmForge reads the project’s swarmforge.conf, creates a git worktree for each role under .worktrees/, copies the shared scripts and constitution into each worktree, and starts a tmux session per role. Each role launches its configured LLM backend.
Task flow – Adding a task on the board creates a card that is handed to the first role in the pack. The role produces a draft, runs swarm_handoff.sh to queue a hand‑off, and the daemon delivers it to the next role’s inbox. The next role runs ready_for_next.sh, works on the draft, and eventually calls done_with_current.sh to move the card forward.
Human gates – Certain hand‑offs (e.g., specifier → coder) generate an Approval row in the Attention pane. A human can approve or reject, which either forwards the card or returns it with a comment.
Observation – Clicking a role or a card opens a live tmux pane in a resizable browser window, letting you see the raw LLM output, logs, or edit the prompt on the fly.
Teardown – Clicking Teardown stops all tmux sessions, the daemon, and the dashboard, leaving the project directories on disk.

Main features (as described in the README)

Config‑driven topology – Swarm shape is defined entirely in swarmforge.conf; no hard‑coded scripts.
Role‑specific prompts & constitution – Each role reads its own prompt plus layered “constitution” articles that encode engineering policies.
Per‑role backend selection – You can point any role to Claude, Codex, Copilot, Grok, etc.
Pack cockpit UI – Kanban board, task queue, attention list, and chat with the lieutenant, all in a local browser.
Git‑worktree isolation – Each role works in its own git worktree, preventing accidental file clashes.
File‑based handoff protocol – Simple, auditable hand‑off files (git_handoff and note) with built‑in audit counters and optional human approval.
Self‑hosted & lightweight – Only requires zsh, git, tmux, Babashka (bb), and an LLM CLI; runs on macOS or Linux without external services.
Sleep inhibition – Prevents the host from sleeping while a swarm is active (via caffeinate or systemd-inhibit).

Typical use‑cases

Small backend scripts – Use the two‑pack for rapid prototyping where a single coder‑cleaner loop suffices.
Mid‑size services – four‑pack adds a specifier and architect, giving you Gherkin acceptance specs and a lightweight architectural review.
Large, safety‑critical codebases – six‑pack introduces dedicated QA, hardening, and mutation‑testing roles, enabling a full‑fledged development pipeline driven by LLM agents.
Educational demos – The simple-windows tag shows the minimal UI (one terminal per role) for teaching the orchestration concepts.

Getting started (quick checklist)

Install prerequisites: zsh, git, tmux, Babashka (bb). Ensure you have a CLI for at least one LLM backend.
Place get-swarm-forge on your $PATH and run it in an empty folder.
Run ./swarm to launch the dashboard.
Click New Project, pick a pack, and give the project a name.
Use New Task to add work; watch the cards move through the roles.
When finished, click Teardown to stop the swarm.

Limitations & scope (as per the repo)

SwarmForge is local‑only; it does not provide a cloud‑hosted orchestration service.
The system assumes you have access to an LLM backend via a command‑line interface; it does not include the models themselves.
Human approvals are required for certain hand‑offs; the UI does not automate those decisions.
The dashboard is a simple static web UI served from the repository; it is not a full‑featured project management tool.

TL;DR

SwarmForge lets you run a team of LLM agents as disciplined software engineers on your own machine. By defining a pack (workflow template) you get a set of roles, each with its own prompt and backend, coordinated through tmux and a tiny hand‑off protocol. The web dashboard visualises the process, supports human approvals, and keeps everything reproducible in git worktrees.