[FEATURE] Add Windows Terminal as a split-pane backend for agent teams (teammateMode)

+1 for this... i think this would be very helpful for Windows users

+1 because it is almost impossible to use Agent Team otherwise.
Feel free to read this page : https://learn.microsoft.com/en-us/windows/terminal/panes
Regards

+1 for this and very helpful feature for windows users

+1 for this - I like to see what's going on in the agents

Native Windows solution found: psmux + compatibility shim

This issue requests Windows Terminal support for agent team split panes. While that would be ideal, I wanted to share a working alternative that I got running today on native Windows — without WSL.

What works

psmux is a Rust-based native Windows tmux clone. It sets $TMUX inside its panes, so Claude Code detects it as tmux. With a thin compatibility shim, full split-pane agent teams work on Windows:

psmux session
┌────────────────────────┬─────────────────────────────┐
│ Pane 1  @alpha (Lead)  │ Pane 2  @bravo (Teammate 1) │
│ Claude Code v2.1.50    │ Claude Code v2.1.50          │
├────────────────────────┴─────────────────────────────┤
│ Pane 3  @bravo (Teammate 2)                          │
│ Claude Code v2.1.50                                  │
└──────────────────────────────────────────────────────┘

Three incompatibilities fixed by the shim

| Issue | Symptom | Fix |
|-------|---------|-----|
| tmux -V launches psmux TUI | Claude Code hangs on startup | Shim returns "tmux 3.4" instantly |
| Format vars (#{window_panes} etc.) return empty inside panes | "Could not determine pane count" | Shim intercepts and returns correct values |
| psmux session must be named default | IPC fails for other session names | Name the session default |

Shim (bash, for Git Bash / MSYS2)

#!/bin/bash
PSMUX_SESSION="${PSMUX_SESSION_NAME:-default}"
case "$1" in
  -V)
    echo "tmux 3.4"; exit 0 ;;
  display-message)
    # parse -p format arg and return correct value via psmux / env vars
    ...
    exec psmux "$@" ;;
  *)
    exec psmux "$@" ;;
esac

A tmux.cmd version for PowerShell/CMD is also needed since PowerShell can't execute bash shebangs.

Full details

• Repo: https://github.com/gonnector/claude-psmux-team
• How it works: https://github.com/gonnector/claude-psmux-team/blob/master/docs/how-it-works.md
• psmux issue filed: marlocarlo/psmux#42

Suggestions for Claude Code

1. Add psmux detection: if (process.env.PSMUX_SESSION) return 'psmux' — once psmux sets its own env var
2. Timeout on tmux -V: If version check takes >2s, fall back to in-process mode gracefully instead of hanging
3. Windows Terminal backend: Still the cleanest long-term solution for Windows users without psmux

This was tested on Windows 11 with psmux v0.3.9 and Claude Code v2.1.50. To my knowledge, this is the first native Windows (non-WSL) agent team split-pane solution.

Follow-up: Testing Complete — 3 teammates spawned successfully on Windows via psmux

Continuing from my earlier comment.

After additional debugging, all 3 shim issues are now resolved and 3 teammates spawn and complete tasks successfully on native Windows (no WSL).

What was fixed in the shim

| Bug | Root cause | Fix |
|-----|------------|-----|
| split-window crashed psmux TUI | psmux %* caused CMD to re-expand %1 (pane ID literal) as batch arg 1, giving psmux -t split-window (invalid target) | Use positional args %~3 + default: session prefix |
| send-keys/kill-pane failed with no server running on session '' | psmux can't resolve bare pane IDs (%2) without session context | Rewrite -t %N → -t default:%N |
| split-window stdout lost | Redirecting all output to log prevented Claude Code from reading the new pane ID | Redirect only stderr (2>> log) |

New finding: only 1 split pane created for all teammates

During testing I observed that Claude Code calls split-window only once regardless of the number of teammates requested. All teammates share a single right-side pane and run sequentially:

Current (psmux on Windows, likely also tmux on macOS?):
┌──────────────────────────┬───────────────────────────────┐
│ Pane 1  Lead             │ Pane 2  Teammates (cycling)   │
│ orchestrating            │ @alpha → completes            │
│                          │ @beta  → completes            │
│                          │ @gamma → completes            │
└──────────────────────────┴───────────────────────────────┘

Expected (for true parallel monitoring):
┌──────────┬──────────┬──────────┬──────────┐
│  Lead    │  @alpha  │  @beta   │  @gamma  │
│  Pane 1  │  Pane 2  │  Pane 3  │  Pane 4  │
└──────────┴──────────┴──────────┴──────────┘

Request: Could Claude Code call split-window once per teammate rather than once for all teammates? This would allow users to monitor all agents simultaneously — which is the primary visual benefit of split-pane mode.

Verified with: Windows 11, psmux v0.3.9, Claude Code v2.1.50, Opus 4.6, 3 teammates.

Shim source: https://github.com/gonnector/claude-psmux-team

+1 this would be extremely useful for developers on Windows

psmux maintainer here -- wanted to provide an update since @gonnector's excellent shim work was done against v0.3.9.

psmux is now at v0.4.10 (releases) and several of the incompatibilities that required the shim have been fixed upstream:

What changed since v0.3.9

| Issue | Status | Details |
|-------|--------|---------|
| tmux -V launched TUI instead of printing version | Fixed (closed #42) | psmux -V / tmux -V now prints version string and exits |
| Format variables returned empty | Improved | 126+ format variables supported (#{pane_id}, #{window_panes}, #{session_name}, etc.) |
| capture-pane -p | Supported | Full pane content capture |
| send-keys | Supported | Including -t session:window.pane targeting |
| list-panes -F | Supported | Format string output |
| split-window | Supported | Both -h (horizontal) and -v (vertical) |
| display-message -p with format vars | Supported | Resolves format variables and prints to stdout |

Current state of Claude Code agent teams on Windows

With psmux v0.4.10, the shim may be significantly simpler or possibly unnecessary for basic agent team functionality. psmux sets $env:TMUX inside its panes, so Claude Code's tmux auto-detection works.

The remaining gap for full parity is mostly on the Claude Code side:

1. Version check timeout -- if tmux -V ever hangs (shouldn't with v0.4.10, but a timeout fallback would be defensive)
2. psmux as a first-class detection target -- if (process.env.PSMUX_SESSION) return 'psmux' alongside the existing tmux/iTerm2 detection
3. One pane per teammate -- as @gonnector noted, Claude Code currently reuses a single split pane for all teammates rather than creating one per teammate

Install

winget install psmux

Also available via cargo install psmux, Scoop, and Chocolatey. Ships psmux.exe, pmux.exe, and tmux.exe aliases.

For Claude Code team

Adding psmux detection would be a small change. psmux sets these env vars inside its sessions:

• TMUX -- already detected by your tmux backend
• PSMUX_SESSION -- psmux-specific, could be used for explicit detection
• TMUX_PANE -- pane ID, same as tmux

Since psmux speaks the tmux command protocol, the existing tmux backend code should work with little to no modification. The 76 implemented commands cover the subset Claude Code uses (new-session, split-window, send-keys, list-panes, kill-pane, display-message, -V).

v0.4.10 Test Results & Remaining Gaps

Following up on @marlocarlo's update — I tested psmux v0.4.10 with Claude Code v2.1.71 on native Windows (Git Bash / MSYS2, no WSL).

What works natively

All 5 tmux commands that previously required the full shim now work without modification:

| Command | Result |
|---------|--------|
| tmux -V | Prints version and exits (no TUI) |
| display-message -p '#{session_name}' | Returns default |
| list-panes -F '#{pane_id}' | Returns %1 |
| split-window -h -l 70% -P -F '#{pane_id}' | Returns %2 (split created) |
| send-keys -t %2 "echo test" Enter | Command delivered to pane |

Remaining issues found

1. tmux -V returns "tmux 0.4.10" — fails Claude Code's version check

Claude Code parses the version from tmux -V and requires >= 2.0. psmux reports "tmux 0.4.10" which parses as 0.4, causing silent fallback to in-process (Agent) mode instead of split-pane (Teammate) mode.

Workaround: A compiled C shim (122KB .exe) intercepts -V → "tmux 3.4", passes everything else to tmux-real.exe.

Suggested psmux fix: Report a tmux-compatible version, e.g. "tmux 3.4-psmux0.4.10".

2. Node.js spawn only finds .exe files on Windows

Claude Code uses Node.js child_process.spawn('tmux', ...) which on Windows calls CreateProcess — this only resolves .exe/.com files. Script-based shims (.cmd, bash) are invisible. The version-spoof shim must be a compiled .exe.

3. TMUX environment variable not detected in Git Bash sessions

@marlocarlo mentioned psmux sets $env:TMUX inside its panes. In my testing with Git Bash (MSYS2/MinGW64), process.env.TMUX was empty. This may be PowerShell-specific. Without it, Claude Code operates in "external session mode" — which still works, but uses a separate tmux socket (-L flag) instead of the existing session.

With --teammate-mode tmux, this is not a blocker since Claude Code bypasses the env check and goes directly to tmux backend. But in auto mode, tmux won't be auto-detected.

Claude Code internal flow (from binary analysis)

For the Claude Code team's reference, the backend selection logic (decompiled from v2.1.71):

isInProcessEnabled(mode):
  if mode === "tmux"    → false (use split-pane)
  if mode === "auto"    → !process.env.TMUX  (requires TMUX env)
  
detectBackend():
  if process.env.TMUX   → tmux (native mode)
  elif tmux -V succeeds  → tmux (external session mode)
  else                   → error

Both paths lead to the tmux backend, but native mode uses the existing session while external mode creates its own. The version check happens at a higher level — if tmux -V exits with code 0, it passes, but if the reported version < 2.0, split-pane is disabled elsewhere.

Updated repo

All findings, the compiled shim, and updated documentation are at:
https://github.com/gonnector/claude-psmux-team

Suggestion for Claude Code team

A small version-check change would eliminate the need for any shim:

- const version = parseFloat(versionString.match(/\d+\.\d+/)?.[0]);
- if (version < 2.0) return false;
+ // Accept psmux (reports "tmux 0.x.y") alongside real tmux (2.0+)
+ const match = versionString.match(/tmux[- ](\d+)/);
+ if (match && parseInt(match[1]) < 2 && !versionString.includes('psmux')) return false;

Or even better: add psmux as a first-class backend (as @marlocarlo suggested), checking process.env.PSMUX_SESSION.

Update: Tested the full flow — individual tmux commands (split-window, send-keys, list-panes, etc.) all work through the compiled shim, but teammate split-pane does not appear in the actual psmux session when running claude --teammate-mode tmux.

Likely cause: psmux does not set the TMUX environment variable in Git Bash (MSYS2) sessions, so Claude Code falls into "external session mode" — creating panes in a separate tmux context instead of splitting the current visible pane. A Claude Code-side change (e.g., detecting PSMUX_SESSION or forcing native mode with --teammate-mode tmux) would likely resolve this.

PSMUX calls set_tmux_env() which sets TMUX, TMUX_PANE, and PSMUX_SESSION regardless of shell type
(pwsh, cmd, or bash). Perhaps the core issue to be solved is this https://github.com/anthropics/claude-code/issues/26244 ?

Same situation as #23574 (WezTerm request) — until Windows Terminal is officially supported as a split-pane backend:
Workaround 1 — Use tmux via WSL:
If you're running Claude Code in WSL:

// settings.json
{
  "teammateMode": "tmux"
}

tmux works inside Windows Terminal (via WSL) and provides the split-pane functionality for agent teams.
Workaround 2 — Windows Terminal native splits + multiple instances:
Windows Terminal supports splits natively:

• Alt+Shift+D — duplicate pane (split)
• Alt+Shift+- — horizontal split
• Alt+Shift+= — vertical split

Run claude in each split for multiple simultaneous sessions. Not automated like agent teams, but functional.
Workaround 3 — Use the VS Code extension:
The VS Code extension handles agent teams through its own pane management, independent of the terminal backend. If agent teams are your priority, the VS Code extension may be the most reliable option on Windows.

as @gonnector mentioned, --teammate-mode tmux works on Windows via Psmux.

However, we need support for git worktrees. We have made Psmux so modern apps like Claude Code can work on Windows natively without using WSL or Linux as a workaround. Pretty much everything else works except whatever is hardcoded in claude code source to detect windows and block it.