SwarmForge: coordinating AI coding agents in git worktrees and tmux

The problem SwarmForge addresses: agents that need to hand work to each other

A single AI coding agent working in your repository has one context window and one working tree. SwarmForge splits the job across several agents, each with a named role, each in its own git worktree, each running inside a tmux session. The README describes the exchange as "durable handoffs": agents pass committed work to one another rather than relying on a shared chat history.

The audience is narrow and specific. You need to be comfortable with zsh, git, tmux, and Babashka, and you need at least one configured agent backend among grok, codex, claude, or copilot. The README also states plainly that the main branch is "the landing page, installer source, shared runtime, and shared engineering law. It is not itself a runnable SwarmForge product." That is an unusual thing for a project to say about its own default branch, and it matters: cloning main and looking for a runnable entry point will not get you a running swarm. You install a product, and the product lives on another branch.

Packs, forges, and the branch-per-product layout

SwarmForge ships two shapes of thing. 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, and running ./swarm starts the forge dashboard and a host lieutenant; project swarms start when the operator creates or opens projects under projects/.

The products are selected by name through the helper: two-pack, four-pack, six-pack, project-manager, and lieutenant. The two-pack runs coder then cleaner. The four-pack runs specifier, coder, refactorer, architect. The six-pack splits the work into six roles covering specification, implementation, cleanup, architecture, hardening, and QA. The README also notes that squad, sprint-module-squad, and adversaries are separate experimental workflows and are not get-swarm-forge products, which is a useful boundary to respect when reading issues or branches.

The composition step is where the design gets interesting. For a pack install the helper downloads two branches: main contributes swarmforge/scripts/ and swarmforge/constitution/articles/, while the pack branch contributes the swarm launcher, swarmforge/swarmforge.conf, swarmforge/constitution.prompt, pack-local articles, and swarmforge/roles/. The three shared article names, engineering.prompt, workflow.prompt, and handoffs.prompt, always come from main. A pack specializes them with project.prompt and local-*.prompt files. The README calls this out explicitly: the composer reserves those three names so a pack cannot silently replace common law. That is a deliberate constraint, and it is the kind of constraint that prevents a downstream product from quietly redefining the handoff protocol under everyone else's feet.

The swarmforge.conf contract, line by line

Configuration is a flat text file, one role per line. For the fixed packs, the README gives this shape:

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

File order is the default forward pipeline. Exactly one role must use the master worktree, and that sentinel means the project's main checkout on its current branch. Every other name becomes a .worktrees/<name> checkout. The window token opens a terminal surface, while window-invisible runs only in tmux and is opened from the dashboard when needed.

Receive mode defaults to task. Setting batch lets a role accept a compatible group of queued handoffs together, which changes how much work lands in one agent turn. Propagation defaults to forward-only; back-one and back-all arrange merge-only copies for earlier roles after downstream work. The supported backends are codex, grok, claude, and copilot, and any remaining tokens on the line are passed through to that backend. Forge hosts use a different line, Lieutenant <backend> [backend arguments...].

The README is careful here: branches may extend the grammar for their own control plane, and it points at lieutenant adding typed card routes and the squad branches adding swarmforge/squad.conf. The stated authority for those extensions is the selected branch README and its parser, not the main README. If you write your own conf lines against the wrong branch's grammar, expect the parser to be the thing that tells you.

Installing the helper and running a first pack

The README's supported entry point is a shell helper rather than a package manager. The reason given is that the helper composes files from more than one branch, which a normal package install would not do. Put it somewhere on PATH:

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

After adding ~/cmds to PATH, the README says to recopy the helper when it changes, so this is a manual upgrade path rather than an automatic one. Once the helper is on PATH, install a pack into an existing software repository and start it:

get-swarm-forge six-pack
./swarm

For a forge, the README shows installing into an empty directory with get-swarm-forge followed by ./swarm; the truncated text in the README stops mid-command at get-swarm-forg, so treat the forge invocation as documented on the forge branch README rather than reconstructing the exact argument list here. What you should see after a pack install is a composed swarmforge/ directory in your project, a swarm launcher at the repository root, and a tmux session whose windows correspond to the roles in swarmforge/swarmforge.conf. The dashboard is the operator surface for starting work, inspecting agents, handling approval gates, answering clarifications, and stopping the swarm.

Where SwarmForge is the wrong tool

The prerequisites are the first filter. If tmux is not part of your workflow, or Babashka is not installed and you do not want it installed, SwarmForge has nothing to offer you. The README lists zsh, git, tmux, Babashka, and at least one of grok, codex, claude, or copilot as prerequisites, and none of them are optional.

The second filter is the work itself. SwarmForge is built around committed handoffs and worktree discipline. If your task is exploratory, if the answer is a paragraph rather than a diff, or if you want one agent to hold a long conversation with you, the multi-role pipeline adds ceremony without adding value. The six-pack in particular assigns specification, implementation, cleanup, architecture, hardening, and QA to separate roles; running that on a two-line fix is overhead you will feel immediately.

The third filter is operational. There are no retrieved releases, so there is no versioned artifact to pin and no changelog to read before upgrading. The helper is fetched from raw.githubusercontent.com and the README tells you to recopy it when it changes, which means your install tracks a branch rather than a tag. The licence is not stated in the repository, so if your organisation requires a known licence before adoption, that is a question to resolve with the repository owner rather than something you can read off the project. And the README opens with a warning not to spend money on a bankrbot SWARM token, which is a clear signal that the project's name is being used by something unrelated; check that you are installing from the repository you think you are.

How this differs from running one agent in one checkout

The closest alternative is not another multi-agent framework; it is the thing most engineers already do, which is run one AI coding agent in one working tree and review its diffs. That approach has no installer, no configuration grammar, and no tmux dependency. It also has no isolation: two agents editing the same checkout will collide, and a long session accumulates context that later work has to reason around.

SwarmForge's answer is structural. Each non-master role gets a .worktrees/<name> checkout, so agents cannot step on each other's files. Handoffs are committed, so the unit of transfer is a diff rather than a message. The constitution splits into shared articles owned by main and pack-local articles, so a product can add rules without redefining the shared ones. Propagation modes (forward-only, back-one, back-all) exist because downstream work sometimes has to flow back to earlier roles as merge-only copies.

What you give up is the conversational loop. There is no single thread where you correct an agent mid-thought; you inspect agents and answer clarifications through the dashboard, and the work moves through the pipeline in file order. If your problem is genuinely decomposable into specification, implementation, cleanup, architecture, hardening, and QA, that trade is worth making. If it is not, one agent and one checkout will be faster.

Editorial conclusion

Adopt SwarmForge if you already work in a git repository, have tmux and Babashka installed, and want several AI coding agents to hand work to each other through commits rather than through one long chat. Do not adopt it if you want a single assistant answering questions, if you cannot install a helper script on PATH, or if you need a signed release tarball, because there are no retrieved releases and the licence is not stated in the repository. Verify three things first: that the helper composes the branches you expect, that exactly one role in swarmforge/swarmforge.conf uses the master worktree, and that a matching prompt exists under swarmforge/roles/ for every configured role.

Frequently asked questions

Official sources

1. Issues
2. README
3. unclebob/swarm-forge on GitHub