Why the First Window in swarmforge.conf Is the Cleanup Window in SwarmForge

The first window in swarmforge.conf serves as the cleanup window because SwarmForge interprets its closure as the signal to shut down the entire swarm, triggering a systematic teardown of all tmux sessions and tracked terminals.

SwarmForge orchestrates AI agent swarms by reading a project-local configuration file located at swarmforge/swarmforge.conf. Each line in this file defines a tmux window running a role-specific backend, such as a coder, architect, or coordinator. The cleanup window designation falls to whichever role appears first in this configuration, creating a deterministic shutdown path that ensures reliable swarm termination.

How the First Window Controls Swarm Lifecycle

When SwarmForge launches, it parses swarmforge/swarmforge.conf and creates a tmux window for each entry in the order listed. The implementation in swarmforge/scripts/swarmforge.bb treats the first entry specially by attaching the global cleanup routine to that specific window's lifecycle.

Closing any window other than the first merely terminates that specific role's session. The remaining agents continue operating, and the swarm persists. However, when the first window closes—typically the coordinator or master role—SwarmForge initiates a complete shutdown sequence.

The Three-Stage Shutdown Sequence

The cleanup routine executes automatically upon the first window's closure:

1. Stop the OS-level sleep inhibitor that was activated when the swarm launched to prevent the system from sleeping during active operations.
2. Tear down all tmux sessions created for the remaining windows, forcibly terminating any running backend processes.
3. Close the remaining tracked terminal windows that belong to the swarm, returning the terminal environment to its pre-swarm state.

This design provides a single, obvious user action—closing the topmost window—to stop the swarm cleanly, while still permitting individual role termination without affecting the overall system.

Configuration File Structure and Window Ordering

The swarmforge.conf file uses a simple line-based format where position determines function. The repository documentation explicitly states that the first listed window becomes the cleanup window because of its position.

# swarmforge/swarmforge.conf

# The first window is the cleanup window (coordinator runs in the master worktree)

window coordinator codex master          # <-- cleanup window

window coder       codex coder
window refactorer  codex refactorer
window architect   codex architect

According to the README (lines 45-46 and 85), this ordering convention ensures users always know exactly which terminal controls the swarm's lifecycle.

Changing the Cleanup Window Designation

If you need a different role to serve as the cleanup coordinator, simply reorder the entries in swarmforge.conf. Move your desired master role to the first line, and SwarmForge will automatically bind the shutdown logic to that window instead.

For example, to make the architect role control swarm termination:

window architect   codex architect      # Now the cleanup window

window coordinator codex master
window coder       codex coder

No additional configuration flags are required; the parser relies solely on line position to identify the cleanup trigger.

Summary

• Position determines function: The first entry in swarmforge/swarmforge.conf is automatically designated as the cleanup window by the parser in swarmforge/scripts/swarmforge.bb.
• Single-point shutdown: Closing the first window stops the sleep inhibitor, tears down all tmux sessions, and closes tracked terminals.
• Isolated role termination: Closing any other window affects only that specific role, allowing the swarm to continue operating.
• Configurable by reordering: Change which role serves as the cleanup coordinator by rearranging lines in the configuration file.
• Documented behavior: The README.md explicitly documents this convention at lines 45-46 and 85.

Frequently Asked Questions

What happens if I accidentally close a window that isn't the first one?

Only that specific role's tmux session terminates. The swarm continues running with the remaining agents active. You can restart that individual role by reloading the configuration or manually launching that specific window again without affecting the rest of the swarm.

Can I designate a different window as the cleanup window without reordering the file?

No. As implemented in swarmforge/scripts/swarmforge.bb, the cleanup logic is strictly tied to the first parsed window entry. The README confirms this design choice, noting that the first window is the cleanup window specifically because it is listed first. Reordering the configuration file is the intended method for changing this designation.

Where is the cleanup logic implemented in the source code?

The cleanup routine is implemented in swarmforge/scripts/swarmforge.bb, which parses swarmforge.conf and launches the tmux sessions. The first window's termination triggers the shutdown sequence described in swarmforge/handoff-protocol.md, which coordinates the sleep inhibitor shutdown and session teardown.

Why does SwarmForge use window order instead of a configuration flag?

Using the first window as the cleanup mechanism provides a deterministic, user-friendly shutdown path that requires no additional configuration syntax. This convention ensures that the visual order of windows in the terminal matches the control hierarchy, making swarm management intuitive. The documentation emphasizes that this design makes termination reliable by giving users a single, obvious action—closing the topmost window—to stop the entire system.

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