# What Files Are Synchronized Across Worktrees in SwarmForge?

> Discover which files SwarmForge synchronizes across worktrees, including roles.tsv, handoffs, and global configs, ensuring consistent multi-agent swarm state. Learn more now.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: internals
- Published: 2026-08-09

---

**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:

```clojure
(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:

```clojure
(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:

```clojure
(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`](https://github.com/unclebob/swarm-forge/blob/main/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:

```clojure
(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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.