# How to Override Automatic Terminal Detection Using SWARMFORGE_TERMINAL Environment Variable

> Override Swarm-Forge terminal detection with SWARMFORGE_TERMINAL. Set this environment variable before running swarm to control terminal backend selection.

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

---

**Set the `SWARMFORGE_TERMINAL` environment variable to any supported backend name before running the `swarm` command to bypass automatic terminal detection in Swarm‑Forge.**

The Swarm‑Forge CLI automatically detects which terminal emulator you're running, but you can force a specific backend by defining this variable. This is useful when running under complex shell environments, remote sessions, or when you prefer a different adapter than the auto-detected one.

## How Terminal Detection Works in Swarm‑Forge

Swarm‑Forge determines which terminal adapter to load through the `detect_terminal_backend` function in [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh). According to the unclebob/swarm-forge source code, this function follows a simple priority:

1. Check if `SWARMFORGE_TERMINAL` is set — if yes, use that value immediately
2. Otherwise, probe the environment to guess the terminal type
3. Normalize the result and load the corresponding adapter script

The detection short-circuit happens at lines 28-31 of the adapter script. When `SWARMFORGE_TERMINAL` contains any non-empty value, that value is passed to `normalize_terminal_backend` and returned directly, skipping all automatic probing.

## Supported Backend Values

The `normalize_terminal_backend` function (lines 6-24) maps various aliases to canonical backend names. You can use any of these values with `SWARMFORGE_TERMINAL`:

| Value you set | Canonical backend | Adapter script loaded |
|-------------|-------------------|----------------------|
| `iterm2`, `iterm` | `iterm2` | [`iterm2.sh`](https://github.com/unclebob/swarm-forge/blob/main/iterm2.sh) |
| `terminal`, `terminal-app` | `terminal-app` | [`terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh) |
| `windows`, `windows-terminal` | `windows-terminal` | [`windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/windows-terminal.sh) |
| `none`, `disabled` | `none` | no adapter (fallback) |

The comparison is **case-insensitive**, so `ITERM2` and `iterm2` work identically.

## Usage Examples

### One-off override (inlined)

Prefix your `swarm` command with the variable assignment:

```bash

# Force iTerm2 integration

SWARMFORGE_TERMINAL=iterm2 ./swarm deploy my-cluster

# Use generic Terminal.app on macOS

SWARMFORGE_TERMINAL=terminal-app ./swarm status

# Windows Terminal under WSL

SWARMFORGE_TERMINAL=windows-terminal ./swarm logs

# Disable all terminal-specific features

SWARMFORGE_TERMINAL=none ./swarm shell

```

### Persistent configuration

Export the variable in your shell profile to apply the override to every Swarm‑Forge invocation:

```bash

# ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish

export SWARMFORGE_TERMINAL=ghostty

```

After reloading your profile (`source ~/.zshrc`), all `swarm` commands will use your specified backend automatically.

## Where Adapter Scripts Are Loaded

Once the backend is determined, the `load_terminal_backend` function (lines 52-60) sources the appropriate adapter from `swarmforge/scripts/terminal-adapters/`. Each adapter implements terminal-specific features like:

- Dynamic window titles
- Progress notifications
- Badge updates
- Shell integration hooks

The adapter filenames match the canonical backend names: [`iterm2.sh`](https://github.com/unclebob/swarm-forge/blob/main/iterm2.sh), [`windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/windows-terminal.sh), [`terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh), and so on.

## Troubleshooting Common Issues

### Backend not recognized

If you set `SWARMFORGE_TERMINAL` to an unknown value, `normalize_terminal_backend` returns it unchanged. The `load_terminal_backend` function then attempts to source [`terminal-adapters/YOURVALUE.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-adapters/YOURVALUE.sh). If that file doesn't exist, you'll see a warning and Swarm‑Forge falls back to the `none` backend.

### Check your current effective backend

Run with verbose logging to see which adapter is actually loaded:

```bash
SWARMFORGE_TERMINAL=iterm2 ./swarm --verbose version

```

Look for lines mentioning `terminal-adapter` in the output.

## Summary

- The `SWARMFORGE_TERMINAL` environment variable overrides all automatic terminal detection in Swarm‑Forge
- Set it to any supported alias or canonical backend name before running `swarm`
- The value is case-insensitive and normalized through `normalize_terminal_backend` in [`swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm-terminal-adapter.sh)
- Use `none` to disable terminal-specific features entirely
- For permanent configuration, export the variable in your shell profile

## Frequently Asked Questions

### What happens if I set SWARMFORGE_TERMINAL to an invalid value?

The `load_terminal_backend` function attempts to load `terminal-adapters/<value>.sh`. If the file doesn't exist, Swarm‑Forge emits a warning and proceeds with no terminal adapter loaded — equivalent to setting `SWARMFORGE_TERMINAL=none`. Your commands still execute; you simply don't get terminal-specific integrations.

### Can I use SWARMFORGE_TERMINAL with any terminal emulator?

You can only use values mapped by `normalize_terminal_backend` or existing adapter scripts in `terminal-adapters/`. The built-in mappings cover iTerm2, Terminal.app, Windows Terminal, and disabling adapters. To add a new terminal, you must create a new adapter script and optionally extend the normalization function.

### Does this variable affect remote SSH sessions?

Yes. `SWARMFORGE_TERMINAL` is read from your environment on the machine where `swarm` executes. If you SSH into a server and run Swarm‑Forge there, set the variable on that remote shell. It does not propagate from your local terminal unless you explicitly forward environment variables.

### Why would I want to disable terminal detection with `none`?

Set `SWARMFORGE_TERMINAL=none` when running Swarm‑Forge in CI/CD pipelines, containerized environments, or subshells where terminal features cause errors or unnecessary overhead. This prevents the tool from attempting OSC escape sequences or proprietary APIs that may misbehave in non-interactive contexts.