# What Are the Core Components of SwarmForge Architecture?

> Discover the 8 core components of SwarmForge architecture. Learn how this system creates a disciplined AI agent software-engineering pipeline, transforming AI into effective tools.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: architecture
- Published: 2026-08-09

---

**SwarmForge architecture consists of eight tightly-coupled components—configuration-driven topology, layered constitution, role-specific prompts, durable handoff protocol, helper scripts, terminal adapters, Babashka daemon, and tmux integration—that transform AI agents into a disciplined software-engineering pipeline.**

SwarmForge, developed in the `unclebob/swarm-forge` repository, is a lightweight, tmux-based orchestration layer that coordinates AI agents into a structured software engineering workflow. Understanding the core components of SwarmForge architecture reveals how it maintains state isolation, enforces role boundaries, and ensures reliable inter-agent communication without direct coupling.

## Swarm Configuration (swarmforge.conf)

The foundation of every SwarmForge deployment is **[`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)**, a declarative topology file that maps tmux windows to agent backends, git worktrees, and receive modes.

Each line in the configuration defines a **window** (role) using the syntax: `window <name> <backend> <worktree> [mode]`. The mode determines whether the role consumes work as discrete **task** handoffs or aggregated **batch** handoffs. When SwarmForge initializes, it parses this file to create isolated tmux sessions, provision worktrees under `.worktrees/`, and inject role-specific environment variables.

```conf

# swarmforge/swarmforge.conf

window coordinator codex master
window coder codex coder
window cleaner codex cleaner

```

The first window listed serves as the **cleanup coordinator**; closing this window triggers graceful shutdown of the entire swarm.

## Constitution and Role Prompts

SwarmForge implements a **layered constitution system** that agents read to understand workflow policies, engineering standards, and handoff protocols.

The entry point **`swarmforge/constitution.prompt`** sources shared articles from **`swarmforge/constitution/articles/`**, including `engineering.prompt`, `handoffs.prompt`, and `workflow.prompt`. These defaults live in the main branch and are copied into runnable worktrees at startup. Role-specific instructions reside in **`swarmforge/roles/<role>.prompt`**, which the configuration file maps to each window. This separation ensures shared governance rules remain consistent while allowing specialized behaviors per agent.

## Durable Handoff Protocol

Inter-agent communication relies on a **file-based handoff protocol** specified in **[`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md)**, eliminating fragile direct tmux commands between windows.

Agents create handoff drafts containing headers like `type`, `to`, `priority`, and `task`. The **[`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh)** script validates these drafts, adds required metadata, and enqueues them to the sender’s `outbox/`. A Babashka daemon, **`handoffd.bb`**, watches all outbox directories, validates handoffs against protocol rules, and atomically delivers them to recipient inboxes. The daemon also sends lightweight tmux wake-up signals to notify waiting agents without blocking the sender.

```sh

# Draft and enqueue a git handoff

cat > tmp/handoff.txt <<'EOF'
type: git_handoff
to: cleaner
priority: 30
task: add-feature-X
commit: a1b2c3d9e8
EOF

swarm_handoff.sh tmp/handoff.txt

```

## Helper Scripts for Agent Coordination

SwarmForge provides idempotent shell scripts in **`swarmforge/scripts/`** that abstract queue operations:

- **[`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh)** – Validates outbound drafts and moves them to `outbox/`
- **[`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh)** (and variants [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh), [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh)) – Atomically pulls the highest-priority handoff from the inbox to `inbox/in_process/` and prints the payload
- **[`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh)** (and variants [`done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_task.sh), [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh)) – Marks the current work as completed and triggers the next pull

```sh

# Inside the cleaner worktree

ready_for_next.sh   # prints TASK: <path> … or NO_TASK

# After processing

done_with_current.sh

```

These scripts ensure exactly-once processing semantics and prevent race conditions during handoff consumption.

## Terminal Adapters

To abstract OS-specific terminal launching, SwarmForge uses **terminal adapters** located in **`swarmforge/scripts/terminal-adapters/`**.

Built-in adapters support macOS Terminal, iTerm2, Ghostty, Windows Terminal, and a headless `none` fallback. Each adapter implements a minimal contract: accept a tmux socket path and window name, then launch the appropriate terminal surface. Adding a new backend requires only creating a new script (e.g., [`wezterm.sh`](https://github.com/unclebob/swarm-forge/blob/main/wezterm.sh)) that adheres to this interface; SwarmForge detects it automatically via the `SWARMFORGE_TERMINAL` environment variable.

## Worktree and State Management

SwarmForge enforces strict isolation through **git worktrees** and a dedicated runtime directory.

Upon startup, the system creates a git worktree per role under **`.worktrees/`** (unless the role specifies `master` as its worktree). All runtime state—including handoff queues (`outbox/`, `inbox/`, `in_process/`), daemon PID files, and logs—resides under **`.swarmforge/`** at the repository root. This architecture keeps each agent’s working directory isolated while maintaining atomic access to shared handoff queues through the filesystem.

## Tmux Integration Layer

The orchestration layer binds everything together through **project-specific tmux sockets**.

SwarmForge creates a unique socket at **`.swarmforge/tmux-socket`**, ensuring complete isolation from other tmux sessions on the host. The daemon and helper scripts communicate via this socket to spawn windows, send keys, and trigger notifications. This design provides real-time observability; developers can attach to the socket and watch the swarm operate as a disciplined engineering team with visible window-per-role segmentation.

## Summary

- **[`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)** drives the entire topology, mapping windows to backends and worktrees with task or batch receive modes.
- The **constitution system** layers shared governance articles with role-specific prompts to standardize agent behavior.
- The **handoff protocol** replaces direct inter-agent communication with durable, file-based queues managed by `handoffd.bb`.
- **Helper scripts** provide atomic, race-free primitives for enqueuing, fetching, and completing work.
- **Terminal adapters** abstract platform-specific UI launching through a simple script-based contract.
- **Worktree isolation** and **`.swarmforge/` state management** ensure agents operate in isolated environments while sharing repository context.
- **Tmux integration** via project-specific sockets provides both isolation and observability for the running swarm.

## Frequently Asked Questions

### How does SwarmForge prevent agents from interfering with each other?

SwarmForge isolates agents through git worktrees (each role gets its own directory under `.worktrees/`) and project-specific tmux sockets (`.swarmforge/tmux-socket`). The handoff protocol enforces asynchronous communication via inbox/outbox queues rather than direct process interaction, ensuring agents can only influence each other through validated, file-based messages processed by the `handoffd.bb` daemon.

### What file format does the handoff protocol use?

According to [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md), handoffs are text files with YAML-like headers specifying `type`, `to`, `from`, `priority`, and payload fields such as `task` or `commit`. The [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) script validates these drafts against the protocol schema before the daemon routes them to recipient inboxes, ensuring type safety and delivery guarantees.

### How do I add support for a new terminal emulator?

Create a new executable script in `swarmforge/scripts/terminal-adapters/` named after the emulator (e.g., [`wezterm.sh`](https://github.com/unclebob/swarm-forge/blob/main/wezterm.sh)). The script must accept the tmux socket path and target window name as arguments and launch the terminal attached to that session. After committing the script, set `SWARMFORGE_TERMINAL=wezterm` before launching the swarm; SwarmForge automatically detects and invokes the adapter.

### Where does SwarmForge store handoff queues and runtime data?

All transient state lives under the `.swarmforge/` directory at the repository root, including the tmux socket, daemon PID files, and per-role queue directories (`outbox/`, `inbox/`, `in_process/`). Persistent agent working directories are maintained as git worktrees under `.worktrees/`, keeping runtime metadata separate from source code while maintaining atomic filesystem operations for queue management.