Agent Handoffs Directory Structure in Swarm Forge: Complete Guide

The Swarm Forge agent handoffs directory structure uses a dedicated .swarmforge/handoffs/ work-tree with separate outbox/, sent/, failed/, and inbox/ directories to manage reliable, auditable communication between agents.

Agent handoffs form the backbone of Swarm Forge's multi-agent coordination system. This directory structure, defined in the handoff protocol specification, provides atomic file operations and clear audit trails that support robust restart behavior. The design ensures no handoff is lost during daemon crashes or network interruptions.

The Handoff Hierarchy Explained

The complete directory tree for agent handoffs in Swarm Forge follows this pattern:

.swarmforge/handoffs/
  outbox/
    tmp/
  sent/
  failed/
  inbox/
    new/
    in_process/
    completed/

Each directory serves a specific purpose in the handoff lifecycle. The structure appears in the protocol specification at swarmforge/handoff-protocol.md [lines 24-38], which defines how the handoffd daemon processes files through this pipeline.

Outbox: Where Handoffs Originate

The outbox/ directory holds handoff files that the local agent intends to send. The daemon monitors this directory continuously, watching for new .handoff files.

Inside outbox/, the tmp/ subdirectory provides a staging area for atomic writes. Agents write draft handoffs here first, then move completed files to outbox/ itself. The daemon ignores tmp/, preventing partial writes from triggering premature processing.

Sent and Failed: Audit Archives

Once the daemon successfully delivers a handoff to all recipients, it moves the original file to sent/. This creates a permanent record of outbound communication.

Handoffs that fail validation or delivery—due to malformed headers, unreachable recipients, or protocol violations—land in failed/. Operators can inspect these files for diagnostics without disrupting active workflow.

Inbox: The Task Queue

The inbox/ directory functions as the agent's task queue with three sub-states:

• new/ — Handoffs awaiting first processing, ordered by priority prefix
• in_process/ — The currently active handoff (or batch directory in batch mode)
• completed/ — Finished handoffs preserved for audit purposes

This three-state model prevents task loss: an agent crashing mid-work leaves evidence in in_process/, enabling automatic recovery on restart.

Creating and Sending Handoffs

Agents use the swarm_handoff.sh helper to validate and queue outbound handoffs. The workflow demonstrates how the directory structure enables safe handoff creation:

# Write a draft handoff in ./tmp/

cat > ./tmp/handoff.txt <<'EOF'
type: git_handoff
to: cleaner
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9e8
EOF

# Validate and queue the handoff

swarm_handoff.sh ./tmp/handoff.txt

After validation, swarm_handoff.sh writes the final .handoff file into .swarmforge/handoffs/outbox/. The daemon then copies it to each recipient's inbox/new/ directory.

Processing Inbound Handoffs

Agents claim work using ready_for_next.sh, which interacts with the inbox structure:

# Agent runs this to claim the next task

ready_for_next.sh

Typical output shows the handoff file path and metadata:

TASK: .swarmforge/handoffs/inbox/in_process/00_20260615T140531Z_000042_from_architect_to_coder.handoff
FROM: architect
TYPE: git_handoff
PRIORITY: 00
TASK_NAME: task-1-cave-setup
PAYLOAD:
Re-read your role and constitution.
merge_and_process.sh architect a1b2c3d9

The script atomically moves the highest-priority handoff from inbox/new/ to inbox/in_process/.

Completing Handoffs

When finished, agents call done_with_current.sh to advance the state:

done_with_current.sh

This moves the handoff from in_process/ to completed/ and checks for additional waiting mail.

Key Implementation Files

File	Location	Purpose
handoff-protocol.md	swarmforge/handoff-protocol.md	Specification of daemon behavior, directory layout, and file formats
handoff_lib.bb	swarmforge/scripts/handoff_lib.bb	Library functions for reading/writing handoff headers
swarm_handoff.sh	swarmforge/scripts/swarm_handoff.sh	Validates drafts and enqueues handoffs to outbox/
handoffd.bb	swarmforge/scripts/handoffd.bb	The daemon that watches directories and manages delivery
ready_for_next.sh	swarmforge/scripts/ready_for_next.sh	Entry point for agents to claim the next task
done_with_current.sh	swarmforge/scripts/done_with_current.sh	Entry point for agents to mark tasks complete

These files together enforce the Swarm Forge agent handoffs directory structure, ensuring reliable communication between roles.

Summary

• .swarmforge/handoffs/ is the root work-tree for all inter-agent communication
• outbox/ with its tmp/ staging area enables safe, atomic handoff creation
• sent/ and failed/ directories provide complete audit trails for outbound traffic
• inbox/new/, inbox/in_process/, and inbox/completed/ implement a robust three-state task queue
• Helper scripts in swarmforge/scripts/ abstract directory operations for agent authors
• The handoffd daemon automates delivery while maintaining state consistency across crashes

Frequently Asked Questions

What happens if the handoff daemon crashes during delivery?

The daemon's design ensures crash safety. Handoffs remain in outbox/ until fully copied to all recipient inboxes. Partial deliveries are detected on restart by checking file presence in recipient inbox/new/ directories, and the daemon resumes from the last consistent state rather than duplicating or losing handoffs.

Can multiple agents share one handoffs directory?

No. Each agent maintains its own .swarmforge/handoffs/ work-tree within its repository clone. The daemon operates on a single agent's directories, and cross-agent communication occurs through copying files between distinct directory trees, not shared filesystem access.

How does priority ordering work in the inbox?

Handoff filenames begin with a zero-padded priority number (e.g., 00_, 50_), lexicographically sorted. The ready_for_next.sh script selects the lowest-numbered (highest priority) handoff from inbox/new/ when claiming work, enabling urgent tasks to preempt routine processing.

What file format does a handoff use?

Handoffs are text files with a YAML-like header containing type, to, priority, task, and optional fields like commit, followed by a PAYLOAD: delimiter and free-form instructions. The handoff_lib.bb library provides strict parsing to validate headers before queueing.

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