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

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:

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:

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:

sudo apt install tmux

According to the source code in 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 (lines 38-44), the isTmuxAvailable() function probes for tmux by executing tmux -V. On native Windows, 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 initiates the startup sequence.
2. Capability Validation: createTeamSession() in 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:

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 example for psmux

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

Usage Example

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

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

# 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 and 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, 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 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 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 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 lines 92-106) and continues execution without the HUD pane and window management features, effectively running in a degraded single-pane mode.

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