What Does `window-invisible` Mean in `swarmforge.conf`? Terminal Visibility Explained

The window-invisible directive in swarmforge.conf launches a SwarmForge agent without opening a visible terminal window, keeping the UI uncluttered while the agent runs headlessly in a tmux session.

The swarmforge.conf file is the central configuration that defines the shape of a SwarmForge swarm. Each line represents a window — a tmux session that runs a single agent role. Understanding visibility directives is essential for controlling which agents appear in your terminal and which operate silently in the background.

window vs window-invisible: A Direct Comparison

SwarmForge offers two directives for launching agent roles. The choice determines whether a terminal surface appears for that role:

Directive	Behavior	Terminal Visibility
window	Launches the agent with a visible terminal window (or tab)	Terminal surface attached to the tmux session
window-invisible	Launches the agent without a visible terminal window	No terminal surface; window tracked but hidden

How window-invisible Works in Pack Branches

Pack branches like two-pack, four-pack, and six-pack use window-invisible as their default for every role. This design choice keeps the UI clean and manageable when running multiple agents simultaneously.

According to the SwarmForge README, the first visible window in swarmforge.conf serves a special purpose: it becomes the cleanup window. Closing this window tears down the entire swarm. Invisible windows, however, can be reopened automatically by the watchdog if they disappear unexpectedly.

Typical Pack-Default Configuration

When you instantiate a pack branch, you'll see configurations like this in swarmforge.conf:

window-invisible specifier grok master
window-invisible coder    codex  coder --yolo
window-invisible refactorer codex refactorer back-one --yolo
window-invisible architect grok  architect batch back-all

All four roles run without dedicated terminal windows.

Making a Role Visible for Debugging

To expose a specific role's terminal — useful for debugging — change window-invisible to window:

window architect grok architect batch back-all

Now the architect role gets its own visible terminal surface.

How SwarmForge Parses These Directives

The launch logic in swarmforge/scripts/swarmforge.bb handles the distinction at runtime:

1. Parsing: Each line of swarmforge.conf is parsed to extract the directive, role name, backend (e.g., grok, codex), and any flags
2. Session creation: A tmux session is created for every role regardless of visibility
3. Terminal attachment: For window, the script opens a terminal surface; for window-invisible, this step is omitted — the agent still runs headlessly
4. CLI forwarding: Additional arguments (like --yolo) are passed directly to the agent backend

Additional Configuration Options

Each configuration line supports more than just visibility control. After the directive and role/backend names, you can specify:

Receive Mode

• task (default): The role consumes handoffs one at a time
• batch: The role consumes all queued handoffs of the same priority as a single batch

Propagation Token

• forward-only (default): Forwards handoff to the next window only
• back-one: Queues a merge-only copy to the previous window
• back-all: Queues merge-only copies to every earlier window

These tokens control how handoff copies propagate through the swarm, as detailed in [swarmforge/handoff-protocol.md](/swarmforge/handoff-protocol.md). The propagation behavior is independent of window visibility.

Example with Batch Mode and Custom Flags

window coder copilot wt-coder task --dangerously-skip-permissions

This creates a visible window running the copilot backend in wt-coder role with task-based receive mode and a permission-skipping flag.

Key Source Files

File	Purpose
swarmforge/swarmforge.conf	Runtime configuration file parsed by the launcher
README.md	Authoritative description of file format and semantics
swarmforge/scripts/swarmforge.bb	Launcher script that reads :config-file and creates tmux sessions
swarmforge/handoff-protocol.md	Documentation for propagation token behavior
test/swarmforge/script_test.clj	Unit tests verifying window-invisible line parsing

Summary

• window-invisible launches agents without terminal visibility; window shows the terminal
• Pack branches default to invisible windows for UI cleanliness
• The first visible window becomes the cleanup window for swarm teardown
• Visibility is orthogonal to receive mode (task/batch) and propagation tokens (forward-only/back-one/back-all)
• Change directives in swarmforge.conf based on whether you need to monitor or debug a specific agent

Frequently Asked Questions

What happens if I close an invisible window?

Invisible windows are tracked by SwarmForge's watchdog and can be reopened automatically if they disappear. Only the first visible window triggers full swarm teardown when closed.

Can I mix window and window-invisible in the same configuration?

Yes. Mixing directives is common when debugging — keep most agents invisible while making one or two roles visible to monitor their behavior.

Does window-invisible affect agent performance or capabilities?

No. The agent runs with identical functionality; only terminal surface attachment differs. Both versions operate within full tmux sessions and participate equally in the handoff protocol.

Where is the parsing logic for these directives tested?

Unit tests in test/swarmforge/script_test.clj verify correct parsing of window-invisible lines, ensuring the launcher distinguishes visibility directives reliably.

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