Window vs Window-Invisible Directives in SwarmForge: Visibility Control Explained

The window directive launches SwarmForge agents in a visible terminal surface, while window-invisible runs them silently inside tmux without opening a window.

In the unclebob/swarm-forge repository, these two directives determine whether an agent’s terminal session appears as a trackable window or runs invisibly in the background. Understanding the distinction is essential for managing UI clutter when orchestrating multiple AI agents through the cockpit interface.

What Are SwarmForge Directives?

A directive in SwarmForge describes how an agent’s terminal session initializes. When you launch a role—whether a coder, architect, or refactorer—the directive tells the terminal-backend adapter (such as Windows Terminal or iTerm2) how to handle the visual representation of that session.

The two primary visibility directives are:

• window – Creates both a tmux session and a visible terminal window
• window-invisible – Creates only the tmux session, skipping the window creation

The window Directive (Visible Mode)

The window directive provides full terminal visibility for direct interaction. When specified, SwarmForge starts the agent inside a tmux session and instructs the terminal-backend adapter to open a new window or tab.

This mode is ideal for:

• Debugging specific roles where you need direct terminal access
• Interacting manually with agents during development
• Monitoring real-time output without the cockpit UI

In swarmforge/scripts/swarmforge.bb, the function visible-window? returns true when processing the window directive, triggering the window creation logic in the adapter layer.

;; Launch a visible terminal window for the "coder" role
window coder grok coder

The window-invisible Directive (Headless Mode)

The window-invisible directive runs agents in headless mode. The agent still executes inside a tmux session for process management and logging, but no terminal surface is created. This prevents window proliferation when managing multiple agents.

This is the default behavior for pack branches, where the browser-based cockpit displays all output centrally rather than spawning separate terminal windows.

# Running a pack-branch command (default uses invisible windows)

swarmforge window-invisible refactorer grok refactorer back-one

Implementation Details

The visibility logic resides in swarmforge/scripts/swarmforge.bb at line 142. The visible-window? function maps directive strings to Boolean values:

;; From swarmforge/scripts/swarmforge.bb (line 142)
(defn visible-window? [directive]
  (= "window" directive))

This Boolean flag propagates through the parser to the terminal-backend adapters. When true, the adapter executes its window-creation routine; when false, it skips window creation while maintaining the tmux session.

According to the source code in test/swarmforge/script_test.clj (lines 144–153), both directives undergo parsing validation to ensure the visibility flag correctly toggles between terminal and headless modes.

Practical Usage Examples

Explicit Visible Window

Use this when you need a dedicated, trackable terminal for a specific role:

# Explicitly request a visible window for a non-pack branch

swarmforge window architect codex architect batch back-all --allow-all-tools

Silent Operation with Cockpit

Use this for clean cockpit operation without terminal clutter:

;; Launch silently (no terminal surface)
window-invisible coder grok coder

Default Pack Behavior

As noted in README.md (lines 311–313), pack branches automatically leverage window-invisible so that each role runs silently while the cockpit UI aggregates output in the browser.

Summary

• window creates a visible terminal surface alongside the tmux session for direct agent interaction.
• window-invisible runs agents in tmux without opening terminal windows, ideal for cockpit-based workflows.
• The visible-window? function in swarmforge/scripts/swarmforge.bb (line 142) controls this behavior by returning true for window and false for window-invisible.
• Pack branches default to window-invisible to prevent UI clutter, while individual role debugging typically uses window.

Frequently Asked Questions

When should I use window-invisible instead of window?

Use window-invisible when running agents through the SwarmForge cockpit or when you want to avoid terminal window proliferation. Use window when you need direct terminal access for debugging or manual interaction with a specific agent.

Does window-invisible still create a tmux session?

Yes. Both directives create tmux sessions for process management and logging. The only difference is that window-invisible skips the step where the terminal-backend adapter opens a visible window or tab.

Where is the visibility logic implemented in the source code?

The visibility mapping is implemented in the visible-window? function inside swarmforge/scripts/swarmforge.bb at line 142. This function returns a Boolean that the parser passes to terminal-backend adapters, determining whether to open a new window.

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