How to Override the Default Terminal Backend in SwarmForge

Set SWARMFORGE_TERMINAL=backend_name before running ./swarm to bypass auto-detection and force a specific terminal emulator.

SwarmForge automatically detects which terminal emulator to use on your system, preferring AppleScript-driven Terminal.app on macOS, then Windows Terminal (wt.exe) on Windows, and finally falling back to a tmux-based cleanup session. However, you can override this behavior entirely using environment variables. This article explains how to control the terminal backend selection in the unclebob/swarm-forge repository.

Understanding SwarmForge's Terminal Detection

The terminal backend selection logic lives in swarmforge/scripts/swarm-terminal-adapter.sh. The detect_terminal_backend() function checks for the SWARMFORGE_TERMINAL environment variable first, only proceeding to auto-detection if the variable is unset:

detect_terminal_backend() {
  if [[ -n "${SWARMFORGE_TERMINAL:-}" ]]; then
    normalize_terminal_backend "$SWARMFORGE_TERMINAL"
  else
    # auto-detect: AppleScript → Windows-Terminal → fallback

    ...
  fi
}

When you provide a backend name, the normalize_terminal_backend function maps common aliases to canonical adapter names. For example, terminal, terminal-app, and terminal.app all resolve to terminal-app (lines 12-16).

Available Terminal Backends

SwarmForge ships with four built-in terminal adapters located in swarmforge/scripts/terminal-adapters/:

Backend	Adapter File	Description
terminal-app	terminal-app.sh	macOS Terminal.app via AppleScript
windows-terminal	windows-terminal.sh	Windows Terminal (wt.exe)
ghostty	ghostty.sh	Ghostty terminal emulator
none	(no adapter)	Disables terminal automation; uses tmux cleanup session

Each adapter implements a standard contract with functions like terminal_backend_label, terminal_open_session, and terminal_close_window.

Override Methods

Method 1: Set SWARMFORGE_TERMINAL for Runtime Override

Force a specific backend for the current swarm invocation:

# Use Ghostty

SWARMFORGE_TERMINAL=ghostty ./swarm

# Use Windows Terminal from WSL

SWARMFORGE_TERMINAL=windows-terminal ./swarm

# Disable terminal automation entirely

SWARMFORGE_TERMINAL=none ./swarm

Method 2: Persist the Override

Add the variable to your shell profile for permanent configuration:

# ~/.bashrc or ~/.zshrc

export SWARMFORGE_TERMINAL=ghostty

Or use a project-specific .env file if your workflow supports it.

Method 3: Configure Cleanup Backend with SWARMFORGE_TERMINAL_BACKEND

The cleanup script swarmforge/scripts/swarm-cleanup.sh reads SWARMFORGE_TERMINAL_BACKEND (line 11) to load the correct adapter during swarm teardown. By default, it uses terminal-app if unset.

For consistent behavior across runtime and cleanup, set both variables:

export SWARMFORGE_TERMINAL=ghostty
export SWARMFORGE_TERMINAL_BACKEND=ghostty
./swarm

Complete Configuration Examples

# Example: Ghostty on macOS with full cleanup support

export SWARMFORGE_TERMINAL=ghostty
export SWARMFORGE_TERMINAL_BACKEND=ghostty
./swarm up

# Example: Windows Terminal from WSL2

SWARMFORGE_TERMINAL=windows-terminal SWARMFORGE_TERMINAL_BACKEND=windows-terminal ./swarm

# Example: Headless/server environment with tmux fallback

SWARMFORGE_TERMINAL=none ./swarm

Key Source Files

• swarmforge/scripts/swarm-terminal-adapter.sh — Core detection and adapter loading
• swarmforge/scripts/swarm-cleanup.sh — Backend selection during teardown
• swarmforge/scripts/terminal-adapters/ghostty.sh — Ghostty adapter implementation
• swarmforge/scripts/terminal-adapters/terminal-app.sh — macOS Terminal.app adapter
• swarmforge/scripts/terminal-adapters/windows-terminal.sh — Windows Terminal adapter

Summary

• Set SWARMFORGE_TERMINAL to override the default terminal backend detection in SwarmForge
• Available backends: terminal-app, windows-terminal, ghostty, none
• Set SWARMFORGE_TERMINAL_BACKEND to ensure cleanup uses the same adapter
• Adapter scripts follow a standard contract defined in swarmforge/scripts/terminal-adapters/
• The normalize_terminal_backend function handles alias resolution for common terminal names

Frequently Asked Questions

What happens if I set SWARMFORGE_TERMINAL to an invalid backend?

SwarmForge will fail to load an adapter and exit with an error. The normalize_terminal_backend function validates the input against available adapter files in swarmforge/scripts/terminal-adapters/. Check the error message to verify the exact backend name expected.

Does SwarmForge support custom terminal adapters?

Yes. The adapter loading system in swarm-terminal-adapter.sh sources files from swarmforge/scripts/terminal-adapters/ based on the normalized backend name. You can create a new .sh file following the existing adapter contract (implementing terminal_backend_label, terminal_open_session, etc.) and reference it via SWARMFORGE_TERMINAL=your-adapter-name.

Why are there two separate environment variables?

SWARMFORGE_TERMINAL controls the active backend during normal swarm operation, while SWARMFORGE_TERMINAL_BACKEND is specifically read by swarm-cleanup.sh during teardown. The separation allows scenarios where runtime and cleanup might need different terminal behaviors, though in practice you'll usually set both to the same value.

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