Support tmux agent teams on Windows via psmux (native Windows terminal multiplexer)

Resolved 💬 4 comments Opened Mar 13, 2026 by psmux Closed Apr 10, 2026

Summary

Windows users are completely locked out of Claude Code's agent teams (teammate mode) because the TmuxBackend requires Linux/macOS tmux, which doesn't exist natively on Windows. psmux is a production-ready, native Windows terminal multiplexer written in Rust that speaks the tmux command protocol — and it already sets the exact environment variables Claude Code checks for. With a small compatibility effort, agent teams could work on Windows today.

The Problem

Claude Code's agent team architecture relies on tmux for split-pane teammate spawning (split-window, send-keys, kill-pane, list-panes, has-session, display-message). On Windows:

process.stdout.isTTY is undefined under Bun SFE on Windows, which forces in-process mode regardless of teammateMode: "tmux" settings (tracked in #26244, stale).
No native tmux binary exists — users must either run inside WSL (losing native PowerShell/cmd access) or go without agent teams entirely.
Worktree agents (isolation: "worktree") also fall back to in-process on Windows, meaning Windows users get zero visible agent orchestration.

This affects every Windows user of Claude Code who wants to use agent teams — a significant portion of the user base.

The Solution: psmux

psmux is a native Windows terminal multiplexer (25,600 lines of Rust) that implements 76 tmux commands with flag-level compatibility. It's not a wrapper or shim — it's a ground-up implementation using Windows ConPTY directly.

It already speaks Claude Code's language

psmux implements every tmux command that TmuxBackend uses:

| Claude Code uses | psmux support | Notes |
|---|---|---|
| tmux -V | ✅ | Returns version string |
| split-window -h/-v -c <dir> | ✅ | Full flag support including -F, -l, -p |
| send-keys | ✅ | Text injection into panes |
| kill-pane -t | ✅ | Target pane termination |
| display-message -p -F | ✅ | 126+ format variables |
| list-panes -F | ✅ | Format string output |
| has-session -t | ✅ | Exit code 0/1 |
| list-windows | ✅ | Full format support |

It already sets the right environment variables

On every pane spawn (5 call sites, no code path missed), psmux sets:

TMUX=/tmp/psmux-{pid}/{socket},{port},0
TMUX_PANE=%{id}
PSMUX_SESSION={name}
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Claude Code's detection (process.env.TMUX non-empty → tmux mode) already triggers correctly inside psmux sessions.

It's production-ready

Performance: <100ms session creation, <80ms pane splits (warm session pooling)
Stability: Stress-tested with 15+ windows, 18+ panes, 5 concurrent sessions
Shell support: PowerShell 7, PowerShell 5, cmd.exe, Git Bash, WSL, Nushell — all in the same session
Distribution: Available via winget, scoop, chocolatey, and cargo
Config compatibility: Reads .tmux.conf directly — existing tmux configs work as-is
Full mouse support: Click panes, drag-resize borders, scroll
Zero dependencies: Single binary, no WSL/Cygwin/MSYS2 required

What needs to change in Claude Code

The blockers are small and well-understood:

1. Fix the `isTTY` gate on Windows (#26244)

Under Bun SFE on Windows, process.stdout.isTTY is undefined, which causes the teammate mode selection to always fall through to in-process. This gate should either:

Check for TMUX env var presence as an override, or
Treat undefined differently from false on Windows

2. Accept psmux as a valid tmux provider

psmux's tmux -V returns a version string. If Claude Code's version parsing expects GNU tmux's exact format, a small normalization may be needed. Alternatively, detecting PSMUX_SESSION as a secondary signal would work.

3. (Optional) Support worktree agents via psmux

Currently worktree agents are hardcoded to in-process on Windows. Since psmux can spawn isolated panes with custom working directories (split-window -c <worktree-path>), worktree isolation could work through psmux too.

Why this matters for Claude Code

Windows is a first-class platform for Claude Code — but agent teams, one of its most powerful features, simply don't work there. This is a significant feature gap.

No WSL tax: Users shouldn't have to run inside WSL (and lose native Windows shell access) just to get agent teams. psmux gives native PowerShell + cmd + Git Bash + WSL all in one session.

Visible agent orchestration: Teammate agents in tmux panes let users see what each agent is doing in real-time. The in-process fallback gives zero visibility.

The hard work is done: psmux already implements the tmux protocol surface that Claude Code needs. The integration path is small changes to Claude Code's detection/gating logic, not a new backend.

Active maintainer willing to collaborate: The psmux project is actively developed and the maintainer is willing to support whatever compatibility work is needed on the psmux side to make agent teams work seamlessly on Windows.

Related issues

#26244 — isTTY gate blocker (stale, narrow scope)
#24384 — Windows Terminal native split-pane backend request
#23675 — tmux pane spawning failures in Git Bash on Windows

This issue supersedes #26244 with a broader scope: not just fixing the isTTY gate, but officially supporting tmux-compatible multiplexers on Windows as first-class agent team backends.