# How Does Batch Receive Mode in SwarmForge Process Multiple Queued Handoffs? > Learn how SwarmForge batch receive mode processes queued handoffs. It aggregates, merges payloads, and processes them as a single task for atomic receiving. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-31 --- **Batch receive mode in SwarmForge aggregates handoffs sharing the same priority into a unique batch directory, merges any git payloads, and emits them as a single logical task for atomic processing by the receiving role.** SwarmForge, an open-source workflow orchestration system from the `unclebob/swarm-forge` repository, supports two distinct work reception strategies: individual task processing and batch processing. When a role is declared with **batch receive mode** in the configuration, the system groups pending handoffs from the inbox queue and processes them as a coordinated unit rather than isolated tasks. ## Configuration and Validation of Receive Modes The `swarmforge/scripts/swarmforge.bb` file handles configuration parsing through the `receive-fields` function (lines 49-58). When parsing a role definition, the parser extracts the token following the worktree name. If this token is `batch`, the system configures the role for batch processing; otherwise, it defaults to `task` mode. During the validation phase, the `validate-window!` function (lines 78-80) enforces that only `task` or `batch` are valid values for `receive-mode`. Any other value triggers a validation error, ensuring strict type safety for the reception behavior. ## Gathering and Prioritizing Queued Handoffs The core batch processing logic resides in `swarmforge/scripts/ready_for_next_batch.bb`. First, the script scans the `.swarmforge/handoffs/inbox/new` directory using the `handoff-files` helper to collect all `*.handoff` files waiting in the queue. Next, the system groups these files by their `priority` header. The `batch-priority` logic identifies the highest priority level present, and `selected-files` filters the handoffs that match this priority (lines 66-70). This grouping ensures that urgent work is batched together before lower-priority items. ## Batch Directory Creation and Git Merge Once handoffs are selected, the `new-batch-dir` function generates a unique identifier using the pattern `batch__` and creates this directory inside the `in_process` work area (lines 33-38). Each selected handoff file is then moved from the inbox into this batch folder via `fs/move`. During the move operation, the system updates metadata headers on each handoff using `set-header!`. The script adds `dequeued_at` timestamps and `task_base_commit` references to track when the handoff entered processing and its git state (lines 71-77). After physical relocation, the `merge-batch!` function iterates through the batch contents and calls `merge-git-handoff!` for every file. This applies any `git_handoff` payloads to the working directory, ensuring the role receives the accumulated code changes from all batched handoffs. ## Emission and Resolution of Batch Tasks Following successful merging, the `print-batch` function (lines 98-110) emits a structured summary to standard output. This includes the `BATCH:` line showing the full path to the batch directory, a `COUNT:` of items, and the `TASK_NAME:` derived from the first handoff's `task` header. Each item in the batch is enumerated with `BATCH_ITEM:` entries for downstream parsing. When the receiving role queries for the next work unit via [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), the `top-batch-task` and `top-batch-task-id` functions in `swarmforge/scripts/swarm_handoff.bb` (lines 44-48) extract the logical task name from the first handoff's headers. This allows the role to treat the entire batch as a single named unit while retaining access to individual handoffs within the batch directory. ## Completion and Cleanup After the role finishes processing, the `done_with_current_batch.bb` helper script removes the batch directory from `in_process` and archives it to the `completed` inbox. This atomic cleanup ensures that partial batch processing cannot occur; the batch is either fully processed or remains in the active queue. ## Practical Implementation Example Configure a role for batch processing in your `swarmforge.bb`: ```clojure ;; Role "cleaner" receives work in batch mode with forward-only policy cleaner codex worktree1 batch forward-only ``` Execute the batch receiver: ```bash bb swarmforge/scripts/ready_for_next_batch.bb ``` Expected output: ```text BATCH: .swarmforge/handoffs/inbox/in_process/batch_20260824T150500Z_000001 COUNT: 3 TASK_NAME: Command Syntax BATCH_ITEM: 1 TASK: ... BATCH_ITEM: 2 TASK: ... BATCH_ITEM: 3 TASK: ... ``` This command groups all priority-matched handoffs, creates the batch directory, merges git changes, and presents the consolidated work unit for processing. ## Summary - **Configuration**: Set `receive-mode batch` in `swarmforge.bb` to enable batch processing; the parser defaults to `task` if unspecified. - **Grouping**: The `ready_for_next_batch.bb` script groups handoffs from `.swarmforge/handoffs/inbox/new` by matching `priority` headers. - **Atomic Bundling**: Handoffs move into a unique `batch__` directory under `in_process`, receiving `dequeued_at` and `task_base_commit` metadata. - **Git Integration**: The `merge-git-handoff!` function applies all git payloads within the batch before the role receives the work. - **Logical Unification**: `top-batch-task` in `swarm_handoff.bb` treats the batch as a single task while preserving individual handoff granularity. ## Frequently Asked Questions ### What is the difference between task and batch receive mode in SwarmForge? **Task mode** processes handoffs individually, presenting each as a separate work unit to the role, while **batch receive mode** aggregates multiple handoffs sharing the same priority into a single logical task. In batch mode, the role receives a directory containing all related handoffs and processes them atomically, which is ideal for coordinated operations across multiple work items. ### How does SwarmForge determine which handoffs belong to the same batch? The system evaluates the `priority` header of each handoff file in `.swarmforge/handoffs/inbox/new`. The `batch-priority` logic selects the highest priority level present in the queue, and all handoffs sharing that priority value are bundled into the same batch. Lower priority handoffs remain in the inbox for future batch cycles. ### What happens to git handoffs during batch processing? During batch creation, the `merge-batch!` function in `ready_for_next_batch.bb` calls `merge-git-handoff!` for every handoff in the batch. This applies each handoff's `git_handoff` payload sequentially to the working directory, ensuring the receiving role sees the cumulative state of all code changes without needing to manually merge individual contributions. ### How is a batch marked as complete after processing? Once the role finishes working on the batch, the `done_with_current_batch.bb` script performs cleanup by removing the batch directory from `in_process` and moving it to the `completed` inbox. This helper ensures that batch processing is atomic—either all handoffs in the batch are processed and archived, or the batch remains active in the processing queue.