# How to Override Terminal Detection in Swarm-Forge Using the SWARMFORGE_TERMINAL Environment Variable

> Override terminal detection in Swarm Forge by setting the SWARMFORGE_TERMINAL environment variable. Force a specific terminal adapter for your swarm command and bypass automatic detection.

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

---

**Set the `SWARMFORGE_TERMINAL` environment variable to any supported backend alias before running the `swarm` command to bypass automatic detection and force a specific terminal adapter.**

Swarm-Forge automatically detects your terminal emulator to load the appropriate integration scripts, but you can override this behavior using the **SWARMFORGE_TERMINAL environment variable**. This override is implemented in the `detect_terminal_backend` function within the terminal adapter script, allowing you to force a specific backend or disable terminal-specific handling entirely. Whether you are running under WSL, using a niche terminal, or need to suppress terminal integrations, this environment variable provides direct control over which adapter Swarm-Forge loads.

## How Terminal Detection Works by Default

By default, Swarm-Forge attempts to identify your terminal emulator through platform-specific heuristics implemented 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 inspects environment variables like `$TERM_PROGRAM` and other indicators to determine whether you are running in iTerm2, Terminal.app, Windows Terminal, or another supported emulator. Once identified, the system calls `load_terminal_backend` (lines 52-60) to source the corresponding adapter script from the `terminal-adapters` directory.

## Overriding Detection with SWARMFORGE_TERMINAL

To **override terminal detection**, export or prefix the `SWARMFORGE_TERMINAL` variable with your desired backend identifier. When this variable is non-empty, the detection logic short-circuits immediately (lines 28-31), skipping automatic discovery and passing your value directly to `normalize_terminal_backend`.

### Supported Backend Aliases

The `normalize_terminal_backend` function (lines 6-24) maps user-friendly aliases to canonical backend names:

- `iterm`, `iterm2` → `iterm2`
- `terminal`, `terminal-app` → `terminal-app`
- `windows`, `windows-terminal` → `windows-terminal`
- `none` → `none` (disables terminal-specific handling)
- `ghostty` → `ghostty` (and other emerging terminals)

Aliases are case-insensitive, so `ITERM2` and `iterm2` are treated identically.

### Usage Examples

Force Swarm-Forge to use iTerm2:

```bash
SWARMFORGE_TERMINAL=iterm2 ./swarm

```

Use Windows Terminal when running under WSL:

```bash
SWARMFORGE_TERMINAL=windows-terminal ./swarm

```

Disable all terminal-specific integrations:

```bash
SWARMFORGE_TERMINAL=none ./swarm

```

For persistent configuration across sessions, add the export to your shell profile:

```bash

# ~/.bashrc, ~/.zshrc, or ~/.bash_profile

export SWARMFORGE_TERMINAL=ghostty

```

## Implementation Details

According to the unclebob/swarm-forge source code, the override mechanism is straightforward but robust. In [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh), the detection logic at lines 28-31 checks if `SWARMFORGE_TERMINAL` is set:

```bash

# Conceptual representation of the logic at lines 28-31

if [[ -n "$SWARMFORGE_TERMINAL" ]]; then
    normalize_terminal_backend "$SWARMFORGE_TERMINAL"
    return
fi

```

If set, the value is passed to `normalize_terminal_backend`, which sanitizes the input and maps it to a canonical name (lines 6-24). The normalized name determines which script from the `terminal-adapters` directory gets sourced. For example, setting `SWARMFORGE_TERMINAL=iterm2` causes the system to load [`terminal-adapters/iterm2.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-adapters/iterm2.sh).

The README.md (lines 266-272) documents this feature with practical examples, confirming that this is the supported method for manual terminal selection.

## Summary

- **SWARMFORGE_TERMINAL** is the environment variable that overrides Swarm-Forge's automatic terminal detection.
- Set it to any supported alias (`iterm2`, `terminal-app`, `windows-terminal`, `none`, etc.) to force a specific backend.
- The override is processed in [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh) at lines 28-31, short-circuiting the detection logic.
- Values are case-insensitive and normalized through the `normalize_terminal_backend` function.
- Use `export SWARMFORGE_TERMINAL=none` to disable terminal-specific handling entirely.

## Frequently Asked Questions

### What values can I use with SWARMFORGE_TERMINAL?

You can use any recognized backend alias such as `iterm2`, `terminal-app`, `windows-terminal`, `ghostty`, or `none`. The `normalize_terminal_backend` function in [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh) (lines 6-24) maps these aliases to canonical identifiers. The value is case-insensitive, so `Windows-Terminal` and `windows-terminal` work identically.

### How do I permanently set SWARMFORGE_TERMINAL for all Swarm-Forge sessions?

Add `export SWARMFORGE_TERMINAL=your-backend` to your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`). This ensures the variable is present in every new shell session, consistently overriding automatic detection without requiring manual prefixing of each command.

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

If you provide an unrecognized value, the `normalize_terminal_backend` function will likely fall back to a default behavior or return the input unchanged, which may result in Swarm-Forge attempting to load a non-existent adapter script from the `terminal-adapters` directory. To avoid errors, use only documented backends like `iterm2`, `terminal-app`, `windows-terminal`, or `none`.

### Can I use SWARMFORGE_TERMINAL to disable terminal integrations completely?

Yes. Set `SWARMFORGE_TERMINAL=none` to bypass all terminal-specific handling. This forces Swarm-Forge to skip loading any adapter scripts from the `terminal-adapters` directory, effectively running in a generic mode without terminal-specific features.