# What Terminal Adapters Does Swarm-Forge Support? (Ghostty, iTerm2, Windows Terminal)

> Swarm-Forge supports Ghostty, iTerm2, and Windows Terminal via a pluggable adapter system. Open terminals, attach tmux sessions, and automate window management efficiently.

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

---

**Swarm-Forge supports Ghostty, iTerm2, and Windows Terminal through a pluggable adapter system that opens terminal windows, attaches tmux sessions, and optionally closes windows when work completes.**

The **terminal adapter system** in [unclebob/swarm-forge](https://github.com/unclebob/swarm-forge) abstracts platform-specific terminal handling into a unified interface. Each adapter implements standard functions like `terminal_open_session` and `terminal_close_window`, letting Swarm-Forge orchestrate tmux-driven workflows without hardcoding terminal-specific logic.

## How the Terminal Adapter System Works

All adapter logic is orchestrated from **[`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh)**. This script:

1. Detects the best available terminal via `detect_terminal_backend`
2. Normalizes the adapter name (handling variants like `iterm` vs `iTerm.app`)
3. Sources the appropriate adapter script
4. Exposes a consistent API for session management

The detection priority is:

- **`SWARMFORGE_TERMINAL`** environment variable (highest priority)
- macOS: `osascript` availability + `TERM_PROGRAM` value
- Windows: presence of `wt.exe`
- Fallback to `none` adapter

## Supported Terminal Adapters

### Ghostty

The **Ghostty** adapter provides full window tracking capabilities on macOS. It can detect existing tabs and manage session lifecycle through AppleScript.

- **Implementation**: [`swarmforge/scripts/terminal-adapters/ghostty.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/ghostty.sh)
- **Capabilities**: Open sessions, track windows (detect existing tabs)
- **User-facing label**: "Ghostty"

This adapter is selected when `TERM_PROGRAM=Ghostty` on macOS systems with `osascript` available.

### iTerm2

The **iTerm2** adapter offers equivalent functionality for iTerm2 users, with session detection and window management via AppleScript.

- **Implementation**: [`swarmforge/scripts/terminal-adapters/iterm2.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/iterm2.sh)
- **Capabilities**: Open sessions, track windows (detect existing sessions)
- **User-facing label**: "iTerm2"

Detection matches `TERM_PROGRAM` values including `iTerm2`, `iTerm`, and `iTerm.app`.

### Windows Terminal

The **Windows Terminal** adapter uses `wt.exe` for session creation but has limited introspection capabilities.

- **Implementation**: [`swarmforge/scripts/terminal-adapters/windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/windows-terminal.sh)
- **Capabilities**: Open sessions via `wt.exe` command line
- **Limitation**: **Cannot track windows** (no query API for existing tabs)
- **User-facing label**: "Windows Terminal"

This adapter is auto-selected on Windows when `wt.exe` is found in PATH.

### Fallback (None)

The **none** adapter disables all terminal integration. Swarm-Forge runs headlessly without spawning terminal windows.

- **Implementation**: [`swarmforge/scripts/terminal-adapters/none.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/none.sh)
- **Use case**: CI/CD environments, remote servers, or when terminal management is handled externally

## Adapter API and Usage Examples

Each adapter exports a consistent function interface. After loading, you interact with these standardized functions regardless of the underlying terminal.

```bash

# Force iTerm2 adapter explicitly

export SWARMFORGE_TERMINAL=iterm2
swarmforge run my-task

```

```bash

# Enable automatic detection (recommended)

unset SWARMFORGE_TERMINAL
swarmforge run my-task

```

```bash

# Direct adapter API usage (after adapter is loaded)

session_id=$(terminal_open_session "my-tmux-session" "My Task")
echo "Opened: $session_id"

# Clean up when finished

terminal_close_window "$session_id"

```

The adapter implementations hide all platform specifics—AppleScript for macOS terminals, `wt.exe` CLI for Windows.

## Adapter Comparison

| Adapter | Platform | Window Tracking | Detection Method |
|---------|----------|-----------------|----------------|
| Ghostty | macOS | Yes | `TERM_PROGRAM=Ghostty` + `osascript` |
| iTerm2 | macOS | Yes | `TERM_PROGRAM` ∈ {`iTerm2`,`iTerm`,`iTerm.app`} |
| Windows Terminal | Windows | No | `wt.exe` in PATH |
| none | Any | N/A | Fallback when no match |

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh) | Detection and loader logic |
| [`swarmforge/scripts/terminal-adapters/ghostty.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/ghostty.sh) | Ghostty integration via AppleScript |
| [`swarmforge/scripts/terminal-adapters/iterm2.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/iterm2.sh) | iTerm2 integration via AppleScript |
| [`swarmforge/scripts/terminal-adapters/windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/windows-terminal.sh) | Windows Terminal via `wt.exe` |
| [`swarmforge/scripts/terminal-adapters/none.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/none.sh) | No-op fallback adapter |

## Summary

- Swarm-Forge's **terminal adapter system** supports **Ghostty**, **iTerm2**, and **Windows Terminal** through modular shell scripts
- **Ghostty and iTerm2 adapters** provide full window tracking on macOS via AppleScript
- **Windows Terminal adapter** supports session creation but cannot query existing windows due to API limitations
- Override detection with the **`SWARMFORGE_TERMINAL`** environment variable for explicit control
- The **`none`** adapter enables headless operation when terminal integration isn't needed

## Frequently Asked Questions

### How do I force Swarm-Forge to use a specific terminal?

Set the `SWARMFORGE_TERMINAL` environment variable to the normalized adapter name. Valid values include `ghostty`, `iterm2`, `windows-terminal`, or `none`. This bypasses automatic detection entirely.

### Why doesn't Windows Terminal support window tracking?

The Windows Terminal adapter relies on `wt.exe` command-line invocation. Unlike macOS terminals with AppleScript APIs, Windows Terminal does not expose a programmatic interface to enumerate or query existing tabs, making session tracking impossible.

### What happens if no supported terminal is detected?

Swarm-Forge falls back to the `none` adapter. Operations that would normally open terminal windows instead run headlessly. This is the default behavior in SSH sessions, containers, or CI environments.

### Can I use Swarm-Forge with terminals not in the supported list?

Only the four built-in adapters are available. To add support for another terminal, you would need to create a new adapter script implementing the required functions (`terminal_open_session`, `terminal_close_window`, etc.) following the pattern in [`swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-terminal-adapter.sh).