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

[psmux]

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:

1. process.stdout.isTTY is undefined under Bun SFE on Windows, which forces in-process mode regardless of teammateMode: "tmux" settings (tracked in Split-pane agent teams blocked on Windows by isTTY gate overriding teammateMode: "tmux" #26244, stale).
2. No native tmux binary exists — users must either run inside WSL (losing native PowerShell/cmd access) or go without agent teams entirely.
3. 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

1. 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.

2. 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.

3. 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.

4. 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.

5. 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

• Split-pane agent teams blocked on Windows by isTTY gate overriding teammateMode: "tmux" #26244 — isTTY gate blocker (stale, narrow scope)
• [FEATURE] Add Windows Terminal as a split-pane backend for agent teams (teammateMode) #24384 — Windows Terminal native split-pane backend request
• [Bug] tmux pane spawning fails in GitBash with tmux enabled #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.

Links

• psmux repo: https://github.com/queil/psmux
• psmux Claude Code integration docs: https://github.com/queil/psmux/blob/master/docs/claude-code.md
• psmux tmux command reference: https://github.com/queil/psmux/blob/master/docs/tmux_args_reference.md

[github-actions]

Found 3 possible duplicate issues:

1. Split-pane agent teams blocked on Windows by isTTY gate overriding teammateMode: "tmux" #26244
2. [FEATURE] Add Windows Terminal as a split-pane backend for agent teams (teammateMode) #24384
3. [FEATURE] Agent Teams: add Windows Terminal split pane support #31297

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[psmux]

This is not a duplicate. Let me clarify the distinction from each flagged issue:

vs #26244 (isTTY gate blocker)

#26244 is a narrow bug report about process.stdout.isTTY being undefined in the Bun SFE on Windows. This issue references that as one of several small blockers, but its scope is much broader: it proposes officially supporting tmux-compatible multiplexers on Windows as first-class agent team backends, with psmux as the concrete, production-ready implementation that already exists. #26244 identifies a symptom; this issue proposes the full solution.

vs #24384 (Windows Terminal native split-pane backend)

#24384 proposes building an entirely new backend using the wt.exe CLI (wt -w 0 sp -H). That's a significant engineering effort — a new WindowsTerminalBackend with its own spawn/query/kill logic, format parsing, and lifecycle management. This issue proposes the opposite approach: reuse the existing TmuxBackend as-is, because psmux already speaks the tmux command protocol (76 commands, same flags, same format strings). The changes needed in Claude Code are minimal detection/gating fixes, not a new backend.

vs #31297 (closed — also WT split pane)

#31297 is the same idea as #24384 (Windows Terminal wt CLI splits) and was closed. Same distinction applies: this issue is about leveraging the existing tmux backend through a compatible Windows multiplexer, not building a new one.

Why this is distinct and higher-value

The key insight is: psmux already implements the exact tmux command surface that Claude Code's TmuxBackend uses (split-window, send-keys, kill-pane, list-panes, has-session, display-message — all with matching flags and format strings). It already sets TMUX, TMUX_PANE, and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 on every pane spawn. The integration path is 2-3 small fixes to detection logic, not a new backend.

The psmux maintainer is actively willing to collaborate on any compatibility work needed on the psmux side.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.