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

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

SWARMFORGE_TERMINAL=iterm2 ./swarm

Use Windows Terminal when running under WSL:

SWARMFORGE_TERMINAL=windows-terminal ./swarm

Disable all terminal-specific integrations:

SWARMFORGE_TERMINAL=none ./swarm

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

# ~/.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, the detection logic at lines 28-31 checks if SWARMFORGE_TERMINAL is set:

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

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 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 (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.

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