dotfiles

tmux setup

Configuration for a multi-agent Claude Code workspace using tmux and iTerm2.

What’s in this folder

File Purpose Install location
tmux.conf tmux settings (mouse, colours, clipboard, pane titles) ~/.tmux.conf
tmux-work Script to launch and manage multi-agent Claude Code sessions ~/.local/bin/tmux-work

Prerequisites

# Install tmux (macOS)
brew install tmux

# Make sure ~/.local/bin exists and is on your PATH
mkdir -p ~/.local/bin

Your ~/.zshrc should include ~/.local/bin in the path:

path=(
  $HOME/.local/bin
  $path
)
typeset -U path

And optionally, an alias for convenience:

alias tw='tmux-work'

Installation

# From the dotfiles repo
cp tmux/tmux.conf ~/.tmux.conf
cp tmux/tmux-work ~/.local/bin/tmux-work
chmod +x ~/.local/bin/tmux-work

If tmux is already running, reload the config:

tmux source-file ~/.tmux.conf

Usage

Starting a session

tw              # 4 Claude agents + preview pane (default)
tw duo          # 2 agents (stacked) + preview pane
tw solo         # 1 agent + preview pane
tw focus        # 1 agent, full screen (no preview)

The default layout looks like this:

+----------+----------+--------------+
| Agent 1  | Agent 2  |              |
| (Claude) | (Claude) |   Preview    |
|          |          |   / Neovim   |
+----------+----------+   (shared    |
| Agent 3  | Agent 4  |    shell)    |
| (Claude) | (Claude) |              |
+----------+----------+--------------+

Each agent pane launches claude automatically. The preview pane on the right stays as a plain shell for viewing files.

Managing agents

# Adding agents
tw add          # Add agent below current pane (horizontal split, default)
tw add h        # Same as above (horizontal split, like vim :split)
tw add v        # Add agent beside current pane (vertical split, like vim :vsplit)
tw add up       # Same as tw add h
tw add down     # Same as tw add h
tw add left     # Same as tw add v
tw add right    # Same as tw add v

# Removing agents
tw rm           # Remove the focused agent pane
tw remove       # Same as above
tw rm h         # Remove the neighbour below (or above)
tw rm v         # Remove the neighbour to the right (or left)
tw rm up        # Remove the pane above
tw rm down      # Remove the pane below
tw rm left      # Remove the pane to the left
tw rm right     # Remove the pane to the right

Split directions follow vim conventions: h = horizontal line (:split, top/bottom), v = vertical line (:vsplit, side by side).

The rm directional commands protect the preview pane and the last remaining agent pane.

Preview pane

tw preview      # Toggle the preview pane on/off
tw open <file>  # Open a file in neovim in the preview pane

tw open automatically restores the preview pane if it is hidden. It also quits any running neovim instance before opening the new file.

Session management

tw attach       # Reattach to an existing session
tw kill         # Kill the session

Keybinding

The tmux config binds prefix + p to toggle the preview pane (same as tw preview).

tmux.conf highlights