Manage AI agents in isolated workspaces with a handoff protocol
Imagine multiple AI agents writing code, cleaning it up, and reviewing architecture in their own terminals, passing results to one another. SwarmForge isolates agents using git worktrees and tmux sessions, enabling collaboration through a handoff protocol based on committed work. Operators manage the process via a local dashboard, handling task initiation, agent status checks, approvals, questions, and swarm shutdown.
Pack and Forge: Installation Differences
SwarmForge offers two modes: 'pack' for adding an agent team to an existing project, and 'forge' for creating a new structure in an empty directory. Packs are templates composed of 2, 4, or 6 roles, each corresponding to specific jobs such as coder, cleaner, spec-fier, refacturer, or architect. Forge sets up an environment capable of managing multiple projects simultaneously, including high-level command agents like project managers or lieutenants. Installation is handled via the get-swarm-forge helper, which combines necessary files from multiple branches to apply them to the current project.
Isolated Worktrees and Sustainable Handoffs
Agents run in isolated git worktrees to prevent interference with each other's work. Upon completing a task, each agent passes results to the next agent using scripts like swarm_handoff.sh. This process follows a sustainable handoff protocol based on committed work, rather than simple file transfer. Operators can check agent status, handle approval gates, and ask questions if further explanation is needed via the local dashboard. This structure allows agents to work independently while maintaining overall project consistency.
Shared Constitution and Role-Specific Prompts
SwarmForge defines common rules that all agents must follow as a 'shared constitution.' This constitution includes engineering standards, workflow discipline, and handoff protocols, and is managed in the main branch. Product branches cannot override these shared rules; project-specific details can only be added via local-*.prompt files. Role-specific prompts clearly define what each agent can modify, what they must verify, and where the next handoff target is. This configuration helps agents perform their roles without confusion and maintain consistent project quality standards.
Pre-Execution Requirements and Cautions
To run SwarmForge, zsh, git, tmux, and Babashka (bb) must be installed, and at least one agent backend from grok, codex, claude, or copilot must be configured. Installation begins by adding the get-swarm-forge helper to the PATH, which downloads and combines files from multiple branches. Note that the main branch is not a runnable product but contains installation sources, shared runtime, and engineering laws. Agents must not directly edit the runtime state created in the .swarmforge/ directory; they should only perform tasks through provided helper commands. Specific experimental workflows in the squad, sprint-module-squad, and adversaries branches are not provided as part of the get-swarm-forge product, so avoid confusing them with the official product.
