How to Set Up Claude Code Agent Teams on Windows Using tmux

May 11, 2026

Developer terminal workspace

Problem

When I tried to use Claude Code’s Agent Teams feature on Windows, I discovered that it requires tmux - but tmux doesn’t run natively on CMD or PowerShell.

The documentation says to enable teammateMode: "tmux", but when I checked my system, tmux was not available:

$ tmux
bash: tmux: command not found

I wanted to run multiple Claude agents in parallel, but without tmux, the Agent Teams feature would not work on Windows.

Environment

Windows 10/11
Git for Windows (MinGW64/Git Bash)
Claude Code CLI

What happened?

Claude Code’s Agent Teams feature spawns multiple Claude instances in separate terminal panes. On Linux and macOS, tmux is readily available. On Windows, however, CMD and PowerShell lack essential Unix-like capabilities:

PTY pseudo-terminals
Unix system calls
MSYS2 runtime libraries

So I needed to install tmux specifically for Git Bash, then configure Claude Code to use it.

How Agent Teams Work

Before diving into the setup, here’s what Agent Teams architecture looks like:

┌─────────────────────────────────────────────────────────┐
│                      Git Bash                            │
│  ┌─────────────────────────────────────────────────┐    │
│  │                 tmux Session                      │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐         │    │
│  │  │ Agent 1  │ │ Agent 2  │ │ Agent 3  │         │    │
│  │  │ (pane 0) │ │ (pane 1) │ │ (pane 2) │         │    │
│  │  └──────────┘ └──────────┘ └──────────┘         │    │
│  │       ↓            ↓            ↓                │    │
│  │   Claude       Claude       Claude               │    │
│  │  Instance     Instance     Instance              │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Each agent runs in its own tmux pane, allowing parallel task execution with separate Claude instances.

Multiple Claude agent panes running in parallel within a tmux session

How to solve it?

Step 1: Verify Git for Windows installation

First, I checked where Git is installed:

where.exe git
# Output: C:\Program Files\Git\cmd\git.exe

Git for Windows includes Git Bash (MinGW64), which provides the Unix-like environment that tmux needs.

Step 2: Install tmux for Windows

I cloned the tmux_for_windows project, which provides pre-compiled binaries for Git Bash:

git clone https://github.com/hongwenjun/tmux_for_windows.git
cd tmux_for_windows

Then I extracted the binaries to Git’s usr directory. Since I installed Git in Program Files, I needed administrator privileges:

# Open PowerShell as Administrator, then run:
Start-Process powershell -Verb RunAs -ArgumentList `
  "-Command Expand-Archive -Path 'tmux_for_windows\tmux_for_git-bash.zip' -DestinationPath 'C:\Program Files\Git\usr' -Force" -Wait

Step 3: Verify tmux installation

I opened Git Bash (not PowerShell!) and verified tmux works:

tmux -V
# Output: tmux 3.3a (or higher version)

Step 4: Configure mouse support (optional but recommended)

I copied the tmux config file for better mouse support:

Copy-Item "tmux_for_windows\.tmux.conf" -Destination "$env:USERPROFILE\.tmux.conf"

This enables mouse scrolling and pane selection.

Step 5: Configure Claude Code settings

I edited Claude Code’s settings.json to enable Agent Teams:

{
  "env": {
    "PATH": "<your-existing-PATH>;C:\\Program Files\\Git\\usr\\bin",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

Key points:

PATH must include Git’s usr\bin directory where tmux lives
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enables the experimental feature
teammateMode: "tmux" tells Claude Code to use tmux for agent management

Step 6: Launch Claude Code correctly

This is the most important step - I must launch Claude from Git Bash:

# In Git Bash terminal
claude

# Or start within a tmux session first
tmux new-session -s work
claude

Claude Code running inside a Git Bash tmux session with visible pane borders

If I launch from CMD or PowerShell, tmux won’t be available and Agent Teams won’t work.

The reason

I think the key reason for these requirements is:

tmux needs MSYS2 runtime - It’s compiled for MinGW64, which Git Bash provides
PTY support - Git Bash emulates Unix pseudo-terminals that tmux requires
Environment variables - settings.json PATH extension ensures Claude can find tmux

When I tried launching from PowerShell, the Unix-like environment wasn’t available, so tmux couldn’t run.

Common Mistakes to Avoid

I made several mistakes during my first attempt:

Problem	Cause	Solution
`tmux: command not found`	PATH missing	Add `C:\Program Files\Git\usr\bin` to PATH in settings.json
Access Denied during extraction	No admin rights	Use `Start-Process -Verb RunAs`
Agents don’t appear in panes	Wrong terminal	Must launch from Git Bash
`teammateSessions` schema error	Invalid field	Only use `teammateMode`, not `teammateSessions`

tmux Quick Reference

Once Agent Teams is running, here are useful tmux shortcuts:

Shortcut	Action
`Ctrl+B` + Arrow keys	Switch between panes
`Ctrl+B` + `d`	Detach session (keeps running)
`Ctrl+B` + `[`	Enter copy/scroll mode
`q`	Exit copy mode

tmux list-sessions          # List all sessions
tmux list-panes -a          # List all panes
tmux attach-session -t work # Attach to named session

Summary

In this post, I showed how to set up Claude Code Agent Teams on Windows by installing tmux for Git Bash. The key point is that tmux requires a Unix-like environment, so you must install the MinGW64 binaries and always launch Claude from Git Bash, not CMD or PowerShell.

Once configured, you can run multiple Claude agents in parallel tmux panes, enabling more efficient task execution on Windows.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 tmux for Windows Repository
👨‍💻 Git for Windows Download

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!