# How to Override SwarmForge Terminal Backend Detection Using SWARMFORGE_TERMINAL

> Override SwarmForge terminal detection with SWARMFORGE_TERMINAL environment variable. Force Ghostty, Terminal.app, or Windows Terminal before running ./swarm.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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/`.

```bash

# 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/ghostty.sh), opening new tabs in the Ghostty emulator (macOS).
- **`terminal-app`** – Loads [`terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh), forcing the use of macOS Terminal.app regardless of other installed emulators.
- **`windows-terminal`** – Loads [`windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/wezterm.sh)) that implements the required interface functions. Once the file exists, reference it via:

```bash
SWARMFORGE_TERMINAL=wezterm ./swarm

```

The [`swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.