Terminal multiplexers

Claude Code and tmux for beginners: panes, keys and Windows options

Updated November 17, 20268 min read

Claude Code tmux setups let you watch several AI agents in one terminal, and tmux keeps them running even after you close the window. tmux is a terminal multiplexer (a program that splits one terminal into many and keeps them alive), built for Linux and macOS, so on Windows you run it inside WSL or try a native port such as psmux. Start with the five words below, then learn the keys, the Windows options and the Claude Code settings.

Five tmux words to learn before anything else

Session
The whole workspace. It groups one or more windows and keeps running in the background until you end it. You give it a name, such as agents.
Window
Like a browser tab inside a session. Each window fills the screen and holds one or more panes.
Pane
One box inside a window, holding one terminal and one running program. Three panes can mean three Claude Code agents side by side.
Prefix key
The key you press before every tmux shortcut, so tmux knows the next key is meant for it. By default it is Ctrl+b.
Detach
Leaving tmux without stopping anything. The programs keep working in the background, and you attach (reconnect) later to find them exactly as you left them.

Put together: you start a session called agents, split its window into three panes, and run claude in each one, every pane in a different project folder. Then you detach, go to lunch, attach again, and every agent is still there, mid-task or waiting for you.

That last trick is why people pair tmux with AI agents. An agent can work for a long time, and with tmux the work no longer depends on one terminal window staying open or one remote connection staying up.

tmux cheat sheet: the keys you will use every day

Every key below starts with the prefix. Hold Ctrl, press b, let go of both, then press the key in the left column. All of these defaults come from the tmux Getting Started wiki.

After Ctrl+b, pressWhat happens
%Split the pane into two side by side (left and right)
"Split the pane into two stacked (top and bottom)
Arrow keysMove to the pane above, below, left or right
zZoom the current pane to full size. Press again to shrink it back
xClose (kill) the current pane
cCreate a new window
n / pGo to the next or previous window
0 to 9Jump straight to window 0 to 9
,Rename the current window
dDetach: leave tmux with everything still running
sShow a list of your sessions to pick from
[Copy mode, for scrolling back through output
:Open the tmux command prompt
?List every key and what it does

You also need four commands that you type at a normal prompt, outside tmux:

tmux new -s agents          # start a session named agents
tmux ls                     # list running sessions
tmux attach -t agents       # reconnect to it
tmux kill-session -t agents # end it and everything inside

The split names are easy to mix up. tmux's docs call % a horizontal split, even though the new pane appears beside the old one. If you only remember one key, make it ?, which shows the whole list whenever you forget.

Running tmux on Windows: WSL or psmux

tmux is built for Unix-style systems such as Linux and macOS, and there is no official Windows version. Windows users have two real routes.

Route 1: real tmux inside WSL

WSL (Windows Subsystem for Linux) runs a full Linux system inside Windows, so you get the genuine tmux. Run the first line in PowerShell as Administrator, restart, open Ubuntu from the Start menu, then run the rest inside Ubuntu:

wsl --install
# after the restart, inside Ubuntu:
sudo apt update && sudo apt install tmux
tmux new -s agents

The catch is that everything inside tmux is Linux, so Claude Code must be installed inside WSL too, with curl -fsSL https://claude.ai/install.sh | bash. A copy installed in PowerShell cannot be used from a WSL pane. Our Claude Code on Windows page covers both installs.

Route 2: psmux, a native tmux for PowerShell

psmux is a free, MIT-licensed community project that brings tmux-style panes to Windows without WSL. It runs on Windows 10 and 11, in PowerShell 7 (recommended) or cmd.exe, understands tmux commands and .tmux.conf settings files, and adds psmux, pmux and tmux commands. Install it with WinGet:

winget install psmux

Its README says Claude Code teammates open in separate panes when you run Claude Code inside a psmux session. Treat that as the project's own claim: Anthropic's docs only name tmux and iTerm2 for split panes, and psmux is not an Anthropic or tmux project. It also skips the WSL step, so your Windows install of Claude Code works as it is.

Windows Terminal split pane shortcuts, no install needed

If you only want several agents visible at once and do not care about detaching, Windows Terminal already splits panes. These are the default keys from Microsoft's panes docs:

ActionShortcut
New pane to the rightAlt + Shift + Plus
New pane belowAlt + Shift + Minus
Split in whichever direction gives squarer panes, copying the current paneAlt + Shift + D
New pane from the + button or the profile menuHold Alt while you click
Move between panesAlt + arrow keys
Make the focused pane bigger or smallerAlt + Shift + arrow keys
Close the focused paneCtrl + Shift + W
Zoom a pane to full sizeCtrl + Shift + P, then search for pane zoom (no default key)

You can also right-click a tab and choose Split Tab. The pane with the coloured border is the one your typing goes to.

Open a three-agent layout with one command

The wt command opens Windows Terminal with panes already split, each one starting in its own folder. In PowerShell the semicolons need a backtick in front, because PowerShell uses a plain semicolon for itself:

wt -d C:\code\shop `; split-pane -V -d C:\code\api `; split-pane -H -d C:\code\docs

Then type claude in each pane. Microsoft notes that PowerShell waits for that new Terminal window to close before it gives you the prompt back, so run the command from a window you do not need. The big limit is the one tmux solves: close Windows Terminal and every agent inside stops.

Claude Code tmux setup for agent teams

Agent teams are an experimental Claude Code feature where one lead session starts teammates and splits the work between them. By default every teammate runs inside your main terminal. Giving each teammate its own visible pane needs tmux or iTerm2, according to Anthropic's agent teams docs. On Windows that means tmux inside WSL.

  1. Install tmux in WSL (see above) and install Claude Code inside WSL too.
  2. Open ~/.claude/settings.json inside WSL and add the settings below. The first line turns agent teams on. "teammateMode": "auto" opens teammates in split panes whenever Claude Code is running inside tmux.
  3. Start tmux with tmux new -s team, move into your project, and type claude.
  4. Ask for a team in plain English, for example: Spawn three teammates to review this pull request: one for security, one for speed, one for test coverage.
  5. Click into any teammate's pane to talk to it directly. Permission questions still show up in the lead's pane, so keep an eye on that one.
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "auto"
}

To try split panes for one session only, start with claude --teammate-mode auto. If you run Claude Code outside tmux but have tmux installed, set teammateMode to "tmux". The panes then open in a separate tmux session, and the Claude Code prompt shows a View teammates line with the command to watch them from a second terminal.

You do not need tmux to use agent teams at all. In the default in-process mode, which works in Windows Terminal and any other terminal, use the up and down arrows in the agent panel to pick a teammate, Enter to open it, Escape to go back, x to stop the selected one, and Ctrl+T to show the task list.

Watch out

Every teammate is a full Claude session with its own memory, so a team burns through your plan's usage much faster than one session. Anthropic suggests starting with 3 to 5 teammates. If a tmux session hangs around after Claude Code ends, list it with tmux ls and close it with tmux kill-session -t <session-name>.

Anthropic also notes that tmux has known limits on some operating systems and has traditionally worked best on macOS. For lighter jobs, subagents run inside one session and need no panes at all.

When a visual app is easier than tmux

tmux was made for programs that print text and finish. AI agents behave differently: they work for a while, then stop and wait for a yes. As a tool for AI agents, tmux does its job of keeping panes alive well, but it cannot tell you which pane is waiting.

tmux is a good fit when

  • You already use Linux, macOS or WSL every day
  • You work over SSH on a remote server and need agents to survive a dropped connection
  • You want Claude Code agent teams in split panes
  • You like keyboard shortcuts and a settings file you can tune
  • You want something free and open source

A visual app is easier when

  • You are on Windows and do not want WSL in the way
  • You keep missing the moment an agent is waiting for an answer
  • You want to see usage limits before an agent hits one
  • Two agents keep editing the same project and undoing each other
  • You are not a developer and a prefix key feels like a puzzle

VibeCodingDeck covers the second column. It is a desktop app for Windows 10 and 11 and Apple silicon Macs that puts up to 12 agents in one grid with no WSL and no prefix key. Each pane gets a status light, and three alert levels with their own sounds flag the agent that needs you (more on that in Claude Code notifications). A live meter shows daily and weekly usage for each login, and closing the app keeps your layout and conversations for next time. Each agent can work on its own safe copy of the project, which is a git worktree underneath (see our worktrees guide).

It works with the agents you already have installed, including Claude Code, Codex, Gemini, Grok, GitHub Copilot, Qwen, Kimi and Antigravity, and costs $29/month or $249/year with every feature included, as of November 2026. If you like the idea of a terminal-based manager instead, our Claude Squad alternatives page compares the options.

Sources

Run up to 12 AI coding agents in one window.

Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.

Get started

Keep reading