A Developer's Guide to tmux in the Age of AI

tmux is a terminal multiplexer: it runs a persistent server process on your machine so that sessions, windows, and panes survive terminal disconnects — you can detach from a session, close your laptop, SSH back in from a different machine, and reattach to find every process exactly where you left it. That single property is why tmux matters more now than it did a decade ago: developers increasingly run long-lived processes — dev servers, build watchers, and autonomous AI coding agents like Claude Code and aider — that need to outlive a flaky SSH connection or a closed lid.

This guide builds the mental model first (sessions, windows, panes, the prefix key), gives you a minimal config you can paste once and stop touching, then spends real time on the part no other tmux guide covers: using tmux as the durable host for AI coding agents. It closes with an honest comparison of when to reach for tmux and when a modern terminal like Zellij or Warp is the better tool.

What tmux Is and the Problem It Solves

tmux is a terminal multiplexer that lets one terminal window host many persistent sessions, windows, and panes. The mechanism behind its persistence is a client-server architecture: when you run tmux, it starts a long-lived server process that owns your sessions, and your terminal connects to that server as a client. When your SSH connection drops, your tmux session doesn’t — because the server process runs independently of any client connection. Your terminal is just a view; the session keeps running whether you’re attached or not.

tmux solves two problems at once. The first is persistence: a build that takes 40 minutes, a dev server, or an AI agent mid-task all keep running after your ssh session dies. You reconnect and reattach. The second is layout: instead of juggling terminal tabs, you split one window into panes — editor on the left, a server log on the right, a shell at the bottom — all visible at once and all reproducible.

tmux was created in 2007 by Nicholas Marriott as an ISC-licensed alternative to GNU screen. The examples in this guide use tmux 3.6b. Install it with your package manager:

# macOS
brew install tmux

# Debian / Ubuntu / WSL
sudo apt install tmux

# Fedora / RHEL
sudo dnf install tmux

tmux -V   # confirm the version

The Sessions, Windows, and Panes Hierarchy

tmux organizes work in three layers: a session is a named, persistent workspace (one per project); windows are tabs within that session; panes are splits within a window. The prefix key — default Ctrl+b, conventionally remapped to Ctrl+a — gates every tmux command. You press the prefix, release it, then press the command key.

The cleanest analogy maps to an editor you already know: a session is like an entire editor window for a project, windows are the tabs inside it, and panes are the split views inside a tab. You might have a frontend session and a backend session; inside backend, a window for the app and a window for the database; inside the app window, one pane running the server and one for ad-hoc commands.

Because the prefix gates commands, every keybinding below assumes you press the prefix first. The default prefix is Ctrl+b; the config in the next section remaps it to Ctrl+a, which is easier to reach.

The Essential Command Set

These commands cover 90% of daily tmux use: create and name sessions, detach and reattach, split and navigate panes, and scroll back through output. You run session-level commands from your shell; pane and window commands run inside tmux via the prefix.

Session management from the shell:

tmux new -s project       # create a named session
tmux ls                   # list running sessions
tmux attach -t project    # reattach to a session
tmux kill-session -t project

Inside a session, with the prefix (shown here as the remapped Ctrl+a):

• prefix d — detach; the session keeps running in the background.
• prefix c — create a new window.
• prefix n / prefix p — next / previous window.
• prefix % — split the current pane vertically (left/right).
• prefix " — split horizontally (top/bottom).
• prefix + arrow keys — move between panes.
• prefix z — zoom the current pane to fullscreen; press again to restore.
• prefix [ — enter copy mode to scroll and search; in vi mode, / searches, n/N jump between matches, q exits.

The detach/reattach loop is the core workflow: detach with prefix d, switch to another machine, reattach with tmux attach -t project-name, and pick up exactly where you left off. For a full keybinding reference, keep a tmux cheat sheet handy — memorizing the whole man page is unnecessary.

A Minimal ~/.tmux.conf You Can Paste Once

A minimal tmux config needs exactly four things: a remapped prefix key (Ctrl+a is more ergonomic than Ctrl+b), mouse support (set -g mouse on), vi copy mode, and intuitive split bindings — everything else is cosmetic and can wait. Here is that config, with a comment on every line explaining why it exists. Paste it into ~/.tmux.conf and reload with tmux source-file ~/.tmux.conf.

# --- prefix -------------------------------------------------
unbind C-b                 # drop the default prefix
set -g prefix C-a          # Ctrl+a is closer to home row
bind C-a send-prefix       # press Ctrl+a twice to send a literal Ctrl+a

# --- usability ----------------------------------------------
set -g mouse on            # click panes, drag borders, scroll natively
set -g history-limit 10000 # keep more scrollback than the default 2000
set -g base-index 1        # number windows from 1, not 0
setw -g pane-base-index 1  # number panes from 1 too

# --- copy mode ----------------------------------------------
setw -g mode-keys vi       # vi keys in copy mode
bind v copy-mode           # prefix v to enter copy mode quickly

# --- saner splits -------------------------------------------
bind | split-window -h -c "#{pane_current_path}"  # | splits left/right
bind - split-window -v -c "#{pane_current_path}"  # - splits top/bottom
# both open in the current pane's directory

# --- reload -------------------------------------------------
bind r source-file ~/.tmux.conf \; display "reloaded"

A few notes on syntax and versions. set -g mouse on is the correct single-option form for tmux 2.1 and later; tmux 2.1 (2015) consolidated the four older options (mode-mouse, mouse-select-pane, mouse-resize-pane, mouse-select-window) into one. If you find an old config using mode-mouse on, that’s why it looks different. The -c "#{pane_current_path}" flag makes new splits inherit the current directory — a small thing you’ll miss immediately if it’s absent.

That’s the whole config. Resist adding a status-bar theme on day one. If you do want one later, the Catppuccin tmux plugin (current tag v2.3.0) requires tmux 3.2+, and its README recommends a manual clone over the plugin manager because of a name conflict.

Modern Workflows: tmux as the Host for AI Coding Agents

tmux is the natural host for long-running AI coding agents. Detach a Claude Code or aider session before closing your laptop, reattach from any machine with tmux attach -t agent, and the agent’s process — and its full output history — is waiting for you. Both Claude Code and aider are terminal CLIs, so this isn’t a special integration: it’s the standard behavior of any foreground process running under a tmux session, applied to a tool that can run for many minutes unattended.

Agentic coding sessions are exactly the workload tmux was built to protect. An agent refactoring a large codebase or running a long test loop is a process you don’t want tied to your SSH connection’s lifetime. Start it inside tmux and it survives the drop.

Watch an Agent While You Work

The most useful layout is an agent in one pane and an editor in another, side by side. Start a session, split it, and run the agent on one side:

tmux new -s agent
# inside the session:
#   prefix |   -> split left/right
#   left pane:  claude   (or: aider)
#   right pane: nvim .

You watch the agent’s reasoning and diffs on the left while you review or edit on the right, both in one window, both surviving disconnects.

Supervise Multiple Agents with Synchronized Panes

When you run several agents in parallel — say, the same task across different branches — synchronized panes let you drive them together. With setw -g synchronize-panes on, every keystroke you type is sent to all panes in the window simultaneously, useful for issuing the same prompt across multiple agent sessions or resetting a set of parallel processes at once. Toggle it off the same way (synchronize-panes off) when you want to interact with one pane again. A common failure mode we hit with synchronized panes is forgetting synchronization is on and broadcasting a destructive command to every pane — bind it to a key with a visible indicator so its state is never ambiguous.

A Scripted Agent Layout

To get a reproducible three-pane supervision layout — agent on the left, editor top-right, logs bottom-right — without any extra dependency, drop this script in ~/bin/tmux-agent.sh:

#!/usr/bin/env bash
set -euo pipefail
SESSION="agent"

# First pane: the agent (left). -d creates the session detached.
tmux new-session -d -s "$SESSION" -x "$(tput cols)" -y "$(tput lines)"
tmux send-keys -t "$SESSION" "claude" C-m          # agent, left

# Split off the right side for the editor; the new pane becomes active.
tmux split-window -h -t "$SESSION"
tmux send-keys -t "$SESSION" "nvim ." C-m          # editor, top-right

# Split the right pane for logs; the new pane becomes active.
tmux split-window -v -t "$SESSION"
tmux send-keys -t "$SESSION" "tail -f dev.log" C-m # logs, bottom-right

# Focus the agent pane and attach. Targeting by direction (-L) instead of
# hardcoded pane indices keeps this correct whatever your base-index is.
tmux select-pane -t "$SESSION" -L
tmux attach -t "$SESSION"

Run chmod +x ~/bin/tmux-agent.sh once, then tmux-agent.sh whenever you start work. The agent keeps running if you detach; reattach from anywhere.

Persistence and Plugins

tmux sessions survive disconnects, but they do not survive a reboot on their own — for that you need plugins that serialize and restore state. The standard stack is the Tmux Plugin Manager (TPM) plus tmux-resurrect and tmux-continuum. Install TPM with:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Then add the plugin lines to the bottom of ~/.tmux.conf and press prefix + I to install:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
run '~/.tmux/plugins/tpm/tpm'   # keep this line last

Understand what each plugin actually does. tmux-resurrect saves and restores your session layout — windows, panes, and working directories — automatically. Restoring the programs that were running is opt-in and limited to a configured whitelist (@resurrect-processes), with editor sessions handled by @resurrect-strategy-vim/nvim and pane text preserved only when @resurrect-capture-pane-contents 'on' is set. Do not assume your agent restarts itself on restore; it won’t unless you’ve whitelisted it.

tmux-continuum automates the save every 15 minutes by default (configurable via @continuum-save-interval) and restores on tmux server start only when @continuum-restore 'on' is enabled. Together they mean a reboot costs you a layout reload, not a from-scratch rebuild.

Declarative Layouts with tmuxp

For layouts you launch repeatedly, define them once in YAML with tmuxp (repo: tmux-python/tmuxp) or the Ruby-based Tmuxinator. tmuxp reads configs from the XDG directory ~/.config/tmuxp/ (the legacy ~/.tmuxp/ path still works). Here is the agent supervision layout as ~/.config/tmuxp/agent.yaml:

session_name: agent
windows:
  - window_name: supervise
    layout: main-vertical
    shell_command_before:
      - cd ~/code/project
    panes:
      - claude
      - nvim .
      - tail -f dev.log

Load it with tmuxp load agent. The keys here — session_name, windows, window_name, layout, shell_command_before, panes — are all current in tmuxp 1.70.x. This is the declarative equivalent of the bash script above: one command, the same reproducible layout every time.

When NOT to Use tmux

If you’re working locally and don’t SSH into remote machines or run long-lived background processes, a modern terminal like Zellij or Warp gives you multiplexing with better defaults and no prefix-key learning curve; tmux’s advantage is specifically its server-side persistence and scriptability over SSH. Reaching for tmux when your terminal’s native tabs would do is added complexity for no gain.

A few decisive notes. Zellij is a Rust-based multiplexer with a mode-based system instead of a single prefix key, built-in session persistence and serialization, and an optional tmux-style prefix preset; it’s under active development and still pre-1.0. Warp is a cross-platform terminal — macOS, Linux, and Windows — with AI-integrated command suggestions, and its client was open-sourced (MIT + AGPL v3) in April 2026, so it is a viable option on Linux, not a macOS-only tool. Use tmux when you SSH into remote machines, run long-lived processes (build watchers, dev servers, AI agents), or need scripted reproducible layouts. Use a modern terminal when you want those features with less ceremony and don’t need tmux’s scripting depth or plugin breadth.

Conclusion

The reason tmux earns a place in an agent-heavy workflow is the same reason it earned one over SSH years ago: it decouples a running process from the terminal watching it. Start your next long agent run inside tmux new -s agent, detach when you step away, and reattach from wherever you land — the work continues without you. Paste the minimal config above, add tmux-resurrect when reboots start costing you layouts, and script the agent layout once so you never rebuild it by hand.

FAQs

What happens to a process running in tmux when the tmux server is killed or the machine reboots?

The process is terminated. tmux persistence only protects against client disconnects, not server shutdown, so killing the server with tmux kill-server or rebooting the machine ends every running process and discards every session. To survive a reboot you need tmux-resurrect to save the layout and tmux-continuum to restore it on server start, but even then the layout is restored, not the running programs, unless you whitelist specific processes via the resurrect-processes option.

What is the difference between tmux windows and panes?

A window is a full-screen tab inside a session, and a pane is a split region inside a single window. Switching windows replaces the entire screen with a different tab using prefix n or prefix p, while panes divide one visible window into side-by-side or stacked regions you navigate with prefix and the arrow keys. Use windows to separate distinct tasks like an app and its database, and panes to view related processes at once, such as an editor next to a live log.

Do I need to remap the prefix key from Ctrl+b to Ctrl+a?

No, remapping is optional and purely an ergonomics choice. The default prefix Ctrl+b works for every tmux command without any configuration. Many users remap it to Ctrl+a because the keys sit closer together on the keyboard, but this conflicts with the same binding in GNU screen and with the readline shortcut that moves the cursor to the start of a line. If you remap to Ctrl+a, add bind C-a send-prefix so pressing it twice still sends a literal Ctrl+a to the shell.

Should I use tmux or Zellij for running coding agents over SSH?

Both work because each runs a server on the remote host that keeps sessions alive across disconnects, so the choice comes down to defaults and ecosystem. Choose tmux when you want a large mature plugin ecosystem, deep scriptability through bash or tmuxp, and bindings that are already installed on most servers. Choose Zellij when you prefer discoverable mode-based controls over a prefix-key model and want session serialization without configuring plugins. Zellij remains pre-1.0, so tmux is the more conservative pick for long-lived setups.