What Files Are Synchronized Across Worktrees in SwarmForge?

SwarmForge synchronizes repository-wide state files—including .swarmforge/roles.tsv, the .swarmforge/handoffs/ message queue, global configuration files, and role prompts—across all Git worktrees to maintain a consistent multi-agent swarm state.

SwarmForge, authored by Uncle Bob in the unclebob/swarm-forge repository, leverages Git worktrees to isolate individual AI agent roles while maintaining a unified swarm consciousness. The synchronization mechanism relies on specific files that reside outside the worktree-specific directories, ensuring every role shares the same registry, messaging infrastructure, and configuration.

The .swarmforge State Directory

SwarmForge maintains a hidden .swarmforge directory at the repository root. This directory contains the critical state files that remain visible to every worktree, enabling coordination across isolated role environments.

roles.tsv: The Role Registry

The .swarmforge/roles.tsv file serves as the single source of truth for mapping roles to their corresponding worktree paths. This tab-separated file is read by all worktrees to discover peer locations and resolve hand-off destinations.

According to the test suite in script_test.clj (lines 66‑71), the file follows this format:

(write-file (fs/path root ".swarmforge/roles.tsv")
    (str "coder\tmaster\t" root "\tsession\tCoder\tcodex\ttask\n"
         "cleaner\tcleaner\t" root "/.worktrees/cleaner\tsession\tCleaner\tcodex\tbatch\n"))

Each line contains tab-separated fields including the role name, worktree name, absolute path, session type, display name, adapter, and mode. The role-worktree-name function (tested at line 86) queries this file to resolve a role's physical worktree location:

(run {:dir root} (script "handoff_lib.bb") "role-worktree-name" "cleaner")

handoffs/: The Inter-Role Message Queue

The .swarmforge/handoffs/ directory contains inbox/ and outbox/ subdirectories that function as a shared message queue. All worktrees monitor these folders, allowing agents to pass tasks and notes between isolated environments.

As demonstrated in script_test.clj (lines 70‑77), handoff files are written to the shared inbox:

(write-file (fs/path root ".swarmforge/handoffs/inbox/new/item.handoff")
    (str "id: 1\n"
         "from: coder\n"
         "to: cleaner\n"
         "priority: 20\n"
         "type: note\n"
         "\n"
         "payload\n"))

Because this directory resides at the repository root—outside any specific worktree—all roles have concurrent access to the same handoff files, ensuring global visibility of inter-agent communication.

tmux-socket: Shared Session Control

SwarmForge creates a .swarmforge/tmux-socket file that provides the path to a portable tmux server socket. This socket is shared across all worktrees, enabling coordinated terminal sessions and allowing the swarm to manage multiplexed windows for each role from a central server instance.

Global Configuration and Constitution

Beyond state management, SwarmForge synchronizes configuration files that define swarm behavior and personality.

swarmforge.conf

The swarmforge/swarmforge.conf file contains the global SwarmForge configuration, declaring windows, role-specific adapters, and operational modes (master vs. batch). Each worktree parses this file at launch to configure its terminal adapters and determine its execution mode.

Test code in script_test.clj (lines 96‑101) establishes this file before testing:

(write-file (fs/path root "swarmforge/swarmforge.conf") "...")

constitution.prompt

The swarmforge/constitution.prompt file encodes the overall swarm policy and shared system prompts. Every worktree loads this constitution to ensure the LLM driving each role follows consistent rules and stylistic guidelines across the entire swarm.

Role-Specific Prompts

While individual worktrees maintain isolation for code and execution, they share role definitions through synchronized prompt files located at swarmforge/roles/*.prompt. Each file defines the persona and capabilities for a specific role.

When a worktree is created for a role, its corresponding prompt file is referenced from this shared location, ensuring that every instance of a particular role uses identical behavioral definitions.

How File Synchronization Works

SwarmForge utilizes Git worktrees, which share the same .git directory but maintain separate working trees for each branch or role. Files located in the repository root—such as those in .swarmforge/ and swarmforge/—are naturally visible to every worktree because Git worktrees only isolate the checked-out branch content, not the root-level configuration files.

This architecture provides file-level synchronization without requiring a separate synchronization service. Any file written to .swarmforge/handoffs/inbox/ by the coder worktree is immediately visible to the cleaner worktree because both share the same underlying filesystem path for the repository root.

Summary

• .swarmforge/roles.tsv maps every role to its worktree path and is queried by functions like role-worktree-name.
• .swarmforge/handoffs/ provides shared inbox/ and outbox/ directories for inter-role messaging.
• .swarmforge/tmux-socket enables coordinated terminal sessions across all worktrees.
• swarmforge/swarmforge.conf supplies global configuration read by every worktree at startup.
• swarmforge/constitution.prompt and swarmforge/roles/*.prompt synchronize swarm policy and role definitions.
• Synchronization occurs at the filesystem level because these files reside in the shared repository root outside worktree-specific directories.

Frequently Asked Questions

Where does SwarmForge store the mapping between roles and worktrees?

SwarmForge stores this mapping in .swarmforge/roles.tsv, a tab-separated file at the repository root. Each line contains the role name, worktree identifier, absolute path, and operational metadata, allowing any worktree to locate peers using the role-worktree-name function.

How do agents pass messages between isolated worktrees?

Agents communicate through the .swarmforge/handoffs/ directory structure, specifically the inbox/ and outbox/ subfolders. Because these directories exist at the repository root, all worktrees share the same physical handoff files, enabling asynchronous message passing between roles.

Are configuration files shared or isolated per worktree?

Configuration files are shared. The swarmforge/swarmforge.conf and swarmforge/constitution.prompt files reside in the repository root and are parsed by every worktree during initialization, ensuring consistent adapter settings and behavioral policies across the swarm.

What coordinates terminal sessions across multiple worktrees?

The .swarmforge/tmux-socket file provides the connection point to a shared tmux server. All worktrees reference this socket to attach to coordinated terminal sessions, allowing SwarmForge to manage multiplexed windows for each role from a central control point.

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