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

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 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. 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
• 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
• 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
• 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
• 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.

# Force iTerm2 adapter explicitly

export SWARMFORGE_TERMINAL=iterm2
swarmforge run my-task

# Enable automatic detection (recommended)

unset SWARMFORGE_TERMINAL
swarmforge run my-task

# 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	Detection and loader logic
swarmforge/scripts/terminal-adapters/ghostty.sh	Ghostty integration via AppleScript
swarmforge/scripts/terminal-adapters/iterm2.sh	iTerm2 integration via AppleScript
swarmforge/scripts/terminal-adapters/windows-terminal.sh	Windows Terminal via wt.exe
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.

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