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

> Easily add a custom terminal adapter for WezTerm or Alacritty in Swarm Forge. Create an executable script and set the SWARM_TERMINAL_ADAPTER environment variable for seamless integration.

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

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/wezterm.sh) and make it executable:

```bash
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:

```sh
#!/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:

```bash
export SWARM_TERMINAL_ADAPTER=wezterm

```

The loader script [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm-terminal-adapter.sh) will automatically locate [`wezterm.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/terminal-adapters/alacritty.sh) with the following content:

```sh
#!/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh). When you specify `wezterm` or `alacritty`, the loader searches for [`wezterm.sh`](https://github.com/unclebob/swarm-forge/blob/main/wezterm.sh) or [`alacritty.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
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:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/wezterm.sh) for `SWARM_TERMINAL_ADAPTER=wezterm`).

### How does Swarm Forge choose which terminal adapter to use?

The [`swarmforge/scripts/swarm-terminal-adapter.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/wezterm.sh) from the adapters directory. If unset, it falls back to the default [`terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/iterm2.sh) or [`ghostty.sh`](https://github.com/unclebob/swarm-forge/blob/main/ghostty.sh) from the `swarmforge/scripts/terminal-adapters/` directory as templates for new implementations.