How to Override SwarmForge Terminal Backend Detection Using SWARMFORGE_TERMINAL

Set the SWARMFORGE_TERMINAL environment variable before running ./swarm to bypass auto-detection and force a specific terminal emulator such as Ghostty, Terminal.app, or Windows Terminal.

The unclebob/swarm-forge repository provides a flexible mechanism for controlling which terminal emulator launches when you start a swarm session. By default, the framework attempts to detect your environment automatically, but you can override SwarmForge terminal backend detection to ensure consistent behavior across macOS, Windows, and Linux environments.

How SwarmForge Auto-Detects Your Terminal

When you invoke the ./swarm wrapper, the script swarmforge/scripts/swarm-terminal-adapter.sh executes a cascading detection logic to determine which terminal backend to load:

1. AppleScript check – If osascript is available, it assumes macOS and selects Terminal.app.
2. Windows Terminal check – If the wt.exe executable exists in the path, it selects Windows Terminal (typically for WSL environments).
3. Fallback – If neither condition is met, the cleanup window attaches to the current shell session without spawning an external terminal.

This auto-detection works for standard setups, but exotic configurations or personal preferences often require explicit control.

Using SWARMFORGE_TERMINAL to Force a Specific Backend

To bypass the auto-detection logic, export or prefix the SWARMFORGE_TERMINAL environment variable with one of the supported backend identifiers. The adapter script normalizes the input via normalize_terminal_backend and loads the corresponding script from swarmforge/scripts/terminal-adapters/.

# Force Ghostty on macOS

SWARMFORGE_TERMINAL=ghostty ./swarm

# Force Windows Terminal when running inside WSL

SWARMFORGE_TERMINAL=windows-terminal ./swarm

# Disable terminal automation entirely

SWARMFORGE_TERMINAL=none ./swarm

When SWARMFORGE_TERMINAL is set, the framework ignores AppleScript and wt.exe detection, proceeding directly to the specified backend.

Supported Terminal Backends

The following values are recognized by the adapter system:

• ghostty – Loads swarmforge/scripts/terminal-adapters/ghostty.sh, opening new tabs in the Ghostty emulator (macOS).
• terminal-app – Loads terminal-app.sh, forcing the use of macOS Terminal.app regardless of other installed emulators.
• windows-terminal – Loads windows-terminal.sh, explicitly targeting Windows Terminal for WSL-based workflows.
• none – Loads no adapter script. The cleanup window runs in the current shell session, effectively disabling terminal automation.

Each backend script must implement a small contract defining functions like terminal_backend_can_open_sessions and terminal_open_session. If the selected backend reports that it cannot open sessions, SwarmForge falls back to the none behavior.

Implementing Custom Terminal Adapters

If your preferred terminal is not among the built-in options, you can extend the system by creating a new adapter. Add a shell script to swarmforge/scripts/terminal-adapters/ (for example, wezterm.sh) that implements the required interface functions. Once the file exists, reference it via:

SWARMFORGE_TERMINAL=wezterm ./swarm

The swarm-terminal-adapter.sh script dynamically sources any file matching the normalized backend name, allowing seamless integration of custom terminals without modifying core framework code.

How the Backend Persists Across the Session

The selected backend is not transient. According to the source code in close-swarm and swarmforge/scripts/swarmforge.bb, the value of SWARMFORGE_TERMINAL is copied into SWARMFORGE_TERMINAL_BACKEND during initialization. This secondary variable ensures that the terminal choice remains available throughout the entire session lifecycle, including cleanup and shutdown phases, preventing mismatches between the launcher and the closer.

Summary

• Auto-detection probes for AppleScript (Terminal.app) or wt.exe (Windows Terminal) before falling back to the current shell.
• Override the detection by setting SWARMFORGE_TERMINAL to ghostty, terminal-app, windows-terminal, or none.
• Backend scripts reside in swarmforge/scripts/terminal-adapters/ and must implement functions like terminal_backend_can_open_sessions.
• Persistence is handled by copying the variable to SWARMFORGE_TERMINAL_BACKEND for use during session teardown.
• Custom adapters can be added by creating new .sh files in the adapters directory.

Frequently Asked Questions

What values can I set for SWARMFORGE_TERMINAL?

You can set SWARMFORGE_TERMINAL to ghostty, terminal-app, windows-terminal, or none. Each value corresponds to a script in swarmforge/scripts/terminal-adapters/ that handles the specific terminal's session management protocols.

How do I disable terminal automation entirely?

Set SWARMFORGE_TERMINAL=none before running ./swarm. This prevents the framework from spawning external windows and runs the cleanup logic directly in your current shell session.

Can I add support for a terminal not listed?

Yes. Create a new shell script in swarmforge/scripts/terminal-adapters/ (e.g., alacritty.sh) that implements the required contract functions including terminal_backend_can_open_sessions and terminal_open_session. Then launch with SWARMFORGE_TERMINAL=alacritty ./swarm.

Why does SwarmForge copy the variable to SWARMFORGE_TERMINAL_BACKEND?

The framework copies SWARMFORGE_TERMINAL into SWARMFORGE_TERMINAL_BACKEND during startup, as seen in close-swarm and swarmforge.bb, to maintain the backend choice throughout the full session lifecycle. This ensures that shutdown and cleanup procedures use the same terminal handling logic as the launcher.

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