# SwarmForge Receive Modes Explained: Task vs Batch Processing

> Learn SwarmForge receive modes task vs batch processing. Understand how task handles single items and batch processes grouped, priority-matched handoffs efficiently.

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

---

**SwarmForge agents process incoming handoffs using either `task` or `batch` receive mode, with `task` as the default for single-item processing and `batch` for grouped, priority-matched handoffs.**

SwarmForge is a distributed agent orchestration framework where each role's behavior is configured through [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf). The **receive mode** determines how an agent consumes work from its queue—either one handoff at a time or multiple handoffs as a coordinated batch. Understanding this distinction is critical for optimizing workflow throughput and ensuring proper handoff semantics.

## What Are SwarmForge Receive Modes?

The receive mode controls the consumption pattern of the [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) and [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) helper scripts. These scripts delegate to mode-specific implementations based on the role's configuration.

According to the SwarmForge source code, the `window` line syntax in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) follows this pattern:

```conf
window <role> <backend> <worktree> [<receive-mode>] [<propagation>]

```

When `receive-mode` is omitted, it defaults to `task` [source (README lines 99-105)](https://github.com/unclebob/swarm-forge/blob/main/README.md).

### Task Mode

**`task`** processes exactly one handoff per cycle.

When [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) executes in `task` mode:

1. It calls [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh)
2. Selects the highest-priority handoff from `inbox/queued/`
3. Moves it to `inbox/in_process/`
4. Outputs a `TASK:` line with the handoff path

After the agent completes work, [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) invokes [`done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_task.sh) to finalize that single handoff.

**Use `task` mode for roles handling independent work units**, such as `specifier`, `coder`, or sequential `refactorer` operations.

### Batch Mode

**`batch`** consumes all queued handoffs sharing the same priority as the first handoff.

When [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) executes in `batch` mode:

1. It calls [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh)
2. Identifies the first handoff's priority
3. Collects every matching handoff from `inbox/queued/`
4. Creates a batch directory: `inbox/in_process/batch_<timestamp>/`
5. Moves all collected handoffs into this directory
6. Outputs a `BATCH:` line with the batch path

[`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) then calls [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh) to complete all handoffs in the batch simultaneously.

**Use `batch` mode for roles requiring grouped processing**, such as `cleaner` (linting/formatting across commits), `architect` (cross-cutting design changes), `hardender` (security hardening), or `QA` (validation suites).

## Pack Defaults for Receive Modes

SwarmForge packs ship with role-appropriate receive mode defaults [source (packs configuration lines 14-19)](https://github.com/unclebob/swarm-forge/blob/main/packs):

| Pack | Role | Default Configuration |
|------|------|----------------------|
| **two-pack** | `cleaner` | `batch back-one` |
| **four-pack** | `refactorer` | `task back-one` |
| | `architect` | `batch back-all` |
| **six-pack** | `cleaner` | `batch back-one` |
| | `architect` | `batch back-all` |
| | `hardender` | `batch back-all` |
| | `QA` | `batch back-all` |

These defaults reflect operational intent: refactoring typically requires focused, sequential attention (task), while cleaning, architectural review, and quality assurance benefit from holistic, grouped processing (batch).

## Practical Configuration Examples

### Basic Task Mode Role

```conf

# In swarmforge.conf

window coder codex wt-coder task forward-only

```

Explicitly sets `task` mode with `forward-only` propagation—handoffs move forward through the pipeline without returning.

### Batch Mode with Back-One Propagation

```conf

# In swarmforge.conf

window cleaner claude wt-cleaner batch back-one

```

Enables batch processing; completed batches return one step backward in the pipeline for review or correction.

### Overriding Pack Defaults

```conf

# Custom project swarmforge.conf

window architect claude wt-arch task forward-only

```

Forces sequential task processing despite the four-pack's default `batch back-all` for architects.

## How Receive Modes Work in the Handoff Protocol

The [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) script in `swarmforge/scripts/` reads the role's receive mode from `.swarmforge/roles.tsv` (generated from [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)) and dispatches accordingly [source (handoff-protocol.md)](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#role-receive-mode):

```bash

# Conceptual flow from ready_for_next.sh

ROLE_MODE=$(get_role_mode_from_tsv)
if [ "$ROLE_MODE" = "batch" ]; then
    exec ready_for_next_batch.sh
else
    exec ready_for_next_task.sh
fi

```

Similarly, [`done_for_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_for_current.sh) branches to either [`done_for_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_for_current_task.sh) or [`done_for_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_for_current_batch.sh).

### Direct Script Usage

```bash

# Inside a role's worktree directory

./ready_for_next.sh

# Output: BATCH: ./inbox/in_process/batch_20260828T123456/

# After agent processing completes

./done_with_current.sh

# Entire batch marked complete

```

## Choosing Between Task and Batch Modes

| Consideration | Prefer `task` | Prefer `batch` |
|-------------|-------------|--------------|
| **Work independence** | Items unrelated, order-agnostic | Items related, benefit from joint context |
| **Agent context limits** | Long context per item | Single context for multiple items |
| **Pipeline latency** | Fine-grained progress visibility | Reduced per-item overhead |
| **Rollback granularity** | Individual handoff retry | Batch-level retry |
| **Ordering guarantees** | Strict FIFO per priority | Priority-group atomicity |

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`swarmforge/scripts/ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next.sh) | Entry point that dispatches to task or batch handlers |
| [`swarmforge/scripts/ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next_task.sh) | Single handoff selection and staging |
| [`swarmforge/scripts/ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next_batch.sh) | Priority-grouped batch creation |
| [`swarmforge/scripts/done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/done_with_current.sh) | Completion dispatcher |
| [`swarmforge/scripts/done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/done_with_current_task.sh) | Single handoff finalization |
| [`swarmforge/scripts/done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/done_with_current_batch.sh) | Batch directory completion |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Formal protocol specification |
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) | Configuration syntax and pack defaults |

## Summary

- **SwarmForge receive modes** (`task`, `batch`) govern how agents consume handoffs from their queues
- **`task` mode** (default) processes single handoffs sequentially via [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) and [`done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_task.sh)
- **`batch` mode** groups priority-matched handoffs for atomic processing via [`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)
- Pack templates provide sensible defaults: `task` for focused roles (`coder`, `refactorer`), `batch` for holistic roles (`cleaner`, `architect`, `hardender`, `QA`)
- Override defaults in project [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) using the `window <role> <backend> <worktree> [<mode>] [<propagation>]` syntax

## Frequently Asked Questions

### What happens if I don't specify a receive mode in my window configuration?

The mode defaults to `task`. According to the SwarmForge README, the `window` line syntax makes receive mode optional, and when omitted, single-handoff processing is used. This ensures backward compatibility and safe defaults for new roles.

### Can I mix task and batch roles in the same pipeline?

Yes. Each role operates independently according to its own [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) configuration. A `batch` mode `cleaner` can feed into a `task` mode `coder`, with the propagation token controlling handoff direction separately from consumption pattern.

### How does batch mode handle priority conflicts?

[`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh) selects the first handoff by priority and timestamp, then includes only handoffs matching that exact priority level. Higher or lower priority handoffs remain queued for subsequent cycles, preserving priority semantics within batches.