How to Add a Custom Terminal Adapter for WezTerm or Alacritty in Swarm Forge

To add a custom terminal adapter in Swarm Forge, create an executable shell script in swarmforge/scripts/terminal-adapters/ that implements six required functions, then set the SWARM_TERMINAL_ADAPTER environment variable to point to your adapter.

Swarm Forge manages development sessions through pluggable terminal adapters that handle window lifecycle operations. If you use WezTerm, Alacritty, or another modern terminal emulator, you can add a custom terminal adapter to the unclebob/swarm-forge repository to integrate your preferred tool into the workflow. This guide walks through the exact function signatures and file locations needed to extend Swarm Forge's terminal support.

Understanding the Terminal Adapter Interface

Swarm Forge communicates with terminal emulators through a standardized shell interface defined in the adapter scripts. According to the source code in swarmforge/scripts/swarm-terminal-adapter.sh, every adapter must implement six specific functions that handle window detection, session attachment, and cleanup operations.

The required interface consists of:

• terminal_backend_label() – Returns a human-readable name for the adapter
• terminal_backend_can_open_sessions() – Returns exit code 0 if the adapter can launch new sessions
• terminal_backend_tracks_windows() – Returns exit code 0 if the adapter can locate windows after creation
• terminal_window_exists <window-id> – Checks if a specific window ID is still active
• terminal_open_session <session> <title> – Opens a new window or tab and attaches the specified tmux session
• terminal_close_window <window-id> – Gracefully closes the window created by the adapter

These functions enable Swarm Forge to orchestrate tmux sessions across different terminal emulators without hardcoding terminal-specific logic into the core application.

Step-by-Step: Adding a WezTerm Adapter

To add a custom terminal adapter for WezTerm, you will create a new script in the terminal adapters directory that leverages WezTerm's CLI capabilities.

Create the Adapter Script

Create a new file at swarmforge/scripts/terminal-adapters/wezterm.sh and make it executable:

chmod +x swarmforge/scripts/terminal-adapters/wezterm.sh

Implement the Required Functions

Copy the following implementation that uses WezTerm's cli commands to manage panes and sessions:

#!/usr/bin/env zsh

terminal_backend_label() { echo "WezTerm"; }

terminal_backend_can_open_sessions() { return 0; }

terminal_backend_tracks_windows() { return 0; }

terminal_window_exists() {
  local pane_id="$1"
  wezterm cli list-panes | grep -q "^${pane_id}\b"
}

terminal_open_session() {
  local session="$1"
  local title="$2"
  local pane_id=$(wezterm cli spawn \
    --cwd "$WORKING_DIR" \
    --title "$title" \
    --command "tmux -S $TMUX_SOCKET attach-session -t $session")
  echo "$pane_id"
}

terminal_close_window() {
  local pane_id="$1"
  wezterm cli close-pane "$pane_id"
}

This implementation uses wezterm cli spawn to create new panes and returns the pane ID for window tracking. The terminal_window_exists function checks the pane list to verify the window is still alive.

Register the Adapter

Set the environment variable to activate your custom adapter:

export SWARM_TERMINAL_ADAPTER=wezterm

The loader script swarmforge/scripts/swarm-terminal-adapter.sh will automatically locate wezterm.sh when this variable is set.

Step-by-Step: Adding an Alacritty Adapter

For Alacritty, the implementation differs slightly because Alacritty does not expose a window list through its CLI. Instead, you track the process ID (PID) of the spawned window.

Adapter Implementation for Alacritty

Create swarmforge/scripts/terminal-adapters/alacritty.sh with the following content:

#!/usr/bin/env zsh

terminal_backend_label() { echo "Alacritty"; }

terminal_backend_can_open_sessions() { return 0; }

terminal_backend_tracks_windows() { return 0; }

terminal_window_exists() {
  local win_id="$1"
  ps -p "$win_id" >/dev/null
}

terminal_open_session() {
  local session="$1"
  local title="$2"
  local pid=$(alacritty \
    --working-directory "$WORKING_DIR" \
    -e tmux -S "$TMUX_SOCKET" attach-session -t "$session")
  echo "$pid"
}

terminal_close_window() {
  local pid="$1"
  kill "$pid" 2>/dev/null
}

Since Alacritty does not provide a native window listing command, this adapter uses process IDs to track window existence. The terminal_open_session function spawns Alacritty with the tmux attach command and returns the process ID for later reference.

How the Loader Selects Your Adapter

The swarmforge/scripts/swarm-terminal-adapter.sh script acts as the bridge between Swarm Forge and your custom implementation. At runtime, it checks the SWARM_TERMINAL_ADAPTER environment variable to determine which adapter to load.

If the variable is not set, the loader defaults to terminal-app.sh. When you specify wezterm or alacritty, the loader searches for wezterm.sh or alacritty.sh in the swarmforge/scripts/terminal-adapters/ directory and sources the appropriate functions.

You can verify which adapter is active by checking the environment before starting Swarm Forge:

SWARM_TERMINAL_ADAPTER=wezterm ./swarmforge/scripts/swarmforge.sh start

Testing Your Custom Adapter

To verify your custom terminal adapter works correctly:

1. Create a test session using Swarm Forge's session commands
2. Check that a new terminal window opens with the correct title
3. Confirm the window attaches to the specified tmux session
4. Close the task and ensure terminal_close_window terminates the process without leaving orphan windows

For WezTerm, you can manually test the window tracking:

source swarmforge/scripts/terminal-adapters/wezterm.sh
pane_id=$(terminal_open_session "test-session" "Test Window")
terminal_window_exists "$pane_id" && echo "Window exists"
terminal_close_window "$pane_id"

Summary

• Swarm Forge uses a six-function interface defined in shell scripts to manage terminal windows
• Place custom adapters in swarmforge/scripts/terminal-adapters/ with names matching the SWARM_TERMINAL_ADAPTER variable
• WezTerm adapters can use wezterm cli commands to spawn and track panes by ID
• Alacritty adapters typically track windows by process ID since the emulator lacks a window listing API
• The loader script swarmforge/scripts/swarm-terminal-adapter.sh automatically sources the correct adapter based on the environment variable

Frequently Asked Questions

What functions must a terminal adapter implement?

Every terminal adapter must implement six functions: terminal_backend_label for identification, terminal_backend_can_open_sessions and terminal_backend_tracks_windows for capability reporting, terminal_window_exists for lifecycle checks, terminal_open_session for creating windows and attaching tmux sessions, and terminal_close_window for cleanup.

Where should I place my custom terminal adapter script?

Place your executable shell script in the swarmforge/scripts/terminal-adapters/ directory. The filename should match the value you plan to use for the SWARM_TERMINAL_ADAPTER environment variable (e.g., wezterm.sh for SWARM_TERMINAL_ADAPTER=wezterm).

How does Swarm Forge choose which terminal adapter to use?

The swarmforge/scripts/swarm-terminal-adapter.sh loader script reads the SWARM_TERMINAL_ADAPTER environment variable at runtime. If set to wezterm, it loads wezterm.sh from the adapters directory. If unset, it falls back to the default terminal-app.sh adapter.

Can I use the same adapter for multiple terminal emulators?

No, each terminal emulator requires its own adapter script because the command-line APIs differ significantly between terminals. However, you can copy and modify existing adapters like iterm2.sh or ghostty.sh from the swarmforge/scripts/terminal-adapters/ directory as templates for new implementations.

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