Portfolio · Bespoke / hybrid

Custom structure

A sample documentation set for tmux, A terminal multiplexer for sessions, windows and panes.

Why this structure

tmux is hard to use until its model of sessions, windows and panes clicks, so the docs lead with concepts, then move to getting started, configuration, a reference of keys and commands, and a small recipe book. No single named framework dictates this order. It is chosen to match how people actually pick the tool up, which is what a custom structure is for.

Get docs like this

Apptmux

AboutA terminal multiplexer for sessions, windows and panes.

StructureBespoke / hybrid

AudienceTerminal users and developers who live in the shell.

Size5 sections · 10 pages

Browse the documentation

A real, navigable sample

This is the actual structure, with example articles. Click any page in the sidebar to read it.

github.com/tmux/tmux/wiki

The tmux model: sessions, windows, panes

tmux has three levels of structure, and everything else in the tool follows from them. Learn these three words and the rest makes sense.

The three levels

A server runs quietly in the background. It owns all of tmux's state and keeps running even after you close your terminal. You rarely touch it directly; it starts automatically the first time you run tmux.
A session is a workspace you attach to and detach from. A session contains one or more windows. You typically keep one session per project or task.
A window fills the whole screen, like a tab in a browser. Each window can be divided into panes, which are independent terminals shown side by side.

Why this design matters

The important consequence is that your work lives in the server, not in the terminal you are looking at. You can detach from a session, close the terminal, even log out over SSH, and the session keeps running. When you reattach later, every window, pane and running program is exactly where you left it.

That single property, surviving a disconnect, is the reason most people adopt tmux.

A rough analogy: the server is the building, a session is a room, a window is a desk in that room, and a pane is one sheet of paper on the desk. You move between them without anything being packed away.

The prefix key

Because tmux runs terminal programs inside itself, it needs a way to tell its own commands apart from keystrokes meant for those programs. It does this with a prefix key.

How it works

You press the prefix, release it, then press a command key. The default prefix is Ctrl+b. So to create a new window you press Ctrl+b, let go, then press c.

Throughout this documentation that is written as prefix c, meaning "press the prefix, then c".

Getting help

prefix ? shows the complete list of key bindings for your current configuration. It is the one binding worth memorising first, because it always reflects your real setup, including any changes you make later.

A common change

Many people find Ctrl+b awkward and remap the prefix to Ctrl+a, which is easier to reach. That change is covered in Configuration.

If a keystroke ever seems to do nothing, you may have pressed the prefix by accident, and tmux is waiting for a command key. Press Escape to cancel and start again.

Start, detach and reattach

This is the core loop of tmux: start a session, detach from it, and reattach later with everything intact.

Start a session

tmux new -s work

The -s work names the session work, which makes it easy to find later. Running plain tmux also works but gives the session a number instead of a name.

Detach

Press prefix d to detach. Your terminal returns to the normal shell, but the session keeps running in the background with all its programs.

List and reattach

tmux ls                 # list sessions
tmux attach -t work     # reattach to "work"

tmux attach on its own reattaches to the most recent session, and tmux a is a common short form.

End a session

When you are truly finished, close all its programs, or:

tmux kill-session -t work

This detach-and-reattach cycle is what makes tmux invaluable over SSH. Start a long job inside tmux, detach, and disconnect. The job keeps running on the server, and you can reattach from anywhere to check on it.

Windows and panes

Inside a session you organise work into windows and panes, all managed with the prefix.

Windows (like tabs)

prefix c: create a new window
prefix n / prefix p: next / previous window
prefix 0 to prefix 9: jump to a window by its number
prefix ,: rename the current window
prefix w: choose a window from a list
prefix &: close the current window

The status bar along the bottom lists your windows, with the active one highlighted.

Panes (splits)

prefix %: split the current pane left and right
prefix ": split it top and bottom
prefix then an arrow key: move focus between panes
prefix z: zoom the current pane to fill the window, and press again to restore
prefix x: close the current pane
prefix space: cycle through the preset layouts

Putting it together

A typical setup is one window per task, split into a couple of panes, for example an editor in one and a running server or test watcher in another.

Zoom (prefix z) is the pane feature people miss most. It gives one pane the whole screen without disturbing your layout, perfect for reading a long file, then snaps back.

Your ~/.tmux.conf

tmux reads its configuration from ~/.tmux.conf when the server starts. This is where you change key bindings, appearance and behaviour.

Where it applies

Because settings load when the server starts, a change does not affect a session that is already running until tmux reloads the file.

Reloading without restarting

From inside a running session, reload the config with:

tmux source-file ~/.tmux.conf

Or run source-file ~/.tmux.conf from the command prompt (prefix :). Better still, bind a key to do it, so a reload is one shortcut away (see the starter config recipe).

Syntax basics

Configuration lines are tmux commands:

set -g option value sets a global option.
setw -g option value sets a window option.
bind key command binds a key, pressed after the prefix, to a command.
unbind key removes a binding.

-g means global, the setting you almost always want. Without it, an option applies only to the current session or window and is lost when it closes.

Remap the prefix and enable the mouse

Two of the most common first changes to a fresh tmux.

Remap the prefix to Ctrl+a

Ctrl+b is awkward to reach. Many people move the prefix to Ctrl+a:

unbind C-b
set -g prefix C-a
bind C-a send-prefix

The third line lets you send a literal Ctrl+a to a program by pressing the prefix twice, which matters if you rely on shell shortcuts that use it.

Enable mouse support

set -g mouse on

With the mouse on you can click to select a pane or window, drag pane borders to resize, and scroll a pane's history with the wheel.

Apply it

Add these to ~/.tmux.conf and reload with tmux source-file ~/.tmux.conf.

Mouse support is a matter of taste. It makes tmux friendlier for newcomers, but some long-time users leave it off so terminal text selection and copy behave the traditional way.

Session and window commands

Commands you run from the shell, or from the tmux command prompt opened with prefix :. Every key binding ultimately runs one of these.

From the shell

tmux new -s NAME: create a named session
tmux ls: list sessions
tmux attach -t NAME: attach to a session
tmux kill-session -t NAME: end a session
tmux kill-server: stop tmux entirely, ending every session

From the command prompt (prefix :)

new-window -n NAME: create a named window
rename-window NAME: rename the current window
rename-session NAME: rename the current session
split-window -h: split left/right (-v for top/bottom)
swap-window -t N: reorder windows

Discoverability

The command prompt has tab completion, and prefix ? lists which key runs which command. Between them you can learn the command behind any shortcut.

Anything you can bind to a key, you can also type at the prompt, and the other way round. Key bindings are just saved shortcuts for these commands.

Default key bindings

The most-used default bindings, all pressed after the prefix. Your own config may change these; prefix ? always shows the current set.

Sessions and windows

d: detach from the session
c: new window
,: rename window
w: list and choose a window
&: close window
n / p: next / previous window
0-9: select window by number

Panes

%: split left/right
": split top/bottom
arrow keys: move between panes
x: close pane
z: zoom pane
space: cycle layouts
o: cycle through panes

Other

[: enter copy mode (scroll and select text)
]: paste the copied text
t: show a clock
?: list every binding

If you only remember one, remember prefix ?. It is the built-in, always-accurate reference for every other key.

A sensible starter config

A small ~/.tmux.conf that smooths off the rough edges most people hit. Drop it in, start tmux, and you have a friendlier setup than the defaults.

# remap prefix to Ctrl-a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# quality of life
set -g mouse on              # click and scroll
set -g base-index 1          # number windows from 1
setw -g pane-base-index 1    # number panes from 1
set -g history-limit 10000   # keep more scrollback
setw -g mode-keys vi         # vi keys in copy mode

# more memorable splits
bind | split-window -h       # prefix | splits left/right
bind - split-window -v       # prefix - splits top/bottom

# reload config with prefix r
bind r source-file ~/.tmux.conf \; display "Reloaded"

What each block does

The first block moves the prefix to Ctrl+a.
The quality-of-life block turns on the mouse, starts numbering at 1 so the keys line up with the layout, keeps more scrollback, and uses vi keys when selecting text.
The splits block adds prefix | and prefix -, easier to remember than % and ".
The last line reloads the config with prefix r.

Treat this as a starting point, not a finished setup. Add to it one line at a time as you notice something you wish tmux did differently.

Copy and paste text

tmux has its own copy mode, so you can select and copy text using the keyboard, independently of your terminal or the mouse.

Copy with the keyboard

Press prefix [ to enter copy mode. The screen freezes and you can scroll.
Move to the start of the text with the arrow keys, or vi keys if you set mode-keys vi.
Begin the selection (Space in vi mode), move to the end, and copy (Enter in vi mode).
Press prefix ] to paste the copied text.

Scrolling history

Copy mode is also how you scroll back through a pane's output without the mouse. Enter it with prefix [, scroll with the arrows or PageUp, and press q to leave.

With the mouse

With set -g mouse on, you can select text by dragging, which copies it into the tmux buffer automatically, and scroll with the wheel.

tmux keeps its copied text in its own buffer, separate from the system clipboard. Bridging the two is possible but platform-specific, often using a helper like xclip, wl-copy or pbcopy.