# unclebob/swarm-forge architecture

> Architecture diagram of the GitHub repository unclebob/swarm-forge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unclebob/swarm-forge
- Repository: https://github.com/unclebob/swarm-forge
- Video tour (about a minute): https://gitdiagram.com/unclebob/swarm-forge/video

## Overview

SwarmForge’s main branch supplies a shared runtime and installer-composition source, not a standalone runnable product. Its central workflow is to compose a product, launch configured agent roles in worktrees and tmux, then exchange and complete durable handoffs; the dashboard supports operator oversight. The README documents responsibilities and broad runtime behavior, but no source excerpts were supplied, so internal call wiring and dashboard-to-command links are intentionally limited.

Main entry points: [`swarmforge/scripts/swarmforge.bb`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.bb) (Runtime launcher), [`get-swarm-forge`](https://github.com/unclebob/swarm-forge/blob/main/get-swarm-forge) (Product composer), [`swarmforge/scripts/pack/dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html) (Local dashboard), [`swarmforge/scripts/pack_web.bb`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_web.bb) (Dashboard server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_composition["Product composition"]
  node_composer["Product composer"]
end

subgraph group_runtime["Agent runtime"]
  node_config["Runtime config<br/>[swarmforge.conf]"]
  node_launcher["Runtime launcher<br/>[swarmforge.bb]"]
  node_terminal["Terminal adapters"]
end

subgraph group_handoffs["Handoff lifecycle"]
  node_handoff["Handoff commands<br/>[swarm_handoff.bb]"]
  node_handoffd["Handoff delivery<br/>[handoffd.bb]"]
  node_ready["Ready checks<br/>[ready_for_next.bb]"]
  node_complete["Work completion"]
  node_merge["Merge processing"]
end

subgraph group_operator["Operator controls"]
  node_dashboard["Local dashboard<br/>[dashboard.html]"]
  node_dashboard_api["Dashboard requests"]
  node_web["Dashboard server<br/>[pack_web.bb]"]
  node_board["Board view<br/>[pack_board.bb]"]
end

subgraph group_guidance["Shared guidance"]
  node_protocol["Handoff protocol"]
  node_constitution["Shared agent rules"]
end

node_operator(("Operator"))
node_agent(("AI agent"))
node_backend{{"Agent backend"}}
node_git{{"Git"}}
node_tmux{{"tmux"}}

node_operator -->|"selects product"| node_composer
node_composer -->|"composes files"| node_config
node_operator -->|"starts swarm"| node_launcher
node_launcher -->|"parses configuration"| node_config
node_launcher -->|"creates worktrees"| node_git
node_launcher -->|"creates sessions"| node_tmux
node_launcher -->|"launches agents"| node_backend
node_launcher -->|"selects adapter"| node_terminal
node_agent -->|"sends work"| node_handoff
node_handoffd -->|"delivers handoffs"| node_agent
node_ready -->|"checks readiness"| node_agent
node_complete -->|"completes work"| node_agent
node_merge -->|"merges work"| node_git
node_operator -->|"oversees swarm"| node_dashboard
node_dashboard -->|"uses dashboard"| node_web
node_web -->|"handles requests"| node_dashboard_api
node_operator -->|"inspects board"| node_board
node_agent -->|"reads guidance"| node_constitution
node_agent -->|"follows protocol"| node_protocol

click node_composer "https://github.com/unclebob/swarm-forge/blob/main/get-swarm-forge"
click node_config "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf"
click node_launcher "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.bb"
click node_terminal "https://github.com/unclebob/swarm-forge/tree/main/swarmforge/scripts/terminal-adapters"
click node_handoff "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.bb"
click node_handoffd "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/handoffd.bb"
click node_ready "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next.bb"
click node_complete "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/done_with_current.bb"
click node_merge "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/merge_and_process.bb"
click node_dashboard "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html"
click node_dashboard_api "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_dashboard_request.bb"
click node_web "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_web.bb"
click node_board "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_board.bb"
click node_protocol "https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md"
click node_constitution "https://github.com/unclebob/swarm-forge/tree/main/swarmforge/constitution/articles"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_composer toneBlue
class node_config,node_launcher,node_terminal toneAmber
class node_handoff,node_handoffd,node_ready,node_complete,node_merge toneMint
class node_dashboard,node_dashboard_api,node_web,node_board toneRose
class node_protocol,node_constitution,node_operator,node_agent,node_backend,node_git,node_tmux toneIndigo
```

## Components

### Product composition

- [Product composer](https://github.com/unclebob/swarm-forge/blob/main/get-swarm-forge): `get-swarm-forge`

### Agent runtime

- [Runtime config](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf): `swarmforge/swarmforge.conf`
- [Runtime launcher](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.bb): `swarmforge/scripts/swarmforge.bb`
- [Terminal adapters](https://github.com/unclebob/swarm-forge/tree/main/swarmforge/scripts/terminal-adapters): `swarmforge/scripts/terminal-adapters`

### Handoff lifecycle

- [Handoff commands](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.bb): `swarmforge/scripts/swarm_handoff.bb`
- [Handoff delivery](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/handoffd.bb): `swarmforge/scripts/handoffd.bb`
- [Ready checks](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next.bb): `swarmforge/scripts/ready_for_next.bb`
- [Work completion](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/done_with_current.bb): `swarmforge/scripts/done_with_current.bb`
- [Merge processing](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/merge_and_process.bb): `swarmforge/scripts/merge_and_process.bb`

### Operator controls

- [Local dashboard](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html): `swarmforge/scripts/pack/dashboard.html`
- [Dashboard requests](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_dashboard_request.bb): `swarmforge/scripts/pack_dashboard_request.bb`
- [Dashboard server](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_web.bb): `swarmforge/scripts/pack_web.bb`
- [Board view](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_board.bb): `swarmforge/scripts/pack_board.bb`

### Shared guidance

- [Handoff protocol](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md): `swarmforge/handoff-protocol.md`
- [Shared agent rules](https://github.com/unclebob/swarm-forge/tree/main/swarmforge/constitution/articles): `swarmforge/constitution/articles`

### Other components

- **Operator**
- **AI agent**
- **Agent backend**
- **Git**
- **tmux**

## Connections

- Operator → Product composer: selects product
- Product composer → Runtime config: composes files
- Operator → Runtime launcher: starts swarm
- Runtime launcher → Runtime config: parses configuration
- Runtime launcher → Git: creates worktrees
- Runtime launcher → tmux: creates sessions
- Runtime launcher → Agent backend: launches agents
- Runtime launcher → Terminal adapters: selects adapter
- AI agent → Handoff commands: sends work
- Handoff delivery → AI agent: delivers handoffs
- Ready checks → AI agent: checks readiness
- Work completion → AI agent: completes work
- Merge processing → Git: merges work
- Operator → Local dashboard: oversees swarm
- Local dashboard → Dashboard server: uses dashboard
- Dashboard server → Dashboard requests: handles requests
- Operator → Board view: inspects board
- AI agent → Shared agent rules: reads guidance
- AI agent → Handoff protocol: follows protocol