Skip to content

tmux Layout

AgentPair can run agents in a tmux session with side-by-side panes for visual monitoring.

Prerequisites

Install tmux:

brew install tmux

sudo apt install tmux

sudo dnf install tmux

Basic Usage

agentpair --tmux --prompt "Implement feature X"

This creates a detached tmux session with the layout:

┌─────────────────────────────────────────────────────────┐
│                                                          │
│   Claude Pane (0)          │    Codex Pane (1)          │
│                            │                            │
│   [Claude output here]     │    [Codex output here]     │
│                            │                            │
│                            │                            │
│                            │                            │
├────────────────────────────┴────────────────────────────┤
│   Status Pane (2)                                        │
│   [Bridge status, iteration info]                        │
└─────────────────────────────────────────────────────────┘

Attaching to Sessions

After starting:

# Attach to the session
tmux attach -t agentpair-myrepo-1

Session names follow the pattern: agentpair-{repo}-{run-id}

Session Management

List Sessions

tmux list-sessions

Output:

agentpair-myrepo-1: 3 windows (created Sat Mar 28 10:00:00 2024)
agentpair-myrepo-2: 3 windows (created Sat Mar 28 11:30:00 2024)

Detach

While attached, press Ctrl+B then D to detach.

Kill Session

tmux kill-session -t agentpair-myrepo-1

Pane Navigation

Standard tmux navigation:

Keys Action
Ctrl+B ← Move to left pane
Ctrl+B → Move to right pane
Ctrl+B ↑ Move to upper pane
Ctrl+B ↓ Move to lower pane
Ctrl+B z Zoom current pane
Ctrl+B [ Enter scroll mode
q Exit scroll mode

Scrolling

To scroll through agent output:

  1. Press Ctrl+B then [ to enter scroll mode
  2. Use arrow keys or Page Up/Down to scroll
  3. Press q to exit scroll mode

Layout Customization

The default layout uses equal horizontal splits for agents and a smaller bottom pane for status.

tmux configuration can be customized in ~/.tmux.conf:

# Example: increase scrollback
set-option -g history-limit 50000

# Mouse support for scrolling
set -g mouse on

Persistent Sessions

tmux sessions persist even if:

  • You close your terminal
  • You disconnect from SSH
  • Your shell exits

Reattach anytime with:

tmux attach -t agentpair-myrepo-1

With SSH

tmux is particularly useful over SSH:

# SSH into remote machine
ssh user@remote

# Start AgentPair with tmux
agentpair --tmux --prompt "Task"

# Detach (Ctrl+B, D)

# Disconnect SSH safely

# Later, reconnect
ssh user@remote
tmux attach -t agentpair-myrepo-1

With Worktree

Combine tmux with worktree isolation:

agentpair --tmux --worktree --prompt "Experimental feature"

Example Workflow

  1. Start session: 

    agentpair --tmux --prompt "Implement OAuth login"

  2. Attach to watch: 

    tmux attach -t agentpair-myproject-1

  3. Navigate panes:

  4. Ctrl+B → to see Codex
  5. Ctrl+B ← to see Claude

  6. Ctrl+B ↓ to see status

  7. Scroll history:

  8. Ctrl+B [ to enter scroll mode
  9. Page Up/Down to navigate

  10. q to exit

  11. Detach when satisfied:

  12. Ctrl+B D to detach

  13. Check status later: 

    agentpair dashboard
agentpair bridge --run-id 1

Troubleshooting

"tmux not available"

Install tmux (see Prerequisites above).

Session Not Found

# List all sessions
tmux list-sessions

# Session might have completed
agentpair dashboard

Panes Not Updating

  • Check if agents are still running
  • View bridge status: agentpair bridge --run-id 1
  • Check for errors in agent panes

Terminal Issues

If the terminal looks corrupted:

# Reset terminal
reset

# Or restart tmux server
tmux kill-server

Next Steps