swarm-forge

Product Introduction

1. Definition: Swarm-Forge is a local, tmux-based AI agent orchestration platform and coordination tool designed for software development. It falls under the technical categories of AI workflow automation, multi-agent systems, and developer tooling.
2. Core Value Proposition: It solves the problem of fragmented AI-assisted development by enabling multiple specialized AI agents (like coders, architects, and QA specialists) to collaborate cohesively on multi-step software projects. Its core value is turning a group of individual AI models into a unified, disciplined, and observable software engineering swarm.

Main Features

1. Config-Driven Swarm Topology: The system's shape is defined by a simple swarmforge.conf file, not hardcoded scripts. Each line defines a role (e.g., coder), its AI backend (e.g., claude, copilot), its dedicated git worktree, and its task-handling mode (task or batch). This allows projects to customize their agent team composition dynamically.
2. Git Worktree Isolation & Layered Constitution: Each agent role operates in its own isolated git worktree under .worktrees/, preventing conflicts. Behavior is governed by a layered prompt system: project-specific swarmforge/roles/<role>.prompt files are combined with a shared, branchable constitution.prompt and its articles (e.g., engineering.prompt, workflow.prompt), ensuring consistent rules across the swarm.
3. Structured Handoff Protocol with Daemon: Agents communicate not through direct API calls but via a file-based handoff protocol managed by a Babashka daemon (handoffd.bb). Agents use helper scripts (swarm_handoff.sh, ready_for_next.sh) to send and receive validated handoffs (either git_handoff pointing to a specific commit or a note). This creates a durable, observable, and restart-safe workflow state under .swarmforge/handoffs/.

Problems Solved

1. Pain Point: It addresses the inefficiency and context loss when developers manually shuttle tasks between different AI models (e.g., from a spec-writing model to a coding model to a refactoring model). It eliminates the "copy-paste" workflow, ensuring agents share full project context and history.
2. Target Audience: The primary user personas are senior software developers, engineering leads, and technical teams who are already leveraging AI coding assistants but need to scale beyond single-agent, single-turn interactions to manage complex, multi-stage development projects.
3. Use Cases: Essential for scenarios like implementing a new feature from a vague requirement (using the specifier -> coder -> refactorer flow), conducting a large-scale codebase refactoring with architectural oversight, or maintaining disciplined TDD and QA processes across an AI-assisted development cycle.

Unique Advantages

1. Differentiation: Unlike monolithic AI coding platforms or simple chat interfaces, Swarm-Forge is a lightweight, local, and open-source orchestration layer. It does not replace AI models but coordinates existing ones (Claude, GPT, Copilot) into a defined process. It contrasts with cloud-based agent platforms by offering full transparency, local execution, and no vendor lock-in.
2. Key Innovation: Its core innovation is the "software engineering swarm" metaphor implemented with battle-tested Unix tools (tmux, git worktree, zsh). The combination of isolated git worktrees, a file-based handoff protocol with a daemon, and a layered constitutional prompt system creates a robust, observable, and restartable multi-agent system without complex infrastructure.

Frequently Asked Questions (FAQ)

1. What is Swarm-Forge used for? Swarm-Forge is used for orchestrating multiple AI agents to collaborate on software development projects, automating workflows from specification and coding to refactoring, architecture review, and quality assurance in a structured, observable manner.
2. How does Swarm-Forge handle communication between AI agents? It uses a file-based handoff protocol where a local daemon manages message queues. Agents create validated handoff files (like git commits or notes) which the daemon delivers to recipient agents' inboxes, ensuring reliable, context-preserving communication without direct agent-to-agent calls.
3. Can I use Swarm-Forge with any AI model? Yes, Swarm-Forge supports configurable backends per role. It currently works with AI assistants that have a command-line interface, such as Claude via claude, OpenAI's models via codex, GitHub Copilot, and Grok, allowing you to mix and match models within a single swarm.
4. Is Swarm-Forge a cloud service or a local tool? Swarm-Forge is a purely local tool that runs on your machine using tmux and git. All state, including worktrees, handoff files, and configuration, is stored locally in your project directory, ensuring privacy and full control over the development environment.
5. What are the differences between the two-pack, four-pack, and six-pack branches? These are pre-configured workflow branches. two-pack is for quick coding/refactoring loops. four-pack adds specification and architecture roles for more disciplined projects. six-pack is the full workflow with separate agents for specification, coding, cleaning, architecture, hardening, and QA, offering the highest level of process separation and quality gates.