《Clean Code》作者把软件工程纪律拆成了 agent 流水线——每个质量门一个独立角色，串起来就是一条完整的开发流程。

SwarmForge（Uncle Bob 的新项目）：整套协调机制就是文件系统，agent 之间靠 git 提交和交接文件说话，每个角色一个独立工作区。

SwarmForge：Uncle Bob 的 tmux 多 agent 编排，一切皆文件

是什么

Robert C. Martin（《Clean Code》作者）的项目：一个基于 tmux 的多 agent 协作编排层。和 herdr、Agent Relay 是同一赛道，但思路完全不同：

• herdr：Rust 二进制，agent 在一个进程里，socket API 控制 • Agent Relay：频道 + DM 消息 • SwarmForge：bash + tmux + git worktree + prompt 文件。一切皆文件

技术栈极简：zsh + git + tmux + Babashka。没有 Rust、没有 Postgres、没有 socket API。所有配置都是 prompt 文本文件。

核心机制

1. 角色 = git worktree

每个 agent 角色分配一个独立 git worktree，互不踩踏——git worktree 的原生隔离，不需要自己发明文件锁：

• coordinator → master（主工作区） • coder → .worktrees/coder/ • architect → .worktrees/architect/

2. 配置 = 一个 conf 文件

一行一个窗口：角色名、agent CLI、worktree、接收模式。每个角色配一个 prompt 文件：

window coordinator codex master window coder codex coder window architect claude architect task –dangerously-skip-permissions

3. 通信 = 文件握手

Agent 之间不直接对话。三个脚本：swarm_handoff.sh（提交交接）、ready_for_next.sh（接收任务）、done_with_current.sh（完成任务）。后台一个 daemon 投递——把 A 的 outbox 复制进 B 的 inbox。agent 永远不碰 tmux socket，daemon 是唯一的 tmux 拥有者。

4. 三条流水线（分支）

• two-pack（2 角色）：coder → cleaner → coder——小任务快速迭代 • four-pack（4 角色）：specifier → coder → refactorer → architect——中等项目 • six-pack（6 角色）：specifier → coder → cleaner → architect → hardender → QA——完整质量门

5. Constitution（宪法）

一个 constitution.prompt 指向 constitution/articles/ 里的多篇文章（工程规范、交接协议、工作流规则），注入每个 agent 的上下文。共享文章在 main 分支，本地覆盖用 local-*.prompt。

Uncle Bob 的独特哲学

最有趣的是角色的纪律设计——它们映射了经典软件工程流程：

• specifier 写 Gherkin 验收规范，先给你确认 • coder 用 TDD 实现 • cleaner 做 CRAP/DRY 审查（复杂度指标） • hardender 做变异测试（故意改代码看测试能不能抓住） • QA 把验收流程写成可执行脚本

这是把《Clean Code》教科书拆成 agent 角色。 Uncle Bob 用 agent swarm 实现了他理想中的软件开发纪律——每个质量门是一个独立的 agent，串成流水线。

怎么开始

BRANCH=four-pack # two-pack / four-pack / six-pack curl -L “https://github.com/unclebob/swarm-forge/archive/refs/heads/…${BRANCH}.tar.gz” | tar -xz –strip-components=1 ./swarm

依赖：zsh、git、tmux、Babashka，加一个 agent 后端（codex/claude/copilot/grok）。窗口会自动打开，第一个窗口是清理窗口（关闭它=关闭整个 swarm）。

一句话

SwarmForge 是“文件即状态“哲学的极致——不用数据库、不用 API、不用消息队列。agent 之间靠 git commit + handoff 文件通信，每个角色一个 worktree、一个 tmux 窗口、一个 prompt 文件。和 herdr（API 驱动）完全相反的方向：把协调机制降到 bash 能表达的最简形式。适合本地多 agent 协作实验，也适合当教学工具——每一层都看得见摸得着。

原文：https://github.com/unclebob/swarm-forge… #多agent编排 #tmux #UncleBob

unclebob/swarm-forge

Source: https://github.com/unclebob/swarm-forge

Do not spend any money on a bankrbot SWARM token.

SwarmForge

A disciplined tmux-based agent orchestration platform that turns swarms of AI agents into reliable, professional software engineers.

Intent

This main branch is documentary: it explains the system and carries the shared operational scripts and default constitution articles. The runnable workflow branches carry the project-facing configurations, role prompts, and local constitution articles that define specific workflows.

SwarmForge is an agent coordination system that facilitates communication between agents working in different git worktrees.

It provides a shared structure for role-specific prompts, worktree assignment, tmux sessions, and message passing so multiple agents can collaborate on the same project without stepping on each other.

Branches

The runnable SwarmForge configurations live on dedicated branches. Each branch contains the swarmforge/swarmforge.conf, local constitution articles, and role prompts for one workflow. At startup, its ./swarm wrapper copies the shared operational scripts and shared constitution articles from main when they are not already present, then launches that branch’s local configuration.

two-pack

two-pack is the quick backend workflow. Use it for small tasks that benefit from fast coding without the overhead of Gherkin and acceptance testing, while still preserving backend refactoring and hardening.

• coder implements requested behavior with TDD and unit tests.
• cleaner batches coder handoffs and performs cleanup, CRAP and DRY review, architectural review, encapsulation and separation-of-concerns fixes, and language mutation hardening.

The normal flow is coder -> cleaner -> coder. Use this branch when you want a tight implementation/refinement loop without specification, QA, property-test, or acceptance-test roles.

four-pack

four-pack is the compact specification workflow. Use it for moderate projects that require Gherkin specification and some architectural consideration without splitting every quality gate into its own agent:

• specifier turns user intent into precise Gherkin acceptance specifications and asks for approval before handoff.
• coder implements approved behavior slices with TDD, unit tests, and generated acceptance tests.
• refactorer performs behavior-preserving cleanup, coverage improvement, CRAP and DRY review, mutation-site scans, and property-test support.
• architect owns high-level structure, dependency direction, mutation hardening, DRY review, soft Gherkin mutation, and final completion notification.

The normal flow is specifier -> coder -> refactorer -> architect -> specifier. Use this branch when you want disciplined development without splitting cleanup, architecture, hardening, and QA into separate agents.

six-pack

six-pack is the full workflow. Use it for major projects that require full specification, up-front QA, backend verification, and significant architectural consideration. It separates each major quality gate into its own role:

• specifier turns user intent into accepted Gherkin specifications and end-to-end QA procedures.
• coder implements approved behavior slices with TDD, unit tests, and generated acceptance tests.
• cleaner performs local behavior-preserving cleanup, coverage improvement, CRAP and DRY review, and mutation-site scans.
• architect reviews module structure, boundaries, dependency direction, and property-test coverage.
• hardender performs mutation hardening, language mutation, CRAP and DRY verification, and soft Gherkin mutation.
• QA converts the specifier’s QA procedures into executable scripts, runs final user-interface verification, checks handoff consistency, and sends completion notifications.

The normal flow is specifier -> coder -> cleaner -> architect -> hardender -> QA -> completion. Use this branch when you want each review and verification concern owned by a separate agent.

Prerequisites

SwarmForge runs locally. Before starting a runnable branch, make sure the target machine has:

• zsh
• git
• tmux
• Babashka (bb)
• At least one configured agent backend, such as codex, claude, copilot, or grok

Getting Started

In the directory where you want to use SwarmForge, choose a runnable branch and pull its contents without creating a Git remote:

BRANCH=four-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" | tar -xz --strip-components=1

Use BRANCH=two-pack for the quick two-agent workflow, BRANCH=four-pack for the compact specification workflow, or BRANCH=six-pack for the full six-agent workflow. Do not use main for this command; main is documentary and stores the shared operational scripts, while the runnable branches provide the configurations and prompts intended for projects.

After copying a runnable branch, start the swarm from the target project:

./swarm

The ./swarm wrapper keeps the runnable branch small. On first use, if swarmforge/scripts/ is missing, it downloads the main branch archive, copies the shared operational scripts from swarmforge/scripts/, stages shared constitution articles from swarmforge/constitution/articles/, and then launches swarmforge/scripts/swarmforge.sh. Later runs reuse the existing local scripts directory instead of overwriting it.

The windows should open automatically.

To stop the swarm, close the first window listed in swarmforge/swarmforge.conf. That cleanup window shuts down the tmux sessions and closes the remaining tracked windows.

While a swarm is active, SwarmForge tries to prevent the host from sleeping. On macOS it uses caffeinate; on Linux it uses systemd-inhibit when available. Display lock or manual sleep can still interrupt agents depending on the OS. Set SWARMFORGE_PREVENT_SLEEP=0 before ./swarm to disable this behavior.

What SwarmForge Does

SwarmForge is a lightweight, tmux-based orchestration layer that:

• Launches a config-driven swarm from a project-local swarmforge/swarmforge.conf
• Creates one tmux session per configured role and opens a terminal surface for each role when the selected backend supports it
• Reads behavior from project-local swarmforge/roles/<role>.prompt files plus a layered swarmforge/constitution.prompt
• Supports per-role backends such as claude, codex, copilot, or grok
• Puts the shared swarmforge/scripts/ directory on each agent’s PATH, including handoff helpers for active swarm communication
• Creates git worktrees under .worktrees/ for roles assigned to dedicated worktree names
• Initializes a git repository in a new working directory when needed
• Keeps all swarm state local to the working directory in .swarmforge/

Core Features

• Config-Driven Topology — The swarm shape comes from swarmforge/swarmforge.conf, not hardcoded shell variables.
• Project-Local Roles — Each role is defined by swarmforge/roles/<role>.prompt in the working tree being orchestrated.
• Layered Constitution — swarmforge/constitution.prompt directs agents to read article files under swarmforge/constitution/articles/.
• Backend Selection Per Role — A role can launch claude, codex, copilot, or grok.
• Observable Swarm — Open one Terminal window per role and watch the sessions in real time.
• Self-Hosted & Lightweight — Runs locally in tmux and Terminal with minimal machinery.

Constitution Structure

Each runnable branch contains a swarmforge/ directory with this general layout:

swarmforge/
  swarmforge.conf
  constitution.prompt
  constitution/
    articles/
      project.prompt
      local-engineering.prompt
      local-workflow.prompt
      ...
  roles/
    <role>.prompt
    ...

constitution.prompt is the entry point. Runnable branches normally use it to tell agents to read every file in swarmforge/constitution/articles/.

Shared default articles live on main under:

swarmforge/constitution/articles/
  engineering.prompt
  handoffs.prompt
  workflow.prompt

At startup, SwarmForge installs missing shared articles into the runnable branch’s swarmforge/constitution/articles/ directory before creating role worktrees. It also installs missing shared articles into each role worktree during script synchronization. Existing local files are skipped, so a runnable branch can override a shared article by committing an article with the same filename.

Pack-specific additions and exceptions should use explicit local filenames rather than editing shared articles. Current conventions are:

• project.prompt for the workflow’s project shape and local topology.
• local-engineering.prompt for workflow-specific engineering rules.
• local-workflow.prompt for workflow-specific flow rules.

The local-*.prompt naming convention means “add to or specialize the shared default article for this runnable branch.” Use it when the shared article remains valid and the branch only needs extra requirements, exceptions, or narrower instructions. Do not use local-*.prompt for a full replacement; use the shared filename instead when the branch intentionally overrides the shared article.

For example, main can provide a shared workflow.prompt, while six-pack can add local-workflow.prompt for QA-specific handoff behavior. If a branch needs to replace the shared workflow article completely, it can commit its own workflow.prompt; startup will treat that local file as an override and will not copy the shared one over it.

Roles

Each role in swarmforge/swarmforge.conf maps to a corresponding swarmforge/roles/<role>.prompt file.

How It Works

In a runnable branch:

1. SwarmForge reads swarmforge/swarmforge.conf.
2. The root ./swarm wrapper copies shared helper scripts, terminal adapters, and shared constitution articles from the main branch when they are not already present.
3. Startup installs missing shared constitution articles into swarmforge/constitution/articles/, skipping any local article file that already exists.
4. Startup validates the configured role prompts, helper scripts, and terminal adapters.
5. If the target directory is not already a git repository, startup initializes one and creates the first commit.
6. Startup creates one git worktree per configured role under .worktrees/, unless the role is assigned to master or none.
7. Startup syncs swarmforge/scripts/ and missing shared constitution articles into each role worktree and puts that local scripts directory on each agent’s PATH, so agents use local handoff helpers without reaching back into the master checkout.
8. SwarmForge creates tmux sessions, opens terminal windows, and launches each configured backend in its assigned worktree.
9. Startup starts an OS-specific sleep inhibitor when one is available, and cleanup stops it with the swarm.
10. Roles communicate through daemon-delivered handoff files. Agents create validated drafts with swarm_handoff.sh, accept work with ready_for_next.sh, and complete work with done_with_current.sh.

Handoff Protocol

Startup syncs the shared helper scripts into every role worktree under swarmforge/scripts/ and puts that local directory on the agent’s PATH. Agents do not send tmux messages directly. The launcher starts handoffd.bb, which owns tmux socket access, watches each agent outbox, copies validated handoff files into recipient inboxes, and sends only generic wake-up notifications.

Agents interact with handoffs through three helper scripts:

• swarm_handoff.sh <draft-file> validates and queues outbound handoffs.
• ready_for_next.sh accepts work using the role’s configured receive mode.
• done_with_current.sh completes the current task or batch using the role’s configured receive mode.

Outbound drafts use one of two message types. A git handoff points the recipient at a committed state. The commit abbreviation must be exactly 10 hexadecimal characters; swarm_handoff.sh validates that it resolves to a single commit and canonicalizes it before queuing the handoff.

type: git_handoff
to: <role>[,<role>...]
priority: NN
task: <short-stable-task-name>
commit: <10-character-commit-abbrev>

A note is one short freeform message:

type: note
to: <role>[,<role>...]
priority: NN
message: <one line, max 80 chars>

The helper generates the delivered payload. Agents do not write long handoff bodies, branch names, queue filenames, or tmux commands.

Recipient agents run ready_for_next.sh when notified or after restart. It dispatches to the task or batch helper configured for that role. If it prints NO_TASK, they stop waiting for work. If it prints TASK: <path>, they treat the printed TASK_NAME and PAYLOAD as the task. If it prints BATCH: <path>, they process the printed BATCH_ITEM entries in helper-delivered order. If a wake-up arrives while an agent is already working, it can ignore the wake-up; done_with_current.sh checks for the next task or batch after completing the current work.

The durable handoff files and lifecycle headers replace the old logbook and resend queue. Runtime handoff state lives under .swarmforge/handoffs/ in each worktree, with outbox, sent, failed, and inbox subdirectories. Agents should not hand-edit, merge, stage, or commit handoff runtime state. See swarmforge/handoff-protocol.md for the full protocol.

The swarmforge.conf File

swarmforge/swarmforge.conf defines the swarm window-by-window. Each line has this form:

window <role> <agent> <worktree> [task|batch] [extra-cli-args...]

The optional receive mode defaults to task. Use batch for roles that should consume all currently queued equal-priority handoffs as one batch.

Any fields after the receive mode are passed directly to the agent CLI as additional arguments. If you omit the receive mode, extra arguments may start at the fifth field:

window coder copilot wt-coder --yolo
window architect claude wt-arch task --dangerously-skip-permissions

You can define as many windows as your project needs. Each role maps to a corresponding prompt file at swarmforge/roles/<role>.prompt, so a config containing architect, coder, reviewer, research, and release windows would expect:

• swarmforge/roles/architect.prompt
• swarmforge/roles/coder.prompt
• swarmforge/roles/reviewer.prompt
• swarmforge/roles/research.prompt
• swarmforge/roles/release.prompt

This lets each project choose its own swarm shape instead of being locked to a fixed set of roles.

Example config:

window coordinator codex master
window coder codex coder
window refactorer codex refactorer
window architect codex architect

In the example above, the agents run in these worktrees:

• coordinator -> main working directory on master, and is the cleanup window because it is listed first
• coder -> .worktrees/coder
• refactorer -> .worktrees/refactorer
• architect -> .worktrees/architect

If a window uses master as its worktree name, SwarmForge does not create .worktrees/master; that role runs in the main working directory on the master branch.

tmux Behavior

SwarmForge uses a project-specific tmux socket recorded in .swarmforge/tmux-socket, so each project swarm is isolated from other tmux sessions. It also honors tmux base-index and pane-base-index settings when launching agents and sending notifications, so configurations that number windows or panes from 1 work without requiring users to change their tmux preferences.

Terminal Behavior

SwarmForge opens trackable terminal windows or tabs through a small terminal backend adapter.

Default detection:

• If AppleScript is available, SwarmForge opens macOS Terminal.app windows.
• Otherwise, if wt.exe is available, SwarmForge opens Windows Terminal windows.
• Otherwise, SwarmForge attaches the cleanup tmux session in the current shell.

After copying a runnable branch, set SWARMFORGE_TERMINAL to override detection:

SWARMFORGE_TERMINAL=ghostty ./swarm
SWARMFORGE_TERMINAL=terminal-app ./swarm
SWARMFORGE_TERMINAL=windows-terminal ./swarm
SWARMFORGE_TERMINAL=none ./swarm

Use ghostty when you want SwarmForge to open Ghostty tabs instead of the default Terminal.app windows. Use windows-terminal when you want SwarmForge to open Windows Terminal windows from WSL. Use none when you want SwarmForge to skip terminal automation and attach the cleanup tmux session in the current shell.

Adding A Terminal Backend

The shared terminal backends are carried on main under swarmforge/scripts/terminal-adapters/. Runnable branches copy those scripts at startup. To add a new backend, update main by creating one file named after the backend:

swarmforge/scripts/terminal-adapters/wezterm.sh

The file must define this small contract:

terminal_backend_label() {
  echo "WezTerm"
}

terminal_backend_can_open_sessions() {
  return 0
}

terminal_backend_tracks_windows() {
  return 0
}

terminal_open_session() {
  local session="$1"
  local title="$2"
  local sibling_id="${3:-}"

  # Open a terminal surface that runs:
  # cd "$WORKING_DIR" && exec tmux -S "$TMUX_SOCKET" attach-session -t "$session"
  #
  # Print a stable window/tab id to stdout.
}

terminal_window_exists() {
  local window_id="$1"

  # Return 0 if the id from terminal_open_session still exists.
  # Return nonzero otherwise.
}

terminal_close_window() {
  local window_id="$1"

  # Close the id from terminal_open_session.
}

If the terminal can open sessions but cannot return stable ids for open/check/close, keep terminal_backend_can_open_sessions as return 0 and set terminal_backend_tracks_windows to return 1. SwarmForge will open one surface per session and skip the watchdog for that backend. swarmforge/scripts/terminal-adapters/windows-terminal.sh is an example of this launch-only style.

If the backend cannot open sessions at all, set both capability functions to return 1; SwarmForge will attach the cleanup tmux session in the current shell. Only edit swarmforge/scripts/swarm-terminal-adapter.sh when adding aliases or changing default auto-detection.

Window Behavior

Each visible agent window is attached to a tmux session. That means terminal selection, copy, and paste may follow tmux and terminal-emulator rules rather than ordinary text-field behavior. If copy or paste feels unusual, check whether tmux copy mode is active before assuming the agent is stuck.

The first window in swarmforge.conf is the cleanup window. Closing that top configured window is the intentional shutdown path: SwarmForge tears down the tmux sessions, closes the remaining tracked windows, and shuts down the swarm.

Closing any other tracked window is non-destructive. The watchdog reopens that window and attaches it back to the same tmux session, so the agent state and terminal history remain intact. This is often the simplest way to recover a window that has landed in an unfamiliar tmux mode or otherwise feels stuck.