Tmux for AI Coding: Run Parallel Agents Without Waiting
Learn tmux for AI coding: split the terminal into panes, run several agents in parallel, detach and resume sessions, and stop waiting one task at a time.
Independent article: published by AI Coding Tools, not official vendor documentation.
Tmux for AI Coding: Run Parallel Agents Without Waiting
AI coding agents changed how we write software — but they introduced a new bottleneck: waiting. You ask an agent to implement a feature, and while it plans, edits, and runs tests, your terminal is blocked. If you queue work one task at a time, a 30-minute session becomes a chain of five-minute waits.
Tmux fixes this. It lets you split one terminal into many panes and windows, keep sessions alive in the background, and run multiple AI agents at the same time. The result: instead of submitting one task and waiting, you split your screen into four quadrants, submit four tasks, and let them run in parallel.
This guide is the pillar article of our tmux cluster. New to the basics? Read the tmux cheatsheet for the command reference, and see the four-pane parallel agent layout for the exact setup described here.
Why tmux and AI coding are a natural fit
Terminal-based AI tools — Claude Code, Codex CLI, OpenCode — are designed to run for minutes at a time. They read your repository, make a plan, edit files, run tests, and iterate. That long-running nature is exactly what tmux is built for:
| Problem with one terminal | How tmux solves it | |---|---| | One agent blocks the screen | Split into panes; each task gets its own pane | | Closing the laptop kills the task | Sessions survive detach; reattach anywhere | | Can't watch tests while an agent works | Run the test watcher in its own pane | | SSH disconnects lose work | Sessions persist on the server | | Context switching between tasks | Named sessions and windows for each task |
If you're evaluating alternatives first, our tmux vs screen comparison explains why tmux is the better foundation for this workflow.
Tmux core concepts: session, window, pane
Before the workflow, the vocabulary. Tmux has three levels:
tmux (server)
└── session (e.g. "project-api") — a named collection of windows
└── window (e.g. "agents") — a full-screen workspace, like a tab
└── pane — a split section of the window
- Session — the top level. A session survives even when you detach from it. Multiple sessions can run side by side, each with its own set of agents.
- Window — like a browser tab inside a session. Useful for grouping related panes.
- Pane — a split region of a window. This is where the magic of parallel AI coding happens: each pane runs its own shell, its own agent, its own command.
The default prefix key is Ctrl-b — you press the prefix, then a command key.
| Action | Command |
|---|---|
| New session | tmux new -s myproject |
| Detach (leave running) | Ctrl-b d |
| Reattach | tmux attach -t myproject |
| Split horizontally | Ctrl-b " |
| Split vertically | Ctrl-b % |
| Switch pane | Ctrl-b then arrow keys |
The tmux cheatsheet has the complete command reference, including copy mode, resizing, and windows.
The flagship pattern: a four-pane parallel layout
The workflow this whole section is built around: turn one screen into four quadrants, and give each quadrant a different job.
Start a session and split into a 2×2 grid:
tmux new -s work
# Ctrl-b " (split horizontally)
# Ctrl-b % (split right pane vertically)
# Ctrl-b % (split left pane vertically)
You now have four panes. A productive assignment for agent-based development:
┌─────────────────────┬─────────────────────┐
│ Pane 1: Agent A │ Pane 2: Agent B │
│ implement feature │ fix bug #214 │
├─────────────────────┼─────────────────────┤
│ Pane 3: Test │ Pane 4: Review │
│ watcher / CI │ git diff + logs │
└─────────────────────┴─────────────────────┘
The point is independent tasks: pane 1 runs one coding agent, pane 2 runs another, pane 3 watches tests, pane 4 is where you review diffs and check logs while the agents work. No pane blocks another.
To make this repeatable, add a one-key binding to ~/.tmux.conf that creates the quad layout instantly:
# ~/.tmux.conf — one key to a four-pane layout
bind -n M-q send-keys tmux new-session -d \; split-window -h \; split-window -v -t 0 \; split-window -v -t 2 \; select-pane -t 0
For a step-by-step walkthrough with a ready-to-paste config, see how to run 4 AI agents in parallel with tmux split panes.
Sessions: run agents in the background and come back
The second pillar of the workflow is detaching. When an agent is mid-task, you don't need to stare at it. Detach, and the agent keeps running:
# Start an agent in its own session
tmux new -s agent-frontend
claude # or: codex, opencode, any agent CLI
# Detach — the agent keeps working
# Ctrl-b d
# Later, reattach and see the result
tmux attach -t agent-frontend
This also makes tmux the natural answer to running multiple Claude Code sessions at once — one session per agent, each isolated, each resumable with --resume. We cover that setup in detail in tmux + Claude Code: multiple agent sessions.
Session management essentials:
| Task | Command |
|---|---|
| List sessions | tmux ls |
| Attach to a session | tmux attach -t name |
| Kill a session | tmux kill-session -t name |
| Rename a session | Ctrl-b $ |
| Next / previous window | Ctrl-b n / Ctrl-b p |
Workflow patterns for parallel agent development
Beyond the quad layout, these are the patterns we use daily.
Pattern 1: Agent + test watcher
Run the coding agent in one pane, the test runner in another. Every edit the agent makes is validated live:
# Pane 1: the agent
claude
# Pane 2: the watcher
npm test -- --watch
Pattern 2: Agent + review pane
While the agent implements, keep a pane open for inspecting its work:
# Pane 1: agent working
claude
# Pane 2: review
git status && git diff --stat
Pattern 3: Named sessions per task
For bigger work, use one session per task instead of panes. Ctrl-b n and Ctrl-b p cycle windows; tmux ls shows everything running. Combine with the tmux.conf productivity setup (mouse mode, vi keys, status bar) to make all of this comfortable.
Combining tmux with multi-window AI development
Tmux panes are one layer of parallelism; AI IDEs add another. Google Antigravity's manager view, for example, lets you spawn multiple agents across workspaces inside the editor — see our Antigravity vs Claude Code comparison for how agent-first IDEs compare with terminal workflows. A common setup: an IDE for interactive work, tmux sessions for long-running agents and watchers. The two complement each other — tmux covers everything the IDE's terminal can't detach from.
FAQ
Is tmux hard to learn?
The first hour is the hardest: the prefix key (Ctrl-b) is unfamiliar, and muscle memory for splits takes a day. After that, tmux is one of the highest-leverage tools in a terminal workflow. The cheatsheet linked above cuts the learning curve to minutes.
Does tmux work on Windows?
Tmux is Unix-native (macOS and Linux install it with brew install tmux or apt install tmux). On Windows, the practical options are WSL2 (which is also how most Windows developers run Claude Code) or Git Bash / MSYS2 builds.
Can I run different AI tools in different panes?
Yes — that's the point. Claude Code in pane 1, Codex in pane 2, a terminal test watcher in pane 3. They operate on independent shells, so nothing conflicts as long as you don't point two agents at the same files.
What happens when my SSH connection drops?
The tmux server keeps running on the remote machine. Reconnect, run tmux attach, and your sessions — agents included — are exactly where you left them.
Do agents keep running after I detach?
Yes. Detaching only closes your view, not the processes. The agent's process continues writing files and running commands in the session. Reattach later to see the result. (Note: a local laptop sleep can still pause the process — for truly remote work, run tmux on a server.)
Related articles
- Tmux Cheatsheet: Sessions, Panes & Shortcuts — the full command reference
- Run 4 AI Agents in Parallel with Tmux Split Panes — the quad layout, step by step
- Tmux + Claude Code: Multiple Agent Sessions — one session per agent, resume with
--resume - Tmux vs Screen: Which Multiplexer? — why tmux over GNU Screen
- Tmux Config: tmux.conf for Faster AI Coding — prefix remap, mouse, vi keys, status bar
Ready to go deeper? Set up the four-pane layout next, or grab the tmux.conf that makes all of it comfortable.