# SwarmForge Handoff Protocol Helper Scripts: A Complete Guide to File-Based Workflow Automation > Automate file-based workflows with SwarmForge handoff protocol helper scripts. Manage .handoff files between tmux roles efficiently. A complete guide to this powerful utility. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-09 --- **SwarmForge handoff protocol helper scripts** are Bash and Babashka utilities located in `swarmforge/scripts/` that manage the creation, delivery, and lifecycle of `.handoff` files between tmux-based roles. The `unclebob/swarm-forge` repository implements a lightweight, file-based coordination mechanism through its **SwarmForge handoff protocol helper scripts**. These utilities enable seamless task transfer between different roles (such as `builder` and `tester`) in a tmux-driven development environment. Located in the `swarmforge/scripts` directory, the scripts handle everything from sequence number generation to daemon-based delivery and workflow state transitions. ## Core Helper Scripts for Handoff Management ### handoff_lib.bb – The Foundation Library The `handoff_lib.bb` file serves as the core library for the entire handoff system. It provides essential functions for generating unique sequence numbers, reading and writing handoff headers, and printing task or batch information. All other scripts in the `swarmforge/scripts` directory depend on this library to maintain consistent file formats and metadata structure. ### handoffd.bb – The Delivery Daemon The `handoffd.bb` script runs as a background daemon that monitors each role's *outbox* directory for pending handoffs. When it detects a new `.handoff` file, it adds delivery metadata (including `enqueued_at` and `recipient` timestamps), moves the file to the recipient's *inbox*, and sends a notification to the appropriate tmux session. This automates the transfer process without requiring manual file manipulation. ### swarm_handoff.bb – Creating Handoffs The `swarm_handoff.bb` script (invoked through the [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) wrapper) generates new handoff files in the sender's *outbox*. It utilizes `handoff_lib.bb` to ensure proper header formatting and sequence numbering before the daemon processes the delivery. ## Daemon Control and Workflow Utilities ### Stopping the Daemon To gracefully terminate the background delivery process, use [`stop_handoff_daemon.sh`](https://github.com/unclebob/swarm-forge/blob/main/stop_handoff_daemon.sh) or its Babashka counterpart `stop_handoff_daemon.bb`. These scripts ensure the `handoffd` process shuts down cleanly without leaving orphaned handoff files in transit. ### User Workflow Helpers A suite of convenience scripts assists users in managing handoff state transitions: - **[`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh)** and **`ready_for_next.bb`**: Move handoff files to signal readiness for the next workflow step - **[`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh)** / **`ready_for_next_task.bb`**: Specifically handle task-level readiness signals - **[`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh)** / **`ready_for_next_batch.bb`**: Handle batch-level transitions - **[`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh)** and **`done_with_current.bb`**: Mark current handoffs as completed - **[`done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_task.sh)** / **`done_with_current_task.bb`**: Complete individual tasks - **[`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh)** / **`done_with_current_batch.bb`**: Complete entire batches These utilities relocate `.handoff` files between the *new*, *inbox*, *outbox*, and *sent* directories according to the protocol defined in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). ## The Handoff Lifecycle in Practice Creating a handoff from the `builder` role to the `tester` role requires specifying the source, destination, type, and priority: ```bash # In the builder's worktree SWARMFORGE_ROLE=builder ./swarmforge/scripts/swarm_handoff.sh \ --from builder \ --to tester \ --type task \ --priority 10 \ --task "build-image" \ --message "Image built successfully" ``` This command internally calls `handoff_lib.bb` to write a properly formatted `.handoff` file into the `outbox/` directory. To run the delivery daemon manually (normally started automatically by SwarmForge): ```bash # From the project root ./swarmforge/scripts/handoffd.bb /path/to/project ``` The daemon continuously polls *outbox* directories, delivers pending handoffs to recipient inboxes, and triggers tmux notifications. When you are ready to process the next item: ```bash ./swarmforge/scripts/ready_for_next_task.sh ``` This moves the `.handoff` file from `inbox/new/` to `inbox/ready/` so the recipient can pick it up. Upon completion: ```bash ./swarmforge/scripts/done_with_current_task.sh ``` This relocates the handoff to the `sent/` directory and cleans up temporary state files. ## Summary - **SwarmForge handoff protocol helper scripts** reside in `swarmforge/scripts/` and implement a complete file-based workflow system using Bash and Babashka - The **`handoff_lib.bb`** library provides core functionality for sequence generation and header management used by all other scripts - **`handoffd.bb`** operates as a background daemon that automates delivery from outbox to inbox while notifying tmux sessions - **`swarm_handoff.bb`** (via [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh)) creates properly formatted handoff files with metadata and priorities - Workflow helpers like **`ready_for_next*.sh`** and **`done_with_current*.sh`** manage state transitions between *new*, *inbox*, *outbox*, and *sent* directories - The protocol is documented in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) and integrates tightly with SwarmForge's tmux-driven architecture ## Frequently Asked Questions ### What is the purpose of the handoffd.bb daemon in SwarmForge? The `handoffd.bb` daemon automates the delivery phase of the handoff protocol by monitoring outbox directories for new `.handoff` files. It adds delivery metadata including timestamps and recipient information, moves files to the appropriate inbox, and sends notifications to the recipient's tmux session to alert them of pending work. ### How do I create a handoff between two roles using the helper scripts? Use the [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) wrapper (which invokes `swarm_handoff.bb`) with parameters specifying `--from`, `--to`, `--type`, `--priority`, and `--task`. This generates a properly sequenced `.handoff` file in the sender's outbox, which the daemon then delivers to the recipient's inbox according to the handoff protocol. ### What is the difference between ready_for_next and done_with_current scripts? The `ready_for_next` scripts (including task and batch variants) signal that a handoff is ready to be processed by moving files from `inbox/new/` to `inbox/ready/`. The `done_with_current` scripts mark work as completed by relocating handoffs to the `sent/` directory and removing temporary state, effectively closing out that workflow item. ### Where are the SwarmForge handoff protocol helper scripts located in the repository? All helper scripts are located in the `swarmforge/scripts/` directory of the `unclebob/swarm-forge` repository. This includes the core library (`handoff_lib.bb`), the daemon (`handoffd.bb`), creation utilities (`swarm_handoff.bb`), control scripts ([`stop_handoff_daemon.sh`](https://github.com/unclebob/swarm-forge/blob/main/stop_handoff_daemon.sh)), and workflow helpers (`ready_for_next*.sh`, `done_with_current*.sh`).