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, press | What happens |
|---|---|
% | Split the pane into two side by side (left and right) |
" | Split the pane into two stacked (top and bottom) |
| Arrow keys | Move to the pane above, below, left or right |
z | Zoom the current pane to full size. Press again to shrink it back |
x | Close (kill) the current pane |
c | Create a new window |
n / p | Go to the next or previous window |
0 to 9 | Jump straight to window 0 to 9 |
, | Rename the current window |
d | Detach: leave tmux with everything still running |
s | Show 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 insideThe 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 agentsThe 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 psmuxIts 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:
| Action | Shortcut |
|---|---|
| New pane to the right | Alt + Shift + Plus |
| New pane below | Alt + Shift + Minus |
| Split in whichever direction gives squarer panes, copying the current pane | Alt + Shift + D |
| New pane from the + button or the profile menu | Hold Alt while you click |
| Move between panes | Alt + arrow keys |
| Make the focused pane bigger or smaller | Alt + Shift + arrow keys |
| Close the focused pane | Ctrl + Shift + W |
| Zoom a pane to full size | Ctrl + 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\docsThen 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.
- Install tmux in WSL (see above) and install Claude Code inside WSL too.
- Open
~/.claude/settings.jsoninside 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. - Start tmux with
tmux new -s team, move into your project, and typeclaude. - 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. - 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 startedKeep reading
Windows install guide
Claude Code Windows install: choose your method, then get it running
Parallel agents
How to run multiple Claude Code agents at once: four ways, easiest last
Git first, agents second
Claude Code worktrees, starting with plain git worktree
Windows walk-through
Claude Squad on Windows: what works, what breaks, what else to try
Alert recipes
Claude Code notifications: copy-paste recipes for every computer
Hands-on Claude Code guide
Claude Code subagents: build a custom agent step by step