Task vs Batch Receive Modes in SwarmForge: How to Choose the Right Processing Strategy

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 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: <path> 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 or omit the parameter to accept the default:

# 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: <path> 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 and 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:

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

# 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 (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: <path> output, suitable for isolated work units
• Batch mode groups equal-priority handoffs into atomic batches via BATCH: <path> and temporary directories
• Configuration occurs in 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 validation logic

Frequently Asked Questions

What is the default receive mode in SwarmForge?

If you omit the receive mode parameter in 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. 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 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_<timestamp>_<suffix>). After processing completes, done_with_current_batch.bb relocates the files to the completed handoffs area.

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