# Task vs Batch Receive Modes in SwarmForge: How to Choose the Right Processing Strategy > Understand SwarmForge task vs batch receive modes. Learn how to choose the right processing strategy for your roles to optimize handoff consumption and ensure atomic unit processing. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: deep-dive - Published: 2026-08-08 --- **SwarmForge supports two receive modes—`task` and `batch`—that determine whether a role processes handoffs individually or consumes multiple queued items as an atomic unit.** The `unclebob/swarm-forge` repository implements a window-based orchestration system where each role declares its preferred consumption pattern via the **receive mode**. This setting controls the granularity of work assignment and directly impacts how agents handle incoming handoffs from the swarm pipeline. ## Understanding Receive Modes in SwarmForge Every window defined in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) specifies a receive mode that dictates handoff consumption behavior. According to the source code in `swarmforge/scripts/swarmforge.bb` (lines 151–166), the system validates this mode during role initialization and defaults to `task` when omitted. The fundamental distinction lies in atomicity: - **Task mode** creates a 1:1 relationship between handoff files and work cycles - **Batch mode** groups equal-priority handoffs into a temporary directory for collective processing ## Task Mode: Single-Handoff Processing Task mode establishes a sequential work loop where the role handles one handoff at a time. ### How Task Mode Works When a role configured for task mode calls `ready_for_next`, the system prints `TASK: ` and exposes a single handoff file. The agent processes this specific task, then invokes `done_with_current` to signal completion before returning to the waiting state. This pattern suits roles requiring isolated context, such as a coder implementing individual features without cross-dependencies. ### Configuration Example Declare task mode explicitly in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) or omit the parameter to accept the default: ```conf # swarmforge/swarmforge.conf window coder codex coder ;# receives tasks one at a time window reviewer gpt-4 reviewer task ;# explicit task declaration ``` ## Batch Mode: Multi-Handoff Processing Batch mode enables roles to pull all queued handoffs of equal priority and process them as a cohesive unit. ### How Batch Mode Works When `ready_for_next` executes in batch mode, the system outputs `BATCH: ` and creates a temporary batch directory containing the grouped handoff files. The role then processes the entire collection before `done_with_current` finalizes the batch and moves files to the completed directory. This approach benefits scenarios like automated refactoring, where applying identical transformations across multiple commits requires shared context. The implementation relies on helper scripts [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh) and [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh), which wrap the underlying Babashka logic in `swarmforge/scripts/ready_for_next_batch.bb` and `swarmforge/scripts/done_with_current_batch.bb`. ### Batch Directory Management Inside `ready_for_next_batch.bb`, the system generates unique batch directories using timestamp-based naming: ```clojure ;; swarmforge/scripts/ready_for_next_batch.bb (defn new-batch-dir [in-process-dir] (let [dir (fs/path in-process-dir (format "batch_%s_%06d" (id-timestamp) suffix))] (fs/create-dir dir) dir)) ``` The batch scripts enforce atomicity by validating against ambiguous states—such as multiple in-process batches or empty batches—before permitting processing to begin. ### Configuration Example Append `batch` to the window declaration to enable batch processing: ```conf # swarmforge/swarmforge.conf window cleaner copilot cleaner batch ;# consumes all pending handoffs as a batch ``` ## Key Implementation Details The receive mode parsing logic resides in `swarmforge/scripts/swarmforge.bb`, where the system validates the mode against allowed values (`task` or `batch`) during window initialization. When batch mode is active, the runtime stores handoff files under `.swarmforge/handoffs/` before grouping them into the temporary batch directory, as documented in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) (lines 49–57). Batch processing guarantees that either all handoffs in the group complete successfully or none do, preventing partial state mutations across the swarm. ## Choosing Between Task and Batch Modes Select the appropriate mode based on your role's workload characteristics: - **Use task mode** when handoffs are independent, require distinct contexts, or involve human-in-the-loop validation that must occur per-item - **Use batch mode** when handoffs share priority levels, involve identical transformations, or benefit from collective analysis (such as linting multiple files simultaneously) ## Summary - **Task mode** processes handoffs sequentially via `TASK: ` output, suitable for isolated work units - **Batch mode** groups equal-priority handoffs into atomic batches via `BATCH: ` and temporary directories - Configuration occurs in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) with `batch` keyword or defaults to `task` - Implementation spans `swarmforge/scripts/swarmforge.bb` for parsing and dedicated `*_batch.bb` scripts for directory management - Batch mode enforces atomic completion through [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh) validation logic ## Frequently Asked Questions ### What is the default receive mode in SwarmForge? If you omit the receive mode parameter in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), the system defaults to **task mode**. This ensures backward compatibility and safe single-item processing for roles that do not explicitly declare batch capabilities. ### How does batch mode handle handoff priority? Batch mode consumes **all queued handoffs of equal priority** as documented in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). The runtime filters the `.swarmforge/handoffs/` directory for matching priority levels before grouping them into the batch directory, ensuring homogeneous processing groups. ### Can I switch receive modes dynamically? No, the receive mode is static for each window declaration. You must modify [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) and restart the role to change from task to batch processing or vice versa, as the mode is parsed during initialization in `swarmforge/scripts/swarmforge.bb`. ### Where are handoff files stored in batch mode? The runtime stores incoming handoffs under `.swarmforge/handoffs/` before `ready_for_next_batch.bb` moves them into a temporary batch directory (formatted as `batch__`). After processing completes, `done_with_current_batch.bb` relocates the files to the completed handoffs area.