Open-source project
unclebob/swarm-forge avatar
unclebob/swarm-forge

SwarmForge's main branch is the installer, not a runnable product

A simple tool for coordinating several AI agents.

4,105 stars411 forksClojureLicense varies

At a glance

What is it?
SwarmForge composes packs of AI agent roles into a project through a curl and chmod helper that reads two branches at once, then starts them as tmux sessions in isolated git worktrees. What is worth reading closely is where the rules live: three constitution articles are reserved so a pack cannot rewrite them, and the configuration grammar is deliberately branch specific.
Who is it for?
SwarmForge is built for someone who already has a git repository and a working agent backend, and who wants several agents with separated worktrees rather than one long session. Two things decide whether it fits.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 69 days ago.
What is it written in?
Mainly Clojure, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • unclebob/swarm-forge4,105 ★ · +308
Star history
Repository2026-09-112026-11-15
unclebob/swarm-forge3.8k4.1k

308 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The default branch is the installer and the rulebook, not a product

The first thing the documentation settles is what the branch you are reading is not. The repository's master branch is named `main`, and it is described as the landing page, the installer source, the shared runtime and the shared engineering law. It is explicitly not a runnable SwarmForge product. Nothing you clone from `main` starts a swarm on its own.

Products live on other branches, one per variant, and each is installed with its own subcommand of the same helper: `get-swarm-forge two-pack`, `four-pack`, `six-pack`, `project-manager` and `lieutenant`. Every one of them is a branch with its own README, and installing one copies files out of two branches, `main` for the shared parts and the product branch for the rest.

Three more branches exist that are not products at all: `squad`, `sprint-module-squad` and `adversaries` are named as separate experimental workflows that are not `get-swarm-forge` products. The distinction matters because the product list is the only thing the helper advertises.

So the shape is a repository that is mostly a distribution point. The runnable thing arrives by composition, into your directory, not by cloning.

The installer is curl, chmod, and a copy from a branch

The supported entry point is a single file you put on your PATH yourself:

sh
mkdir -p ~/cmds
curl -L -o ~/cmds/get-swarm-forge \
  https://raw.githubusercontent.com/unclebob/swarm-forge/main/get-swarm-forge
chmod +x ~/cmds/get-swarm-forge

Then `~/cmds` goes on your PATH, and you recopy the helper when it changes. The stated reason the helper is the supported route rather than a clone is that it composes files from more than one branch, which a plain checkout of `main` cannot do.

The prerequisites list is short and opinionated: zsh, git, tmux, Babashka available as `bb`, and at least one configured agent backend, named as grok, codex, claude or copilot. The launcher script in the repository root is called `swarm`, and a matching `close-swarm` sits beside it for shutting down.

Worth being explicit about: the install is a script fetched over HTTPS from a branch URL with no checksum, no signature and no release tag attached to it. Whatever trust you place in this tool is trust in that branch's current contents.

There is no version to pin, so an install is whatever the branch held

The repository has no GitHub releases, and the install path does not reference a tag or a version anywhere. The helper is copied from the `main` branch, and the product content comes from the product branch, which is itself a moving branch rather than a release. Two installations run a week apart can therefore differ without either of them doing anything wrong.

The instruction to recopy the helper when it changes is the matching half of that design. The tool expects to be re-fetched rather than upgraded, which is a workable model for an installer and an awkward one for a fleet of machines or a CI runner, where nothing tells you which content a given machine received.

What you get installed is written into your project directory. For a pack install the helper writes the launcher, the configuration file, the constitution entry point, the pack's own articles and the role prompts into the tree you ran it in, on top of the shared runtime and dashboard that come from `main`. There is no uninstall described, and no list of what was added, so reversing the install means knowing what the composition step wrote.

Config file order is the pipeline, and exactly one role owns master

Every running project has a `swarmforge/swarmforge.conf`, and for the fixed packs each non-comment line follows one shape:

text
window[-invisible] <role> <backend> <worktree> [task|batch] [forward-only|back-one|back-all] [backend arguments...]

Three rules give the file most of its behaviour. File order is the default forward pipeline, so the sequence of lines is the sequence of roles rather than a set. Exactly one role must name the `master` worktree, and that name is a sentinel meaning the project's main checkout on whichever branch it is currently on; every other name becomes a checkout under `.worktrees/<name>`, which is what keeps the agents isolated. And the first token decides whether the role gets a visible terminal surface, with `window-invisible` running only inside tmux and being opened from the dashboard when needed.

The grammar is explicitly extensible, and that is the part to watch. Branches may add their own control plane tokens, with `lieutenant` adding typed `card` routes and the squad branches adding a `swarmforge/squad.conf`. The selected branch's own README and its parser are named as the authority, so the grammar you read on `main` does not describe every product.

Receive mode and propagation have defaults worth understanding

The two optional brackets in that config line are the scheduling behaviour, and both have defaults that are easy to leave unexamined.

Receive mode defaults to `task`, meaning a role takes one queued handoff. `batch` lets a role accept a compatible group of queued handoffs together, which is how a refactoring or cleanup role avoids making a separate pass for every small change it was handed. Propagation defaults to `forward-only`, so work travels down the pipeline as the file order reads. `back-one` and `back-all` arrange merge-only copies back to earlier roles after downstream work finishes, which is how a specification or architecture role learns what the implementer actually did without being able to write through the same path.

Anything after those two brackets is passed to the backend, and the supported backend names are codex, grok, claude and copilot. Forge hosts do not use this grammar at all: their configuration line is `Lieutenant <backend> [backend arguments...]`, a different shape for a different job.

Three article names are reserved so a pack cannot replace the law

The engineering rules are composed as data rather than baked into the launcher. A pack agent is started with instructions to read `swarmforge/constitution.prompt`, read recursively whatever that file names, and then read its own `swarmforge/roles/<role>.prompt`.

Three article names belong to `main` and cannot be taken by a product: `engineering.prompt` covering language defaults, testability, acceptance pipeline tooling, verification and quality tool guardrails; `workflow.prompt` covering worktree discipline, commit attribution, temporary files and failure conditions; and `handoffs.prompt` covering the structured send, receive, merge, retry and completion protocol. A pack specialises them with differently named local files such as `project.prompt`, `local-engineering.prompt` or `local-workflow.prompt`, and the composer reserves those three names so a pack cannot silently replace common law.

Below that, role prompts divide ownership: what a role may change, what it must verify, what it must leave to another role, and where its next handoff goes. There must be a matching prompt for every configured role, so a config line naming a role with no prompt file is a configuration error the runtime will hit. The one exception is a forge lieutenant, whose shared prompt explicitly places it outside the project engineering constitution.

Two packs, two forges, and a distinction the docs labour over

The five products split cleanly once you know the difference between a pack and a forge. A pack is composed into an existing project, and running `./swarm` starts that project's configured roles. A forge is installed into an empty host directory, where `./swarm` starts the forge dashboard and host lieutenant, and project swarms start only when the operator creates or opens projects beneath `projects/`.

The packs are role chains of increasing size. The two-pack is coder then cleaner. The four-pack adds a specifier in front and an architect behind, giving specifier, coder, refactorer, architect. The six-pack names six separate roles covering specification, implementation, cleanup, architecture, hardening and QA. The two forges are multi-project: `project-manager` carries selectable two, four and six pack templates plus a host lieutenant, and downloads the three pack branches into `packs/` during install, while `lieutenant` carries one configurable project template under `.swarmforge/project-pack/` and pairs it with a planning lieutenant.

So the two forges differ in how many templates they carry, not in kind. If you want one project, the packs are the whole product and the forge machinery is overhead.

A token scam warning sits above the title, and no licence is declared

The first thing on the readme page is not a description. It is a red, underlined warning telling readers not to spend money on a bankrbot SWARM token, typo included, sitting above the project title. It reads as a leftover from an earlier namesake, and it is the only place the word token appears in the documentation.

The licence situation is the other loose end. There is no LICENSE file at the root of the tree, and the repository's licence field is empty. Nothing in the documentation states terms either. For a tool whose whole job is writing files into your repository and driving agents that commit to it, that is the first thing to settle before running it.

The tree itself is mostly distribution material: `get-swarm-forge`, `swarm`, `close-swarm`, `bb.edn` for Babashka, `swarmforge/` for the runtime and constitution, `test/`, and an `AGENTS.md`. It also carries planning artefacts at the root, with `issues.md`, `project-board.md`, `platoon-brainstorm.md` and a screenshot named `project-swarm.jpg`.

The project is written in Clojure, is not archived, has no GitHub releases, and was last pushed on 2026-09-07.

Editorial conclusion

SwarmForge is built for someone who already has a git repository and a working agent backend, and who wants several agents with separated worktrees rather than one long session. Two things decide whether it fits. First, the install path copies a script from a moving branch with no release to pin, so what you install is whatever that branch held at the moment you copied it, and you are told to recopy it when it changes. Second, the behaviour of a configuration file is defined by the branch you selected, so the README you read on main is not the authority for a lieutenant or squad setup. Read the selected branch's own README before trusting its grammar, and decide in advance who answers the approval gates, since the dashboard expects a human on the other side of them.

Frequently asked questions

What is SwarmForge?

A tool that coordinates AI agents in isolated git worktrees and tmux sessions, where agents exchange committed work through durable handoffs and a local dashboard is used to start work, inspect agents, handle approval gates, answer clarifications and stop the swarm.

What do I need installed before using SwarmForge?

zsh, git, tmux, Babashka available as bb, and at least one configured agent backend: grok, codex, claude or copilot.

What is the difference between a SwarmForge pack and a forge?

A pack is composed into an existing project and ./swarm starts that project's configured roles. A forge is installed into an empty host directory, where ./swarm starts the forge dashboard and host lieutenant, and project swarms begin once projects exist beneath projects/.

How does the SwarmForge configuration file define the agent pipeline?

Each non-comment line of swarmforge/swarmforge.conf names window or window-invisible, a role, a backend and a worktree, followed by an optional receive mode, an optional propagation mode and any backend arguments. File order is the default forward pipeline, and exactly one role must use the master worktree.

Does SwarmForge publish versioned releases?

No. The repository has no GitHub releases, and the supported entry point is a helper copied from the main branch, which composes files from more than one branch and has to be recopied when it changes.

Official sources

  1. Issues
  2. README
  3. unclebob/swarm-forge on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/unclebob-swarm-forge.svg)](https://hysenlabs.com/projects/unclebob-swarm-forge)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/unclebob-swarm-forge.svg)](https://hysenlabs.com/projects/unclebob-swarm-forge)

Was this useful?