# How to Override the Default Terminal Backend in SwarmForge

> Learn how to override the default terminal backend in SwarmForge by setting the SWARMFORGE_TERMINAL environment variable. Force your preferred terminal emulator for seamless workflows.

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

---

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

```sh
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`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh) | macOS Terminal.app via AppleScript |
| `windows-terminal` | [`windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/windows-terminal.sh) | Windows Terminal (`wt.exe`) |
| `ghostty` | [`ghostty.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

```sh

# 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:

```sh

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

```sh
export SWARMFORGE_TERMINAL=ghostty
export SWARMFORGE_TERMINAL_BACKEND=ghostty
./swarm

```

## Complete Configuration Examples

```sh

# 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh)** — Core detection and adapter loading
- **[`swarmforge/scripts/swarm-cleanup.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-cleanup.sh)** — Backend selection during teardown
- **[`swarmforge/scripts/terminal-adapters/ghostty.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/ghostty.sh)** — Ghostty adapter implementation
- **[`swarmforge/scripts/terminal-adapters/terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/terminal-app.sh)** — macOS Terminal.app adapter
- **[`swarmforge/scripts/terminal-adapters/windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.