# How to Configure tmux and psmux for Team Mode in oh-my-codex

> Configure tmux or psmux for oh-my-codex team mode on macOS, Linux, Windows, or WSL2. Install the correct binary, add to PATH, and start collaborating with ease.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: how-to-guide
- Published: 2026-04-03

---

**To configure tmux or psmux for team mode in oh-my-codex, install the appropriate binary for your platform—tmux for macOS, Linux, or WSL2, or psmux for native Windows—and ensure it is available on your system PATH before running any `omx team` command.**

oh-my-codex implements a durable team runtime that drives interactive worker panes inside a **tmux** session. On native Windows where tmux cannot run, the project transparently falls back to **psmux**, a Windows-compatible tmux-API shim that emulates the command-line interface, allowing the team machinery to function without modification.

## Platform-Specific Installation Requirements

The only configuration required is installing the correct backend for your operating system and verifying it is accessible on your PATH.

### macOS

Install tmux via Homebrew:

```bash
brew install tmux

```

### Linux Distributions

- **Ubuntu / Debian**: `sudo apt install tmux`
- **Fedora**: `sudo dnf install tmux`
- **Arch Linux**: `sudo pacman -S tmux`

### Native Windows

For native Windows environments (not WSL2), install **psmux** using Windows Package Manager or manually:

```bash
winget install psmux

```

Alternatively, download the binary from https://github.com/marlocarlo/psmux and add its directory to your system PATH.

### Windows with WSL2

If running inside a WSL2 distribution, install tmux within the Linux environment:

```bash
sudo apt install tmux

```

According to the source code in [`src/team/tmux-session.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/team/tmux-session.ts), the function `isWsl2()` detects this environment, causing `isNativeWindows()` to return false and allowing standard tmux detection to apply.

## How oh-my-codex Detects the Runtime

The detection logic resides in two primary files. In [`src/team/tmux-session.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/team/tmux-session.ts) (lines 38-44), the `isTmuxAvailable()` function probes for tmux by executing `tmux -V`. On native Windows, [`src/cli/index.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts) (lines 92-106) implements `launchWithHud()`, which explicitly checks for Windows via `isNativeWindows()` and handles the fallback to psmux when tmux is not found.

The detection flow follows this priority:

1. **WSL2 Check**: If `isWsl2()` returns true, the environment is treated as Linux regardless of the Windows host.
2. **Native Windows Check**: If `isNativeWindows()` returns true and `tmux -V` fails, the CLI prints a warning and continues using psmux.
3. **Standard tmux Check**: On macOS and Linux, `isTmuxAvailable()` validates the tmux binary before `createTeamSession()` is invoked.

## Launching a Team Session

Once the backend is installed, starting a team session requires no additional configuration files. The architectural flow implemented in the source code handles session creation automatically:

1. **CLI Entry Point**: `launchWithHud()` in [`src/cli/index.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts) initiates the startup sequence.
2. **Capability Validation**: `createTeamSession()` in [`src/team/tmux-session.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/team/tmux-session.ts) throws an error if tmux is unavailable; the CLI catches this and emits a warning on Windows.
3. **Session Construction**: The function builds a leader pane, splits worker panes vertically, registers resize hooks, and optionally spawns a HUD pane using standard tmux commands (or psmux equivalents on Windows).

## Verifying Your Configuration

Confirm the binary is accessible before launching a team:

```bash
tmux -V

```

Expected output shows the version (e.g., `tmux 3.3a`). If you receive a "command not found" error on Windows, update your PATH:

```powershell

# PowerShell example for psmux

$env:Path += ";C:\Program Files\psmux"

```

## Usage Example

Launch a team named "demo" with three executor workers:

```bash
omx team 3:executor "run the demo plan in parallel"

```

If you are on native Windows without tmux installed, the CLI outputs the following warning defined in [`src/cli/index.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts) (lines 92-106):

```

[omx] warning: tmux was not found on native Windows. Continuing without tmux/HUD.
[omx] To enable tmux-backed features, install psmux:
[omx]   winget install psmux
[omx] See: https://github.com/marlocarlo/psmux

```

## Manual Session Management (Optional)

For advanced use cases requiring custom layouts, pre-create a tmux session and attach `omx` to it:

```bash

# Create detached session

tmux new-session -s omx-team-demo -d

# Start the HUD watcher (optional)

tmux send-keys -t omx-team-demo:0 'omx hud --watch' C-m

# Execute team command within the session

tmux send-keys -t omx-team-demo:0 'omx team 3:executor "my task"' C-m

```

This approach bypasses automatic session creation while maintaining full compatibility with the team runtime.

## Summary

- **Install the correct binary**: Use tmux on macOS, Linux, and WSL2; use psmux on native Windows.
- **Validate PATH availability**: The functions `isTmuxAvailable()` and `isNativeWindows()` require the binary to be executable without absolute paths.
- **No configuration files needed**: oh-my-codex detects capabilities automatically via [`src/team/tmux-session.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/team/tmux-session.ts) and [`src/cli/index.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts).
- **Graceful degradation**: On native Windows without psmux, the system warns but continues, though HUD features require the backend.

## Frequently Asked Questions

### What is the difference between tmux and psmux in oh-my-codex?

**tmux** is the standard terminal multiplexer used on POSIX platforms to create durable team sessions with split panes. **psmux** is a Windows-compatible shim that implements the tmux command-line API, enabling the same `omx team` functionality on native Windows where tmux cannot run. According to [`docs/release-notes-0.8.7.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/release-notes-0.8.7.md), psmux support was added specifically to enable Windows compatibility without modifying the core team logic.

### How does oh-my-codex detect which backend to use?

The detection chain in [`src/team/tmux-session.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/team/tmux-session.ts) first checks `isWsl2()` to identify Windows Subsystem for Linux (which uses standard tmux). If false, `isNativeWindows()` identifies native Windows environments. On native Windows, `launchWithHud()` in [`src/cli/index.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts) attempts `tmux -V`; upon failure, it prints a warning and proceeds assuming psmux is available. On all other platforms, `isTmuxAvailable()` validates the tmux binary directly.

### Can I use standard tmux on Windows with oh-my-codex?

**Only inside WSL2**. The source code explicitly differentiates between `isWsl2()` (true) and `isNativeWindows()` (true). When running inside a WSL2 distribution, the environment is treated as Linux, and standard tmux installation and detection apply. Native Windows CMD or PowerShell sessions require psmux, as tmux relies on POSIX APIs unavailable in native Windows.

### What happens if I run `omx team` without installing the backend?

On macOS or Linux, `createTeamSession()` in [`src/team/tmux-session.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/team/tmux-session.ts) throws an error that prevents execution if `isTmuxAvailable()` returns false. On native Windows, the CLI emits a warning message (as implemented in [`src/cli/index.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts) lines 92-106) and continues execution without the HUD pane and window management features, effectively running in a degraded single-pane mode.