Mastering TMUX — Terminal Splitting for AI Multi-Agent Systems

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 "Jun (Lead)"
tmux select-pane -t team:0.1 -T "Minjun Architect"
tmux select-pane -t team:0.2 -T "Jihun Researcher"
tmux select-pane -t team:0.3 -T "Sua Designer"
tmux select-pane -t team:0.4 -T "Seoyeon Developer"
tmux select-pane -t team:0.5 -T "Taeyang 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	Jun	Team Lead	Left main
1	Minjun	PM · Architect	Top right
2	Jihun	Researcher	Right 2nd
3	Sua	Designer	Right 3rd
4	Seoyeon	Developer	Right 4th
5	Taeyang	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 /mnt/c/work/Team/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=("Jun" "Minjun" "Jihun" "Sua" "Seoyeon" "Taeyang")

# Rebuild if session is missing
if ! tmux has-session -t $SESSION 2>/dev/null; then
  echo "Session not found — rebuilding"
  bash /mnt/c/work/Team/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

---

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.