# Agent Handoffs Directory Structure in Swarm Forge: Complete Guide

> Explore the Swarm Forge agent handoffs directory structure, detailing outbox, sent, failed, and inbox folders for robust agent communication. Understand the .swarmforge/handoffs/ work-tree.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-09-02

---

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

```text
.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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) helper to validate and queue outbound handoffs. The workflow demonstrates how the directory structure enables safe handoff creation:

```sh

# 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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), which interacts with the inbox structure:

```sh

# Agent runs this to claim the next task

ready_for_next.sh

```

Typical output shows the handoff file path and metadata:

```text
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`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) to advance the state:

```sh
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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.