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

> Understand the window-invisible directive in swarmforge.conf. Learn how to run SwarmForge agents headlessly in tmux for a clean UI. Maximize your terminal visibility.

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

---

**The `window-invisible` directive in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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](https://github.com/unclebob/swarm-forge/blob/main/README.md), the **first visible window** in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf):

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

```conf
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`](/swarmforge/scripts/swarmforge.bb) handles the distinction at runtime:

1. **Parsing**: Each line of [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md)](/swarmforge/handoff-protocol.md). The propagation behavior is independent of window visibility.

### Example with Batch Mode and Custom Flags

```conf
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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) | Runtime configuration file parsed by the launcher |
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](/test/swarmforge/script_test.clj) verify correct parsing of `window-invisible` lines, ensuring the launcher distinguishes visibility directives reliably.