SwarmForge Receive Modes Explained: Task vs Batch Processing

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. 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 and 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 follows this pattern:

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

When receive-mode is omitted, it defaults to task source (README lines 99-105).

Task Mode

task processes exactly one handoff per cycle.

When ready_for_next.sh executes in task mode:

1. It calls 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 invokes 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 executes in batch mode:

1. It calls 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 then calls 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):

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

# 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

# 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

# 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 script in swarmforge/scripts/ reads the role's receive mode from .swarmforge/roles.tsv (generated from swarmforge.conf) and dispatches accordingly source (handoff-protocol.md):

# 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 branches to either done_for_current_task.sh or done_for_current_batch.sh.

Direct Script Usage

# 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	Entry point that dispatches to task or batch handlers
swarmforge/scripts/ready_for_next_task.sh	Single handoff selection and staging
swarmforge/scripts/ready_for_next_batch.sh	Priority-grouped batch creation
swarmforge/scripts/done_with_current.sh	Completion dispatcher
swarmforge/scripts/done_with_current_task.sh	Single handoff finalization
swarmforge/scripts/done_with_current_batch.sh	Batch directory completion
swarmforge/handoff-protocol.md	Formal protocol specification
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 and done_with_current_task.sh
• batch mode groups priority-matched handoffs for atomic processing via ready_for_next_batch.sh and 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 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 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 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.

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