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

> Understand SwarmForge window vs window-invisible directives. Learn how to control agent visibility for silent or visible terminal execution. Maximize your workflow efficiency.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: deep-dive
- Published: 2026-08-31

---

**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](https://github.com/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.

```clojure
;; 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.

```bash

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

```clojure
;; 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:

```bash

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

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

```

### Default Pack Behavior

As noted in [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/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.