# SwarmForge Handoff Protocol Message Types: git_handoff and note Explained > Explore SwarmForge handoff protocol message types git_handoff and note. Understand how these two message types facilitate code commits and status updates in the SwarmForge system. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: api-reference - Published: 2026-08-09 --- **SwarmForge defines exactly two valid message types—`git_handoff` for code commits and `note` for free-form status updates—that agents exchange when passing work through the handoff protocol.** The SwarmForge handoff protocol governs inter-agent communication in the `unclebob/swarm-forge` repository, enforcing a strict contract for how autonomous roles transfer tasks. Understanding these SwarmForge handoff protocol message types is essential for writing valid handoff files that the validation scripts accept and the delivery daemon processes. ## The Two Message Types According to [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) (lines 27-31 and 90-99), the protocol permits only two distinct message kinds. The [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) validation script explicitly rejects any other `type` values, ensuring protocol compliance across the swarm. ### git_handoff Emit a **`git_handoff`** when your role has committed code that another role must merge and act upon. This message type carries the commit SHA and the logical task name that the commit belongs to. **Required headers:** - `type: git_handoff` - `to` — the recipient role(s) - `priority` — integer priority level - `task` — the task identifier - `commit` — the Git SHA to be merged ### note Use a **`note`** for short free-form informational messages, such as "waiting on QA" or blockers. The protocol restricts this type to explicit directives from the role prompt, constitution, or user instructions. **Required headers:** - `type: note` - `to` — the recipient role(s) - `priority` — integer priority level - `message` — the single-line informational payload ## Message Validation and Expansion The [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) script serves as the validation gate for all outbound handoffs. It enforces the two allowed message types, checks for required headers, and expands drafts by injecting mandatory metadata headers including `id`, `from`, and `created_at`. After validation, the script writes the completed handoff file to the agent’s `outbox/` directory for pickup by the daemon. ## Practical Examples ### Drafting a git_handoff Create a draft file with the required headers: ```text # handoff draft (./tmp/handoff.txt) type: git_handoff to: cleaner priority: 50 task: task-1-cave-setup commit: a1b2c3d9e8 ``` Validate and queue the handoff: ```bash swarm_handoff.sh ./tmp/handoff.txt ``` The script expands the draft with canonical headers, adds a body containing the merge instruction, and places the final file in `outbox/cleaner/`. ### Drafting a note Create a status update draft: ```text # handoff draft (./tmp/note.txt) type: note to: architect,QA priority: 70 message: Waiting on QA result before merging cleanup branch. ``` Process the note through the validator: ```bash swarm_handoff.sh ./tmp/note.txt ``` The resulting handoff includes the standard headers plus the `message` payload, and the daemon delivers it to each recipient’s inbox. ## Daemon Processing and Delivery The `swarmforge/scripts/handoffd.bb` daemon consumes files from the `outbox/` directory, copies them to each recipient’s `inbox/`, and sends tmux wake-up notifications. It relies on the message type to determine how to handle the payload. Meanwhile, helper scripts such as [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) and [`ready_for_next_task_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task_batch.sh) read the `type` header to report incoming work to the receiving agent. ## Summary - **Two exclusive types**: The protocol recognizes only `git_handoff` and `note`; all other types are rejected by [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh). - **Context-specific usage**: Use `git_handoff` for code commits requiring merge actions, and `note` only when explicitly authorized for status updates. - **Strict validation**: The [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) script enforces header requirements and expands drafts before queueing. - **Automated delivery**: The `handoffd.bb` daemon routes validated messages to recipient inboxes based on the `to` header. ## Frequently Asked Questions ### What happens if I use a message type other than git_handoff or note? The [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) validator will reject the handoff file and exit with an error. The protocol explicitly forbids custom message types to maintain consistency across the swarm. ### Can I send a note without being explicitly directed? No. The protocol specification in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) mandates that `note` messages should only be sent when directed by the role prompt, constitution, or user. Unauthorized notes violate the protocol contract. ### Where are handoff files stored after validation? After [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) validates and expands the draft, it writes the completed handoff file to the agent’s `outbox/` directory. The `handoffd.bb` daemon then moves copies to each recipient’s `inbox/` directory. ### How does the daemon know which agent receives the handoff? The daemon parses the `to` header from the validated handoff file. It supports multiple recipients (comma-separated) and copies the message to each target agent’s inbox before sending tmux notifications to wake the receiving processes.