SwarmForge: Coordinating AI Agents Through Git Worktrees and tmux
A simple tool for coordinating several AI agents.
At a glance
- What is it?
- SwarmForge is a Clojure-based installer and runtime that composes role-based AI agent packs into existing repositories, using isolated git worktrees for parallel work and a handoff protocol for committed exchanges. The main branch is a landing page and shared runtime, not a runnable product.
- Who is it for?
- SwarmForge is for engineering teams already comfortable with git worktrees, tmux, and at least one of the supported agent backends (codex, grok, claude, copilot). It is not for anyone who wants a single-command agent runner or who cannot install zsh, git, tmux, and Babashka.
- 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 9 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 September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What SwarmForge Solves and Who It Serves
Running several AI agents on one repository creates three concrete problems: they overwrite each other's files, they lose context between turns, and the operator has no single place to see what each agent is doing. SwarmForge addresses all three by giving each role its own git worktree and tmux session, exchanging work only through committed handoffs, and exposing a local dashboard for starting work, inspecting agents, handling approval gates, answering clarifications, and stopping the swarm. The target user is an engineer who already works in a terminal, understands git branches, and wants to run a pipeline of specialized agents (for example specifier, coder, refactorer, architect) rather than a single general-purpose agent. The README's framing is explicit: the main branch is the landing page, installer source, shared runtime, and shared engineering law, not a runnable product. That distinction matters because a newcomer who clones main and looks for ./swarm will not find a working swarm.
How the Installer Composes Branches into a Running Project
The mechanism is branch composition. For a pack install, the get-swarm-forge helper downloads two branches: main supplies swarmforge/scripts/ (shared runtime and dashboard) and swarmforge/constitution/articles/ (shared engineering, workflow, and handoffs rules), while the named pack branch supplies the swarm launcher, swarmforge/swarmforge.conf, swarmforge/constitution.prompt, pack-local articles, and swarmforge/roles/. The result is written into the current project. 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 composer reserves those three names for main, so a pack cannot silently replace common law. For a forge install, the named forge branch supplies the host runtime, lieutenant, and dashboard. The project-manager forge also downloads the three pack branches into packs/, while the lieutenant forge carries its one template under .swarmforge/project-pack/. This is a data-driven design: instructions are composed as files rather than baked into the launcher.
The swarmforge.conf Grammar and What Each Field Controls
Every running project has a swarmforge/swarmforge.conf. For the fixed packs, each non-comment line follows 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, which is a sentinel for the project's main checkout on its current branch; other names become .worktrees/<name> checkouts. window opens a terminal surface, while window-invisible runs only in tmux and is opened from the dashboard when needed. Receive mode defaults to task; batch lets a role accept a compatible group of queued handoffs together. Propagation defaults to forward-only; back-one and back-all arrange merge-only copies for earlier roles after downstream work. Supported backends are codex, grok, claude, and copilot, with remaining tokens passed to that backend. Forge hosts instead use Lieutenant <backend> [backend arguments...]. Branches may extend the grammar for their own control plane, for example lieutenant adds typed card routes and the squad branches add swarmforge/squad.conf. The selected branch README and its parser are the authority for those extensions, which means the grammar is not one specification but several per-branch dialects.
Constitution Articles and Role Prompts as Separation of Ownership
A normal pack agent is started with instructions to read swarmforge/constitution.prompt, recursively read what it names, and then read swarmforge/roles/<role>.prompt. The three shared articles divide responsibility: engineering.prompt covers language defaults, testability, acceptance-pipeline tooling, verification, and quality-tool guardrails; workflow.prompt covers worktree discipline, commit attribution, temporary files, and failure conditions; handoffs.prompt covers the structured send, receive, merge, retry, and completion protocol. A product branch contributes its own constitution entry point and any differently named local articles such as project.prompt, local-engineering.prompt, or local-workflow.prompt. Role prompts divide ownership inside that law: 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. The one documented exception is a forge lieutenant: the shared lieutenant.prompt explicitly keeps it outside the project engineering constitution. The practical consequence is that adding a role to swarmforge.conf without adding a corresponding prompt file will leave that agent without instructions.
Prerequisites, Installation Commands, and the Supported Entry Point
The README lists these prerequisites: zsh, git, tmux, Babashka (bb), and at least one configured agent backend among grok, codex, claude, and copilot. The helper is installed by downloading it to a directory on PATH: mkdir -p ~/cmds, then curl -L -o ~/cmds/get-swarm-forge https://raw.githubusercontent.com/unclebob/swarm-forge/main/get-swarm-forge, then chmod +x ~/cmds/get-swarm-forge. The README states that the helper is the supported entry point because it composes files from more than one branch, and that you should recopy the helper when it changes. To install a pack in an existing software repository, the documented sequence is get-swarm-forge six-pack followed by ./swarm. To install a forge, you run get-swarm-forge in an empty directory. The README text supplied here is truncated mid-command at get-swarm-forg, so the exact forge invocation cannot be confirmed from this material; the product table lists get-swarm-forge project-manager and get-swarm-forge lieutenant as the two forge options. There are no retrieved releases, so there is no versioned artifact to pin.
Where SwarmForge Is the Wrong Tool, and What It Does Not Do
The most direct limitation is stated in the README itself: the main branch is not a runnable SwarmForge product. Anyone who clones main and expects a working swarm will be disappointed. Second, the tool assumes a Unix-like environment with zsh, tmux, and Babashka. There is no documented Windows path, and the dashboard is local, so remote or headless operation is not described. Third, the configuration grammar is per-branch. The README says branches may extend the grammar for their own control plane and that the selected branch README and its parser are the authority. That means a swarmforge.conf written for six-pack may not parse under lieutenant, and vice versa. Fourth, the experimental branches (squad, sprint-module-squad, adversaries) are explicitly not get-swarm-forge products, so they carry no compatibility promise. Fifth, the repository has no homepage and no retrieved releases, so there is no published versioning scheme, changelog, or upgrade path in the supplied material. Finally, the license is listed as unknown. Without a confirmed license, redistribution or commercial use cannot be assumed, and that is a real adoption blocker for many organizations.
How It Differs from a Single-Agent CLI Workflow
A single-agent CLI such as a plain codex or claude session keeps everything in one working tree and one conversation. SwarmForge instead gives each role its own worktree under .worktrees/<name>, so two agents can edit different files without colliding, and it exchanges work through committed handoffs rather than shared chat history. The handoffs.prompt article defines the structured send, receive, merge, retry, and completion protocol, which is a different model from a human copying output between terminals. The trade-off is overhead: you must maintain a swarmforge.conf, a matching role prompt per role, and a constitution that the agents read before starting. For a one-off refactor or a small script, that is more machinery than the task needs. For a multi-stage pipeline where specification, implementation, cleanup, and architecture are genuinely separate concerns, the worktree isolation and the handoff protocol are the reason to choose it over a single-agent session. The project-manager and lieutenant forges extend this further by hosting multiple projects under projects/, which a single-agent CLI does not attempt.
Maintenance, Branch Churn, and License Questions to Resolve
Maintenance cost here is branch-shaped. The helper must be recopied when it changes, and the README places the supported entry point on that helper rather than on a released binary. Packs and forges live on separate branches (two-pack, four-pack, six-pack, project-manager, lieutenant), so an upgrade means re-running the helper against the branch you use, not bumping a version number. The last push recorded for the repository is 2026-09-07, and no releases were retrieved, so there is no tag history to inspect for breaking changes. The composition rule that main owns engineering.prompt, workflow.prompt, and handoffs.prompt means a pack cannot override shared law, which limits how much a pack upgrade can surprise you, but it also means shared-law changes arrive whenever main changes. On licensing, the material says only that the license is unknown. That is not a legal opinion, but it is a factual gap: until the repository states a license, you cannot confirm the terms under which the code, the constitution articles, or the role prompts may be used or redistributed. Verify the license file before installing into a commercial repository.
Editorial conclusion
SwarmForge is for engineering teams already comfortable with git worktrees, tmux, and at least one of the supported agent backends (codex, grok, claude, copilot). It is not for anyone who wants a single-command agent runner or who cannot install zsh, git, tmux, and Babashka. Before adopting, verify that the pack branch you intend to use has a working parser for its swarmforge.conf grammar, confirm the license terms, and check that a matching role prompt exists for every role you configure. The main branch is explicitly not a runnable product, so start from a named pack or forge branch.
Community notes