How to Override Automatic Terminal Detection Using SWARMFORGE_TERMINAL Environment Variable

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. 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
terminal, terminal-app	terminal-app	terminal-app.sh
windows, windows-terminal	windows-terminal	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:

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

# ~/.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, windows-terminal.sh, 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. 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:

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

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