What Are the Core Components of the SwarmForge Architecture?

The SwarmForge architecture consists of four core components: the Core Engine, the Handoff Daemon and Protocol, Role Prompts and Constitution files, and Terminal Adapter scripts.

SwarmForge is a collaborative AI framework hosted at unclebob/swarm-forge that orchestrates multiple AI agents to work on software projects simultaneously. The system relies on a modular architecture where specialized components handle orchestration, task routing, behavior definition, and terminal abstraction. Understanding these core components helps developers customize workflows and troubleshoot the swarm effectively.

SwarmForge Core Engine

The Core Engine serves as the central orchestrator and entry point for every SwarmForge project. Implemented in swarmforge/scripts/swarmforge.sh (with a Bytecode equivalent swarmforge.bb), this component initializes the entire system.

The engine performs three critical functions at startup:

• Reads the swarmforge/swarmforge.conf configuration file to determine which adapters, roles, and repository settings to load
• Launches the Handoff Daemon (handoffd.bb) to manage the task queue
• Dispatches cards to appropriate role agents based on the current pipeline state

When you execute ./get-swarm-forge in a project directory, you invoke this engine. The script then coordinates all subsequent operations, acting as the single source of truth for swarm lifecycle management.

Handoff Daemon and Protocol

The Handoff Daemon implements the workflow engine that moves tasks through the AI agent pipeline. Found in swarmforge/scripts/handoffd.bb with supporting logic in handoff_lib.bb, this component maintains the state machine governing card progression.

The daemon manages work through a strict pipeline: Specifier → Coder → Refactorer → Architect → Done. It exposes a REST API (documented in swarmforge/handoff-protocol.md) that agents poll for new cards and use to submit results.

Key responsibilities include:

• Maintaining a persistent queue of work items with metadata
• Handling role transitions and state persistence
• Creating merge-only copies for earlier roles when necessary
• Managing concurrent access from multiple AI agents

You rarely interact with the daemon directly, though you can manually submit cards for debugging:

# Start the daemon in background

swarmforge/scripts/handoffd.bb &

# Submit a new card to the queue

echo '{"title":"Add login UI","description":"Create a login page"}' |
  curl -X POST -d @- http://localhost:5000/cards

Role Prompts and Constitution

Role Prompts define the behavioral specifications for each AI agent in the swarm. Located in swarmforge/roles/ (e.g., lieutenant.prompt) and swarmforge/constitution/articles/ (e.g., handoffs.prompt, engineering.prompt, workflow.prompt), these files contain the system prompts that shape agent capabilities.

Each prompt file encodes:

• The specific responsibilities of a role (e.g., Coder implements features, Architect reviews design)
• Shared conventions and constraints the swarm must follow
• Output formats and communication protocols for handoffs

When the Handoff Daemon assigns a card to a specific role, the Core Engine spawns a language model process loaded with the corresponding prompt file. This ensures consistent behavior across sessions while allowing granular customization of agent capabilities without modifying executable code.

Terminal Adapter Scripts

The Terminal Adapter layer abstracts host terminal interactions to provide consistent user experience across different environments. These scripts reside in swarmforge/scripts/terminal-adapters/ and include implementations for iTerm2, Windows Terminal, Ghostty, and generic terminals.

Adapters handle:

• Display rendering for progress updates and agent status
• User input collection when human intervention is required
• Cleanup procedures when the swarm terminates or encounters errors

Switching adapters requires only an environment variable change:

# Force iTerm2 adapter instead of generic terminal

export SWARM_TERMINAL_ADAPTER=iterm2
./get-swarm-forge

This abstraction allows SwarmForge to run on diverse development environments without modifying core orchestration logic.

How the Components Work Together

The four components form a closed-loop system that processes software development tasks iteratively:

1. Configuration Phase: The Core Engine reads swarmforge.conf to establish runtime parameters, available roles, and terminal preferences.

2. Initialization: The engine launches the Handoff Daemon, which initializes the card queue and prepares the role pipeline.

3. Execution Loop: For each card in the queue, the daemon selects the appropriate Role Prompt and spawns an AI agent within the configured Terminal Adapter.

4. Completion and Routing: The agent returns output to the daemon, which updates the card state and moves it to the next role (or to Done if complete).

5. Iteration: The process repeats until all cards reach terminal states.

This architecture decouples the workflow engine from specific AI models and terminal types, enabling developers to swap components—such as replacing the handoff protocol or using a custom terminal adapter—without disrupting the entire system.

Summary

• Core Engine (swarmforge.sh): Central orchestrator that reads configuration and initializes the swarm.
• Handoff Daemon (handoffd.bb): Manages the task queue and implements the role pipeline (Specifier → Coder → Refactorer → Architect → Done).
• Role Prompts (*.prompt files): Define AI agent behavior and system constraints for each specialized role.
• Terminal Adapters (terminal-adapters/*.sh): Abstract display and input handling across different terminal emulators.

Frequently Asked Questions

How does SwarmForge handle task persistence between sessions?

The Handoff Daemon maintains the task queue in a stateful manner, storing card metadata and progress through the role pipeline. When the Core Engine restarts, it reconnects to the existing daemon instance (or spawns a new one that reads persisted state), allowing work to continue across terminal sessions or system restarts without losing context.

Can I replace the default Handoff Protocol with a custom implementation?

Yes. Because the architecture isolates protocol logic within handoff_lib.bb and handoff-protocol.md, you can modify the card lifecycle, add new roles, or change the state machine without affecting the Core Engine or Role Prompts. The daemon exposes a REST API that any compliant implementation can satisfy.

What determines which AI model executes a specific role?

The Role Prompt files (lieutenant.prompt, handoffs.prompt, etc.) define the behavior, but the actual model selection depends on the Core Engine's configuration in swarmforge.conf. The engine spawns the language model process specified in your configuration, loads the appropriate prompt file, and connects it to the Terminal Adapter for I/O handling.

Is it possible to run SwarmForge without the Terminal Adapter layer?

While the Terminal Adapter provides the standard interface for human interaction, the Core Engine and Handoff Daemon function independently. You can operate SwarmForge in headless mode by configuring a null adapter or by interacting directly with the daemon's REST API at localhost:5000, though this requires manual handling of agent output and queue management.

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