What Are the Core Components of SwarmForge Architecture?

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, 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.

# 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, eliminating fragile direct tmux commands between windows.

Agents create handoff drafts containing headers like type, to, priority, and task. The 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.

# 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 – Validates outbound drafts and moves them to outbox/
• ready_for_next.sh (and variants ready_for_next_task.sh, 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 (and variants done_with_current_task.sh, done_with_current_batch.sh) – Marks the current work as completed and triggers the next pull

# 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) 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 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, 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 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}