Want to run 6 AI agents simultaneously in a single terminal? The answer is TMUX. Everything you need in practice — from installation to team layout configuration and session recovery.

---

What Is TMUX?

TMUX (Terminal Multiplexer) is a tool that lets you run multiple terminals simultaneously inside a single terminal. Like a tabbed browser, it splits your terminal into tabs, divides the screen into panes, and keeps your work running in the background even after you close the terminal.

In an AI multi-agent environment, this capability is essential. You can run 6 Claude Code instances in separate panes and operate them all at the same time.

---

Installation (30 seconds)

sudo apt install -y tmux
tmux -V

That’s it. One line on Ubuntu/WSL.

---

Core Concepts: Session → Window → Pane

TMUX is organized into three layers:

Session          ← Top level. Survives after terminal closes
  └── Window     ← Tab. Only one visible at a time
        └── Pane  ← Split screen. Each is an independent shell

An analogy: – Session = the browser itself – Window = a tab – Pane = the screen split in half within a tab

---

Basic Command Cheat Sheet

Session Management

tmux new-session -s team       # Create new session
tmux ls                        # List sessions
tmux attach -t team            # Attach to session
tmux kill-session -t team      # Kill session
# Ctrl+B, D                    # Detach session (keeps running in background)

Pane Splitting & Navigation

Shortcut	Action
Ctrl+B %	Split vertically (left/right)
Ctrl+B "	Split horizontally (top/bottom)
Ctrl+B arrow	Move between panes
Ctrl+B z	Toggle current pane fullscreen
Ctrl+B x	Close current pane
Ctrl+B Ctrl+arrow	Resize pane

Window Management

Shortcut	Action
Ctrl+B c	New window
Ctrl+B n / p	Next / previous window
Ctrl+B 0~9	Jump to window by number

---

Controlling Panes from Scripts

This is the key to automation — how to send commands to a specific pane:

# Format: tmux send-keys -t session:window.pane "command" Enter

# Send command to Pane 1
tmux send-keys -t team:0.1 "echo hello" Enter

# Read current screen content of Pane 2
tmux capture-pane -t team:0.2 -p

The address format is session:window.pane. team:0.3 means session “team”, window 0, pane 3.

---

In Practice: Setting Up an AI Team Layout

A main-vertical layout for 6 agents. The team lead (Pane 0) takes the wide left side; the rest of the team stacks vertically on the right.

Setup Script

# 1. Create session
tmux new-session -d -s team -x 317 -y 85

# 2. Split 5 times → 6 total panes
for i in 1 2 3 4 5; do
  tmux split-window -t team:0 -h
done

# 3. Apply layout
tmux select-layout -t team:0 main-vertical
tmux set-option -t team main-pane-width 158

# 4. Set pane titles
tmux set-option -t team pane-border-status top
tmux select-pane -t team:0.0 -T "Mason (Lead)"
tmux select-pane -t team:0.1 -T "Liam Architect"
tmux select-pane -t team:0.2 -T "Noah Researcher"
tmux select-pane -t team:0.3 -T "Sophia Designer"
tmux select-pane -t team:0.4 -T "Ava Developer"
tmux select-pane -t team:0.5 -T "Ryan Reviewer"

# 5. Launch Claude Code in each pane
for i in 0 1 2 3 4 5; do
  tmux send-keys -t team:0.$i "claude" Enter
done

Pane	Member	Role	Position
0	Mason	Team Lead	Left main
1	Liam	PM · Architect	Top right
2	Noah	Researcher	Right 2nd
3	Sophia	Designer	Right 3rd
4	Ava	Developer	Right 4th
5	Ryan	Reviewer	Bottom right

---

When the Session Drops — Recovery Guide

TMUX’s greatest strength is that sessions persist independently of your terminal. Even if your SSH connection drops or you close the terminal, the session stays alive.

By Situation

Situation	Risk	Solution
SSH dropped	Low	Reconnect with tmux attach -t team
Claude in a pane exited	Medium	Re-run claude in that pane, then /resume
Pane itself disappeared	High	Create new pane + re-set title
Entire session lost	High	Re-run setup script

SSH Drop → Reconnect

The most common situation. Nothing is lost.

tmux ls                  # Check sessions
tmux attach -t team      # Resume right where you left off

When Only Claude Died

The pane is alive but Claude Code has exited:

# Re-launch in that pane
tmux send-keys -t team:0.3 "claude" Enter

# Resume previous conversation
tmux send-keys -t team:0.3 "/resume" Enter

When a Full Rebuild Is Needed

If the session is completely gone after a system reboot:

bash ~/setup-team.sh
tmux attach -t team

---

Auto Health-Check Script

If manual checks are tedious, use a cron job to check team status every 10 minutes:

#!/bin/bash
# check-team.sh

SESSION="team"
TITLES=("orchestrator" "architect" "researcher" "designer" "developer" "reviewer")

# Rebuild if session is missing
if ! tmux has-session -t $SESSION 2>/dev/null; then
  echo "Session not found — rebuilding"
  bash ~/setup-team.sh
  exit 0
fi

# Check Claude running state per pane
for i in 0 1 2 3 4 5; do
  CMD=$(tmux list-panes -t $SESSION:0 \
    -F "#{pane_index} #{pane_current_command}" \
    | grep "^$i " | awk '{print $2}')

  if [ "$CMD" != "claude" ] && [ "$CMD" != "node" ]; then
    echo "Pane $i (${TITLES[$i]}): restarting"
    tmux send-keys -t $SESSION:0.$i "claude" Enter
  else
    echo "Pane $i (${TITLES[$i]}): OK"
  fi
done

# Register cron (every 10 minutes)
crontab -e
# */10 * * * * /home/user/check-team.sh >> /tmp/team-check.log 2>&1

---

Prevention: tmux-resurrect

Save your session state to a file and restore it even after a system reboot.

# Install
git clone https://github.com/tmux-plugins/tmux-resurrect \
    ~/.tmux/plugins/tmux-resurrect

# Add to ~/.tmux.conf
# run-shell ~/.tmux/plugins/tmux-resurrect/resurrect.tmux

Shortcut	Action
Ctrl+B → Ctrl+S	Save session
Ctrl+B → Ctrl+R	Restore session

---

What Running This for Real Taught Me

The layout above is the easy part. Driving six live agents through send-keys for weeks surfaced failure modes the tutorials never mention. These cost me real time, so here they are:

• Send the message and the Enter separately. tmux send-keys -t team:0.3 "do the thing" Enter looks atomic, but under load the trailing Enter often doesn’t register — the text lands in the input box and just sits there. The reliable pattern is two calls with a beat between: send the text, sleep 0.3, then send Enter on its own.

• One line per message. Long, multi-line instructions get truncated in transit — the agent receives a fragment, acts on half of it, and drifts off-task. I compress every dispatch to a single line and let the agent ask for detail if it needs it.

• Never fire-and-forget. After sending, tmux capture-pane -t team:0.3 -p to confirm the agent actually received the message before assuming the task is running. A surprising number of “stuck” agents were just messages that never landed.

• Pin the model when you respawn a pane. Respawning a dead pane with a bare tmux respawn-pane -k relaunches the CLI on the default model, which silently thrashed my per-pane assignments (the lead runs a heavyweight model; the researchers don’t need it). I wrap every respawn in a script that passes the pane’s fixed model.

• A jammed input box clears with Ctrl+U. When a prompt gets wedged — half-sent text, a stray Enter — sending more text makes it worse. Send C-u to clear the line first, then resend clean.

None of these show up until you’re orchestrating several agents at once. They’re the difference between a demo that works once and a team that runs for days.

---

Key Takeaways

Task	Command
Create session	tmux new-session -s team
Attach to session	tmux attach -t team
Split pane	Ctrl+B % (left/right) / Ctrl+B " (top/bottom)
Send command to pane	tmux send-keys -t team:0.3 "cmd" Enter
Read pane content	tmux capture-pane -t team:0.3 -p
Apply layout	tmux select-layout -t team:0 main-vertical
Full team setup	bash ~/setup-team.sh

TMUX is the infrastructure for running AI multi-agent systems. Sessions survive independently of terminals, and any agent can be precisely controlled via pane addresses like team:0.3. Remember those two things and the rest is just application.

---

Related Guides on Private Labs

• Triple Crown Strategy: Turning AI Coding into Project Management
• Team Automation with Claude Code: A Practical Guide
• WSL2 Network Issues: What Caused Them and How I Fixed Them

More in Problem Solving.