TMUX(1)

📦

version 3.8 · 9 versions

3.8 · arch rolling, fedora 44, nixpkgs unstable (latest)
3.2a · centos-stream 9
3.3a · centos-stream 10
3.2a · ubuntu jammy
3.7c · alpine 3.24, fedora 43, fedora 44, nixos 26.05, ubuntu stonking
3.4 · ubuntu noble
3.3a · debian bookworm
3.6a · alpine 3.23, fedora 44, ubuntu resolute
3.5a · alpine 3.22, debian trixie, fedora 43, opensuse-leap 16.0, ubuntu questing

, in arch rolling, fedora 44, nixpkgs unstable

💖 TMUX(1) 💖

okay bestie, sit down, hydrate, because we're about to talk about the General Commands Manual entry for tmux — the terminal multiplexer — and she is iconic. 🎀

✨ NAME ✨

tmux — terminal multiplexer. that's it. that's the whole name. she's mysterious, she's powerful, she's the main character.

🌸 SYNOPSIS 🌸

tmux [-2CDhlNuVv] [-c shell-command] [-f file] [-L socket-name]
     [-S socket-path] [-T features] [command [flags]]

🦋 DESCRIPTION 🦋

so like. tmux is a terminal multiplexer. what that means (fr fr) is she lets you create, access, and control a whole bunch of terminals from one single screen. it's giving "one screen, infinite windows" energy. 💅

and the way that she can be detached from a screen and just keep running in the background, minding her own business, and then later you reattach to her like nothing ever happened?? obsessed. ✨

when tmux starts up, she creates a new session with a single window and puts it on your screen. at the bottom of the screen there's a status line showing info about the current session, and that's also where you go to type in interactive commands. 💖

okay so definitions, because the terminology matters:

A session is one single collection of pseudo terminals that tmux is managing. every session has one or more windows linked to it.
A window takes up the entire screen and may be split into rectangular panes, and each pane is its own separate pseudo terminal. (if you want the technical nitty-gritty on pseudo terminals, the pty(4) manual page has you covered 🧚)
Any number of tmux instances may connect to the same session, and any number of windows may live in the same session. no cap.
Once all sessions are killed, tmux exits. periodt.

each session is persistent — she will survive an accidental disconnection (think your ssh(1) connection timing out 😭) or an intentional detach (that's the ‘C-b d’ key strokes, iykyk). and you can reattach to her with:

$ tmux attach

in tmux, a session gets displayed on screen by a client, and all the sessions are managed by a single server. the server and each client are separate processes, and they talk to each other through a socket in /tmp. 💅

the options are as follows:

-2 — force tmux to assume the terminal supports 256 colours. this is equivalent to -T 256. bestie, it's the same thing. 🎀
-C — start in control mode (peep the “CONTROL MODE” section). give it twice (-CC) and it disables echo.
-c shell-command — execute shell-command using the default shell. if it's necessary, the tmux server will get started so it can retrieve the default-shell option. this one exists for compatibility with sh(1) when tmux is used as a login shell.
-D — do not start the tmux server as a daemon. this also turns the exit-empty option off. heads up: with -D, command may not be specified. ⚠️
-f file — specify an alternative configuration file. by default, tmux loads the system configuration file from /etc/tmux.conf if it's present, and then looks for a user configuration file at ~/.tmux.conf or $XDG_CONFIG_HOME/tmux/tmux.conf.

the configuration file is just a set of tmux commands that get executed in sequence when the server is first started. tmux loads configuration files once, when the server process has started. if you wanna load a file later, the source-file command is right there. 🫶

tmux shows any error messages from commands in configuration files in the first session created, and then just keeps on processing the rest of the configuration file. she doesn't stop for anybody.

-h — print usage information and exit.
-L socket-name — tmux stores the server socket in a directory under TMUX_TMPDIR, or /tmp if that's unset. the default socket is named default. this option lets you specify a different socket name, which means you can run several independent tmux servers. unlike -S, a full path is not necessary: the sockets all get created in a directory tmux-UID under the directory given by TMUX_TMPDIR, or in /tmp. the tmux-UID directory is created by tmux and must not be world readable, writable or executable. 🔒

if the socket is accidentally removed, you can send the SIGUSR1 signal to the tmux server process to recreate it (note that this will fail if any parent directories are missing).

-l — behave as a login shell. ngl this flag currently has no effect and is only there for compatibility with other shells when using tmux as a login shell. 💀
-N — do not start the server even if the command would normally do so (for example new-session or start-server).
-S socket-path — specify a full alternative path to the server socket. if -S is specified, the default socket directory is not used and any -L flag is ignored. 🙈
-T features — set terminal features for the client. this is a comma-separated list of features. see the terminal-features option.
-u — write UTF-8 output to the terminal even if the first environment variable of LC_ALL, LC_CTYPE, or LANG that is set does not contain "UTF-8" or "UTF8".
-V — report the tmux version. ✨
-v — request verbose logging. log messages get saved into tmux-client-PID.log and tmux-server-PID.log files in the current directory, where PID is the PID of the server or client process. if you specify -v twice, an additional tmux-out-PID.log file is generated, containing a copy of everything tmux writes to the terminal. 🍓

you can send the SIGUSR2 signal to the tmux server process to toggle logging between on (as if -v was given) and off.

command [flags] — this specifies one of a set of commands used to control tmux, as described in the following sections. if no commands are specified, the command in default-client-command is assumed, which defaults to new-session.

👑 DEFAULT KEY BINDINGS 👑

tmux can be controlled from an attached client using a key combination of a prefix key — ‘C-b’ (Ctrl-b) by default — followed by a command key. it's a little two-step, but she eats every time. 💅

the default command key bindings are:

C-b — send the prefix key (C-b) through to the application.
C-o — rotate the panes in the current window forwards.
C-z — suspend the tmux client.
! — break the current pane out of the window.
" — split the current pane into two, top and bottom.
# — list all paste buffers.
$ — rename the current session.
% — split the current pane into two, left and right.
& — kill the current window.
' — prompt for a window index to select.
( — switch the attached client to the previous session.
) — switch the attached client to the next session.
* — create a new floating pane.
, — rename the current window.
- — delete the most recently copied buffer of text.
. — prompt for an index to move the current window.
0 to 9 — select windows 0 to 9.
: — enter the tmux command prompt.
; — move to the previously active pane.
= — choose which buffer to paste interactively from a list.
? — list all key bindings.
D — choose a client to detach.
L — switch the attached client back to the last session.
[ — enter copy mode to copy text or view the history.
] — paste the most recently copied buffer of text.
c — create a new window.
d — detach the current client.
f — prompt to search for text in open windows.
i — display some information about the current window.
l — move to the previously selected window.
m — mark the current pane (see select-pane -m).
M — clear the marked pane.
n — change to the next window.
o — select the next pane in the current window.
p — change to the previous window.
q — briefly display pane indexes.
r — force redraw of the attached client.
s — select a new session for the attached client interactively.
t — show the time. ⏰
T — change the current pane title.
w — choose the current window interactively.
x — kill the current pane.
z — toggle zoom state of the current pane.
Tab — choose a new window and session by fuzzy matching.
{ — swap the current pane with the previous pane.
} — swap the current pane with the next pane.
g 1, 2, 3, 4 and g Up, Down, Left, Right — move floating pane to corners or edges. Meta resizes the pane as well.
~ — show previous messages from tmux, if any.
Page Up — enter copy mode and scroll one page up.
Up, Down, Left, Right — change to the pane above, below, to the left, or to the right of the current pane.
M-1 to M-7 — arrange panes in one of the seven preset layouts: even-horizontal, even-vertical, main-horizontal, main-horizontal-mirrored, main-vertical, main-vertical-mirrored, or tiled.
Space — arrange the current window in the next preset layout.
M-n — move to the next window with a bell or activity marker.
M-o — rotate the panes in the current window backwards.
M-p — move to the previous window with a bell or activity marker.
C-Up, C-Down, C-Left, C-Right — resize the current pane in steps of one cell.
M-Up, M-Down, M-Left, M-Right — resize the current pane in steps of five cells.

key bindings may be changed with the bind-key and unbind-key commands. 🎀

and bestie… we are SO not done. there are 23 more parts of this whole entire saga coming your way. 💖✨

✨ COMMAND PARSING AND EXECUTION ✨

okay bestie, so tmux has a whole library of commands it uses to control itself. Each one has a name and can take zero or more flags and arguments. You can bind them to a key with the bind-key command, or run them straight from your shell prompt, a shell script, a configuration file, or the command prompt. 🫶

Like, the exact same set-option command run from the shell prompt, from ~/.tmux.conf, and bound to a key can look like this:

$ tmux set-option -g status-style bg=cyan

set-option -g status-style bg=cyan

bind-key C set-option -g status-style bg=cyan

So here the command name is set-option, -g is a flag, and status-style and bg=cyan are arguments. no cap 🎀

Now — tmux is lowkey a huge nerd and it splits "command parsing" from "execution". To actually execute a command, tmux needs it broken up into its name + arguments first. That first bit is command parsing. And here's the vibe check: if you run a command from the shell, your shell parses it. If it comes from inside tmux or from a config file, tmux does the parsing. 💅

Times when tmux is the one parsing:

in a configuration file;
typed at the command prompt (see command-prompt);
given to bind-key;
passed as arguments to if-shell or confirm-before.

To execute commands, every client has its own ‘command queue’. There's also a global command queue that isn't attached to any client, and it gets used on startup for config files like ~/.tmux.conf. Parsed commands get added to the queue and run in order. 🦋

Some commands — looking at you, if-shell and confirm-before — parse their argument to make a new command, and that new command is inserted immediately after themselves. Which means arguments can get parsed twice or even more: once when the parent command (like if-shell) is parsed, and again when it parses and executes its own command. iconic behaviour honestly 😭

And some commands — if-shell, run-shell and display-panes — will literally stop execution of the subsequent commands on the queue until something happens. For if-shell and run-shell that something is a shell command finishing; for display-panes it's a key being pressed. ⏸️

Example time! These commands:

new-session; new-window
if-shell "true" "split-window"
kill-session

Will execute new-session, new-window, if-shell, the shell command true(1), split-window and kill-session in that order. ✨

The “COMMANDS” section lists the tmux commands and their arguments.

🔍 PARSING SYNTAX 🔍

This section is all about the syntax of commands parsed by tmux — so like, in a configuration file or at the command prompt. Heads up though: when commands are entered into the shell, they get parsed by the shell instead — see for example ksh(1) or csh(1). 🌸

Every command gets terminated by a newline or a semicolon (;). Commands separated by semicolons together form a ‘command sequence’ — and if one command in that sequence hits an error, none of the following commands run. periodt 🛑

It's recommended that a semicolon used as a command separator should be written as an individual token, for example from sh(1):

$ tmux neww \; splitw

Or:

$ tmux neww ';' splitw

Or from the tmux command prompt:

neww ; splitw

However, a trailing semicolon is also interpreted as a command separator, for example in these sh(1) commands:

$ tmux neww\; splitw

Or:

$ tmux 'neww;' splitw

So like the examples show, when you're running tmux from the shell you have to be extra careful with quoting semicolons:

Semicolons that should be interpreted as a command separator should be escaped according to the shell conventions. For sh(1) this typically means quoted (such as neww ';' splitw) or escaped (such as neww \; splitw).
Individual semicolons or trailing semicolons that should be interpreted as arguments should be escaped twice: once according to the shell conventions and a second time for tmux; for example:

$ tmux neww 'foo\;' bar
$ tmux neww foo\\\; bar

Semicolons that are not individual tokens or trailing another token should only be escaped once according to shell conventions; for example:

$ tmux neww 'foo-;-bar'
$ tmux neww foo-\;-bar

Comments are marked by the unquoted # character — anything left on the line after a comment is ignored until the end of the line. 💬

If the last character of a line is \, that line gets joined with the following line (the \ and the newline are completely removed). This is called line continuation and it applies both inside and outside quoted strings and in comments — but not inside braces. 🧚

Command arguments can be written as strings surrounded by single (') quotes or double (") quotes, or as command lists surrounded by braces ({}). You need this when the argument contains any special character. Single and double quoted strings can't span multiple lines except with line continuation. Braces, though? Braces can totally span multiple lines. slay 💅

Outside of quotes, and inside double quotes, these replacements happen:

Environment variables preceded by $ are replaced with their value from the global environment (see the “GLOBAL AND SESSION ENVIRONMENT” section).
A leading ~ or ~user is expanded to the home directory of the current or specified user.
\uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint corresponding to the given four or eight digit hexadecimal number.
When preceded (escaped) by a \, the following characters are replaced: \e by the escape character; \r by a carriage return; \n by a newline; and \t by a tab.
\ooo is replaced by a character of the octal value ooo. Three octal digits are required, for example \001. The largest valid character is \377.
Any other characters preceded by \ are replaced by themselves (that is, the \ is removed) and are not treated as having any special meaning — so for example \; will not mark a command sequence and \$ will not expand an environment variable.

Braces get parsed as a configuration file (so conditions such as ‘%if’ are processed) and then converted into a string. They're designed to avoid needing extra escaping when you pass a group of tmux commands as an argument (for example to if-shell). These two examples produce an identical command — and note that no escaping is needed when using {}: 🌈

if-shell true {
    display -p 'brace-dollar-foo: }$foo'
}

if-shell true "display -p 'brace-dollar-foo: }\$foo'"

Braces may be enclosed inside braces, for example:

bind x if-shell "true" {
    if-shell "true" {
        display "true!"
    }
}

Environment variables can be set using the syntax ‘name=value’, for example ‘HOME=/home/user’. Variables set during parsing are added to the global environment. A hidden variable may be set with ‘%hidden’, for example:

%hidden MYVAR=42

Hidden variables are not passed to the environment of processes created by tmux. See the “GLOBAL AND SESSION ENVIRONMENT” section. 🙈

Commands may be parsed conditionally by surrounding them with ‘%if’, ‘%elif’, ‘%else’ and ‘%endif’. The argument to ‘%if’ and ‘%elif’ is expanded as a format (see “FORMATS”) and if it evaluates to false (zero or empty), subsequent text is ignored until the closing ‘%elif’, ‘%else’ or ‘%endif’. For example:

%if "#{==:#{host},myhost}"
set -g status-style bg=red
%elif "#{==:#{host},myotherhost}"
set -g status-style bg=green
%else
set -g status-style bg=blue
%endif

Will change the status line to red if running on ‘myhost’, green if running on ‘myotherhost’, or blue if running on another host. 🎨

Conditionals may be given on one line too, for example:

%if #{==:#{host},myhost} set -g status-style bg=red %endif

✨ COMMANDS ✨

okay bestie this is the big one 💖 this whole section is the commands tmux supports. Most of them take an optional -t argument (and sometimes -s too) with one of target-client, target-session, target-window, or target-pane — those are just fancy ways of saying which client, session, window or pane the command should mess with 💅

target-client should be the name of the client, usually the pty(4) file the client is connected to — so like /dev/ttyp1 or ttyp1 for the client attached to /dev/ttyp1, either one works. If you don't specify a client, tmux tries to figure out which one you're currently using, and if that fails it just reports an error 😭. You can list clients with the list-clients command.

target-session gets tried in this order:

A session ID prefixed with a $.
An exact name of a session (as listed by the list-sessions command).
The start of a session name — so like mysess would match a session named mysession.
A glob(7) pattern which is matched against the session name.

If the session name is prefixed with an =, only an exact match counts, periodt. So =mysess will only match exactly mysess, not mysession, no exceptions 🌸

If a single session is found, that's your target session. Multiple matches = error, bestie 💀. And if a session is omitted entirely, the current session is used if there is one; if there's no current session available, the most recently used one gets picked 👑

target-window (or src-window or dst-window) specifies a window in the form session:window. The session part follows the same rules as target-session, and window gets looked for in this order:

A special token, listed below.
A window index — so mysession:1 is window 1 in session mysession.
A window ID, such as @1.
An exact window name, such as mysession:mywindow.
The start of a window name, such as mysession:mywin.
As a glob(7) pattern matched against the window name.

Same as with sessions, a = prefix means exact match only 🎀. An empty window name specifies the next unused index if that's appropriate (like for the new-window and link-window commands), otherwise the current window in session is chosen.

These special tokens are available to point at particular windows. Each one has a single-character alternative form too 🦋

{start} / ^ — the lowest-numbered window
{end} / $ — the highest-numbered window
{last} / ! — the last (previously current) window
{next} / + — the next window by number
{previous} / - — the previous window by number
{current} / @ — the current window
{mouse} / = — the window where the mouse event happened

target-pane (or src-pane or dst-pane) can be a pane ID, or it takes a similar form to target-window but with the optional addition of a period followed by a pane index or pane ID, like for example mysession:mywindow.1 💖. If you leave the pane index out, the currently active pane in the specified window is used. These special tokens work for the pane index:

{last} / ! — the last (previously active) pane
{next} / + — the next pane by number
{previous} / - — the previous pane by number
{top} — the top pane
{bottom} — the bottom pane
{left} — the leftmost pane
{right} — the rightmost pane
{top-left} — the top-left pane
{top-right} — the top-right pane
{bottom-left} — the bottom-left pane
{bottom-right} — the bottom-right pane
{up-of} — the pane above the active pane
{down-of} — the pane below the active pane
{left-of} — the pane to the left of the active pane
{right-of} — the pane to the right of the active pane
{active} / @ — the active pane
{marked} / ~ — the marked pane
{mouse} / = — the pane where the mouse event happened

The tokens + and - may be followed by an offset, like this bestie:

select-window -t:+2

Also!! target-session, target-window or target-pane can consist entirely of the token {mouse} (alternative form =) to specify the session, window or pane where the most recent mouse event occurred (check the “MOUSE SUPPORT” section), or {marked} (alternative form ~) to specify the marked pane (check select-pane -m) 🐭✨

Sessions, windows and panes are each numbered with a unique ID — session IDs are prefixed with a $, windows with a @, and panes with a % 💅. These are unique and stay unchanged for the whole life of the session, window or pane in the tmux server, fr fr. The pane ID gets passed to the child process of the pane in the TMUX_PANE environment variable 🌈. IDs can be displayed using the session_id, window_id, or pane_id formats (see the “FORMATS” section) and the display-message, list-sessions, list-windows or list-panes commands.

target-session, target-window or target-pane each denote the ‘type’ of target the command needs to work on. If a target isn't explicitly qualified using : and ., tmux will pick whatever seems like the best choice available 👑. For example, if a target-pane of 1 is used with a current window that has only one pane, tmux knows that the 1 can't mean a pane, so it'll look for the active pane in window 1, or the active pane in the current window in session 1. Only if none of those are there will it report an error 💀. If it really matters that a specific pane, window or session always gets used — like from a script — the target should be fully qualified (for example a target-pane of -t:.1), or else pane, window or session IDs should be used. Don't be sloppy, bestie 🫶

shell-command arguments are sh(1) commands. This may be a single argument passed to the shell, for example:

new-window 'vi ~/.tmux.conf'

Will run:

/bin/sh -c 'vi ~/.tmux.conf'

Unless specified, tmux uses the value of default-shell in place of /bin/sh 🌸

Also, the new-window, new-session, split-window, respawn-window, respawn-pane and display-popup commands allow shell-command to be given as multiple arguments and executed directly (without sh -c) 🎀. This can dodge issues with shell quoting, iconic honestly. For example:

$ tmux new-window vi ~/.tmux.conf

Will run vi(1) directly without invoking the shell ✨

command [argument ...] refers to a tmux command, either passed with the command and arguments separately, for example:

bind-key F1 set-option status off

Or passed as a single string argument in .tmux.conf, for example:

bind-key F1 { set-option status off }

Example tmux commands include:

refresh-client -t/dev/ttyp2

rename-session -tfirst newname

set-option -wt:0 monitor-activity on

new-window ; split-window -d

bind-key R source-file ~/.tmux.conf \; \
        display-message "source-file done"

Or from sh(1):

$ tmux kill-window -t :1

$ tmux new-window \; split-window -d

$ tmux new-session -d 'vi ~/.tmux.conf' \; split-window -d \; attach

🫶 CLIENTS AND SESSIONS 🫶

The tmux server manages clients, sessions, windows and panes, bestie 💖. Clients are attached to sessions to interact with them — either when they're created with the new-session command, or later with the attach-session command. Each session has one or more windows linked into it. Windows may be linked to multiple sessions, and they're made up of one or more panes, each of which contains a pseudo terminal 👑. Commands for creating, linking and otherwise manipulating windows live in the “WINDOWS AND PANES” section.

The following commands are available to manage clients and sessions 🦋

attach-session [-dErx] [-c working-directory] [-f flags] [-t target-session] — (alias: attach) If you run it from outside tmux, attach to target-session in the current terminal. target-session must already exist — to create a new session, see the new-session command (with -A to create or attach) 😌. If used from inside, it switches the currently attached session over to target-session. If -d is specified, any other clients attached to the session get detached 💀. If -x is given, it sends SIGHUP to the parent process of the client as well as detaching the client, which typically causes it to exit. -f sets a comma-separated list of client flags. The flags are:
- ignore-size — the client does not affect the size of other clients
- new-layouts — use the new layout string format
- no-detach-on-destroy — do not detach the client when the session it is attached to is destroyed if there are any other sessions
- no-output — the client does not receive pane output in control mode
- pause-after=seconds — output is paused once the pane is seconds behind in control mode
- read-only — the client is read-only
- wait-exit — wait for an empty line input before exiting in control mode

A leading ! turns a flag off if the client is already attached 🎀. -r is an alias for -f read-only,ignore-size. When a client is read-only, only keys bound to the detach-client or switch-client commands have any effect. That's it. Nothing else works. Respect the read-only era 💅

If no server is started, attach-session will attempt to start it — but this will fail unless sessions are created in the configuration file 😭

The target-session rules for attach-session are slightly adjusted: if tmux needs to select the most recently used session, it will prefer the most recently used unattached session 🫶

-c will set the session working directory (used for new windows) to working-directory.

If -E is used, the update-environment option will not be applied.

detach-client [-aP] [-E shell-command] [-s target-session] [-t target-client] — (alias: detach) Detach the current client if it's bound to a key, the client specified with -t, or all clients currently attached to the session specified by -s 🌸. The -a option kills all but the client given with -t. If -P is given, it sends SIGHUP to the parent process of the client, typically causing it to exit 💀. With -E, run shell-command to replace the client ✨

`has-session` 💅

has-session [-t target-session]
              (alias: has)

Bestie, this one is a straight-up vibe check on a session. If the session you named with -t target-session does not exist, it yells at you and bails with exit status 1. If it does exist? Chill, exits 0. That's it, that's the whole job. ✨

`kill-server` 💀

kill-server

No flags, no mercy — this one takes out the entire tmux server, every client hanging off it, and destroys all the sessions. It's giving scorched earth, fr fr. 😭

`kill-session` 🔥

kill-session [-aCg] [-f filter] [-t target-session]

This destroys the session you point at with -t target-session — closes any windows linked to it (and only it), and detaches every client attached to it. Other sessions get to live another day. Slay.

-a — nuke all the sessions except the one you specified. Bye besties 👋
-f filter — when you're using -a, this sets a filter. Only the sessions where the filter comes back true get killed. So it's a targeted takedown, not a bloodbath.
-g — if that session is part of a session group, then the whole group goes down, not just the one.
-C — clears alerts (that's bell, activity, or silence) in every window linked to the session. Peace and quiet, periodt.

`list-clients` 📋

list-clients [-r] [-F format] [-f filter] [-O sort-order] [-t target-session]
      (alias: lsc)

Shows you every client currently attached to the server. The whole roster.

-F format — picks the format of each line.
-f filter — only clients where the filter is true show up. Filter deets live in the “FORMATS” section, iykyk.
-O sort-order — how to sort them. Pick one of: 'name', 'size', 'creation' (that's time), or 'activity' (also time).
-r — reverses the sort order. Flip it and reverse it. 🔄
-t target-session — if you give this, it only lists clients connected to that session. So specific.

`list-commands` 🎀

list-commands [-F format] [command]
      (alias: lscm)

Lists the syntax of command — or, if you leave it out, of every single command tmux supports. It's the full menu. The -F format flag lets you control the format of what comes back.

`list-sessions` 🌸

list-sessions [-r] [-F format] [-f filter] [-O sort-order]
      (alias: ls)

Lists all the sessions the server is managing. Your whole collection, bestie. 💖

-F format — sets the format of each line.
-f filter — only sessions where the filter is true show up. Check the “FORMATS” section for how filters work.
-O sort-order — sorting time. Choose one of: 'index', 'name', 'creation' (time), or 'activity' (time).
-r — reverses the sort order. The way that flips the whole list around, iconic.

`lock-client` 🔒

lock-client [-t target-client]
      (alias: lockc)

Locks target-client. Need the deets on what locking actually does? Go read the lock-server command, girlie.

`lock-session` 🔒✨

lock-session [-t target-session]
      (alias: locks)

Locks all the clients attached to target-session. Every one of them. No entry without the key. 👑

`new-session` 🌈

new-session [-AdDEPX] [-c start-directory] [-e environment] [-f flags]
      [-F format] [-n window-name] [-s session-name] [-t group-name]
      [-x width] [-y height] [shell-command [argument ...]]
      (alias: new)

Creating a whole new session called session-name. Main character origin story. ✨

So the tea: the new session attaches itself to your current terminal unless you pass -d. window-name and shell-command are the name of, and the shell command to run in, that very first window. With -d, the starting size comes from the global default-size option — and you can override that size with -x and -y. Passing '-' means "use the size of the current client, if there is one." And heads up: if you give -x or -y, the default-size option gets set for the session. -f sets a comma-separated list of client flags (peep attach-session for those).

If you run this from a terminal, any termios(4) special characters get saved and used for new windows in the new session. Cute.

Now the -A flag: it makes new-session behave like attach-session whenever session-name already exists. And if -A is in play, then -D behaves like -d does to attach-session, and -X behaves like -x does to attach-session.

If -t is given, it specifies a session group. Sessions in the same group share the same set of windows — new windows are linked into every session in the group, and any windows closed get removed from all of them. But the current and previous window, and any session options, stay independent. Any session in a group can be killed without it affecting the others. Group chat, but make it windows. 🫶

The group-name argument can be:

the name of an existing group — in which case the new session gets added to that group;
the name of an existing session — the new session joins the same group as that session, and a new group gets created if one's needed;
the name for a brand new group containing only the new session.

-n and shell-command are invalid if -t is used. Don't do it. 🚫

The -P option prints info about the new session once it's been created. By default it uses the format '#{session_name}:', but you can hand it a different format with -F.

If -E is used, the update-environment option will not be applied. And -e takes the form 'VARIABLE=value' and sets an environment variable for the newly created session — you can use it multiple times if you're feeling extra. 💅

`refresh-client` 🧚

refresh-client [-cDlLRSU] [-A pane:state] [-B name:what:format] [-C
      size] [-f flags] [-r pane:report] [-t target-client]
      [adjustment]
      (alias: refresh)

Refreshes the current client if you've bound this to a key, or refreshes a single client if you point at one with -t. And if -S is specified, it only updates the client's status line — nothing else, just the glow-up on the bar.

Now here's where it gets spicy. The -U, -D, -L, -R, and -c flags let you change the visible portion of a window that's bigger than the client:

-U moves the visible part up by adjustment rows
-D moves it down
-L moves it left by adjustment columns
-R moves it right
-c snaps back to tracking the cursor automatically

If adjustment is left out, 1 is used. ⚠️ Important caveat bestie: the visible position is a property of the client, not of the window — so changing the current window in the attached session resets it. Rude, but that's the rule.

-C size — sets the width and height of a control mode client, or of a window for a control mode client. size has to be either 'widthxheight' or 'window ID:widthxheight', like '80x24' or '@0:80x24'.
-A pane:state — lets a control mode client trigger actions on a pane. The argument is a pane ID (with that leading '%'), then a colon, then one of 'on', 'off', 'continue' or 'pause'.
- If 'off', tmux will not send output from the pane to the client, and if all clients have turned the pane off, it'll stop reading from the pane.
- If 'continue', tmux goes back to sending output to the pane if it was paused (whether that was manually or via the pause-after flag).
- If 'pause', tmux pauses the pane.
- -A can be given multiple times for different panes. Stack 'em.
-B name:what:format — sets a subscription to a format for a control mode client. The argument gets split into three items by colons: name is a name for the subscription, what is a type of item to subscribe to, and format is the format. Once a subscription is added, changes to the format get reported with the %subscription-changed notification, at most once a second. If you only give the name, the subscription is removed. And what can be empty to check the format only for the attached session, or it can be one of: a pane ID like '%0'; '%*' for all panes in the attached session; a window ID like '@0'; or '@*' for all windows in the attached session.
-f flags — sets a comma-separated list of client flags. See attach-session.
-r pane:report — lets a control mode client give info about a pane via a report (like the response to OSC 10). The argument is a pane ID (with a leading '%'), a colon, then a report escape sequence.
-l — requests the clipboard from the client using the xterm(1) escape sequence and stashes it in a new paste buffer. 📋
-L, -R, -U, -D — move the visible portion of the window left, right, up or down by adjustment, if the window is bigger than the client.
-c — resets so the position follows the cursor. Also peep the window-size option.

`rename-session` ✏️

rename-session [-t target-session] new-name
      (alias: rename)

Renames the session to new-name. Glow-up complete. 💖

`server-access` 🔐

server-access [-adglrw] [user | group]

Changes the access, or the read/write permission, of a user or group. The user running the tmux server (its owner) and the root user cannot be changed and are always permitted access. -g changes a group rather than a user.

-a and -d — give or revoke access for the specified user or group. And if a client is already attached, -d causes it to be detached unless it's still permitted by another entry. Sneaky but fair.
-r and -w — change the permissions for user or group. -r makes matching clients read-only, -w makes them writable.
-l — lists the current access permissions. User entries show with 'U', group entries with 'G', and read-only or writable entries with 'R' or 'W' — for example 'user1 (U,W)' or 'testgroup (G,R)'. If both a user entry and a group entry match a client, the user entry takes precedence. And heads up: only the effective group ID of the client is used, not its supplementary groups.

By default the access list is empty, and tmux creates sockets with file system permissions that prevent access by any user other than the owner (and root). Those permissions have to be changed manually. And bestie, listen—

Great care should be taken not to allow access to untrusted users even read-only. ⚠️

`show-messages` 📨

show-messages [-JT] [-t target-client]
      (alias: showmsgs)

Shows server messages or info. Messages get stored, up to a maximum — that max is set by the message-limit server option. -J and -T show debugging information about jobs and terminals. 🛠️

`source-file` 📂

source-file [-Fnqv] [-t target-pane] path ...
      (alias: source)

Runs commands from one or more files given by path — and yes, path can be glob(7) patterns. 🌈

-F — if present, path gets expanded as a format.
-q — if given, no error is returned when path doesn't exist. No yelling, just vibes.
-n — the file is parsed but no commands are executed. Window shopping only.
-v — shows the parsed commands and line numbers, if possible.

`start-server` ⭐

start-server
      (alias: start)

Starts the tmux server — if it isn't already running — without creating any sessions. Just the server, standing there, ready.

Note that since by default the tmux server will exit with no sessions, this is only useful if a session is created in ~/.tmux.conf, if exit-empty is turned off, or if another command is run as part of the same command sequence.

For example:

$ tmux start \; show -g

`suspend-client` 😴

suspend-client [-t target-client] (alias: suspendc)

Suspend a client by sending SIGTSTP (tty stop). Like, it literally tells the client to take a lil nap, bestie. 💤

`switch-client` 🔁

switch-client [-ElnprZ] [-c target-client] [-O sort-order] [-t target-session] [-T key-table]

(alias: switchc)

Switch the current session for client target-client to target-session. But okay, plot twist: as a special case, -t may refer to a pane (a target that contains :, . or %), to change session, window and pane. In that case, -Z keeps the window zoomed if it was zoomed. If -l, -n or -p is used, the client is moved to the last, next or previous session respectively. -O may be used with -n and -p to specify the field to sort on: one of name, size, creation (time), or activity (time). -r toggles the client read-only and ignore-size flags (see the attach-session command).

If -E is used, the update-environment option will not be applied.

-T sets the client's key table; the next key will be looked up using key-table. After that key, the client is returned to its default key table (normally root). This may be used to configure multiple prefix keys, or to bind commands to sequences of keys. For example, to make typing abc run the list-keys command:

bind-key -Ttable2 c list-keys
bind-key -Ttable1 b switch-client -Ttable2
bind-key -Troot   a switch-client -Ttable1

WINDOWS AND PANES 🪟✨

Each window displayed by tmux may be split into one or more panes; each pane takes up a certain area of the display and is a separate terminal. A window may be split into panes using the split-window command. Windows may be split horizontally (with the -h flag) or vertically. Panes may be resized with the resize-pane command (bound to C-Up, C-Down C-Left and C-Right by default), the current pane may be changed with the select-pane command and the rotate-window and swap-pane commands may be used to swap panes without changing their position. Panes are numbered beginning from zero in the order they are created. Periodt. 💅

By default, a tmux pane permits direct access to the terminal contained in the pane. A pane may also be put into one of several modes:

Copy mode — which permits a section of a window or its history to be copied to a paste buffer for later insertion into another window. This mode is entered with the copy-mode command, bound to [ by default. Copied text can be pasted with the paste-buffer command, bound to ]. 📋
View mode — which is like copy mode but is entered when a command that produces output, such as list-keys, is executed from a key binding. 👀
Choose mode — which allows an item to be chosen from a list. This may be a client, a session or window or pane, or a buffer. This mode is entered with the choose-buffer, choose-client and choose-tree commands. 🎀

In copy mode an indicator is displayed in the top-right corner of the pane with the current position and the number of lines in the history. It's giving very "you are here" energy. 🌈

Commands are sent to copy mode using the -X flag to the send-keys command. When a key is pressed, copy mode automatically uses one of two key tables, depending on the mode-keys option: copy-mode for emacs, or copy-mode-vi for vi. Key tables may be viewed with the list-keys command. 🗝️

The following commands are supported in copy mode:

append-selection — Append the selection to the top paste buffer. Just stack it on top, bestie.
append-selection-and-cancel (vi: A) — Append the selection to the top paste buffer and exit copy mode. Bye! 👋
back-to-indentation (vi: ^) (emacs: M-m) — Move the cursor back to the indentation. 🧘
begin-selection (vi: Space) (emacs: C-Space) — Begin selection. ✨
bottom-line (vi: L) — Move to the bottom line. ⬇️
cancel (vi: q) (emacs: Escape) — Exit copy mode. 🚪
clear-selection (vi: Escape) (emacs: C-g) — Clear the current selection. 🧽
copy-end-of-line [-CP] [prefix] — Copy from the cursor position to the end of the line. prefix is used to name the new paste buffer. 📝
copy-end-of-line-and-cancel [-CP] [prefix] — Copy from the cursor position and exit copy mode. 🏃‍♀️
copy-pipe-end-of-line [-CP] [command] [prefix] — Copy from the cursor position to the end of the line and pipe the text to command. prefix is used to name the new paste buffer. 🚰
copy-pipe-end-of-line-and-cancel [-CP] [command] [prefix] — Same as copy-pipe-end-of-line but also exit copy mode. 🏁
copy-line [-CP] [prefix] — Copy the entire line. ➖
copy-line-and-cancel [-CP] [prefix] — Copy the entire line and exit copy mode. 🚪
copy-pipe-line [-CP] [command] [prefix] — Copy the entire line and pipe the text to command. prefix is used to name the new paste buffer. 🚰
copy-pipe-line-and-cancel [-CP] [command] [prefix] — Same as copy-pipe-line but also exit copy mode. 🏁
copy-pipe [-CP] [command] [prefix] — Copy the selection, clear it and pipe its text to command. prefix is used to name the new paste buffer. 🚰
copy-pipe-no-clear [-CP] [command] [prefix] — Same as copy-pipe but do not clear the selection. 🙅‍♀️
copy-pipe-and-cancel [-CP] [command] [prefix] — Same as copy-pipe but also exit copy mode. 🏁
copy-selection [-CP] [prefix] — Copies the current selection. 📋
copy-selection-no-clear [-CP] [prefix] — Same as copy-selection but do not clear the selection. 🙅‍♀️
copy-selection-and-cancel [-CP] [prefix] (vi: Enter) (emacs: M-w) — Copy the current selection and exit copy mode. 🏁
cursor-down (vi: j) (emacs: Down) — Move the cursor down. ⬇️
cursor-down-and-cancel — Same as cursor-down but also exit copy mode if reaching the bottom. 🏁
cursor-left (vi: h) (emacs: Left) — Move the cursor left. ⬅️
cursor-right (vi: l) (emacs: Right) — Move the cursor right. ➡️
cursor-up (vi: k) (emacs: Up) — Move the cursor up. ⬆️
cursor-centre-vertical (emacs: C-l) — Moves the cursor to the vertical centre of the pane. 🎯
cursor-centre-horizontal (emacs: M-l) — Moves the cursor to the horizontal centre of the pane. 🎯
end-of-line (vi: $) (emacs: C-e) — Move the cursor to the end of the line. 🔚
goto-line line (vi: :) (emacs: g) — Move the cursor to a specific line. 🧭
halfpage-down (vi: C-d) (emacs: M-Down) — Scroll down by half a page. 📜
halfpage-down-and-cancel — Same as halfpage-down but also exit copy mode if reaching the bottom. 🏁
halfpage-up (vi: C-u) (emacs: M-Up) — Scroll up by half a page. 📜
history-bottom (vi: G) (emacs: M->) — Scroll to the bottom of the history. ⏬
history-top (vi: g) (emacs: M-<) — Scroll to the top of the history. ⏫
jump-again (vi: ;) (emacs: ;) — Repeat the last jump. 🔁
jump-backward to (vi: F) (emacs: F) — Jump backwards to the specified text. ⬅️
jump-forward to (vi: f) (emacs: f) — Jump forward to the specified text. ➡️
jump-reverse (vi: ,) (emacs: ,) — Repeat the last jump in the reverse direction (forward becomes backward and backward becomes forward). 🔄
jump-to-backward to (vi: T) — Jump backwards, but one character less, placing the cursor on the character after the target. 🎯
jump-to-forward to (vi: t) — Jump forward, but one character less, placing the cursor on the character before the target. 🎯
jump-to-mark (vi: M-x) (emacs: M-x) — Jump to the last mark. 📍
line-numbers-on — Show line numbers in copy mode. 🔢
line-numbers-off — Hide line numbers in copy mode. 🙈
line-numbers-toggle (emacs: L) — Toggle line numbers in copy mode. 🔢
middle-line (vi: M) (emacs: M-r) — Move to the middle line. 🎯
next-matching-bracket (vi: %) (emacs: M-C-f) — Move to the next matching bracket. 🧩
next-paragraph (vi: }) (emacs: M-}) — Move to the next paragraph. 📄
next-prompt [-o] — Move to the next prompt. ➡️
next-word (vi: w) — Move to the next word. 📖
next-word-end (vi: e) (emacs: M-f) — Move to the end of the next word. 📖
next-space (vi: W) — Same as next-word but treat all non-whitespace characters as part of a word. 🧵
next-space-end (vi: E) — Same as next-word-end but treat all non-whitespace characters as part of a word. 🧵
other-end (vi: o) — Switch at which end of the selection the cursor sits. 🔄
page-down (vi: C-f) (emacs: PageDown) — Scroll down by one page. 📜
page-down-and-cancel — Same as page-down but also exit copy mode if reaching the bottom. 🏁
page-up (vi: C-b) (emacs: PageUp) — Scroll up by one page. 📜
pipe [command] — Pipe the selected text to command and clear the selection. 🚰
pipe-no-clear [command] — Same as pipe but do not clear the selection. 🙅‍♀️
pipe-and-cancel [command] [prefix] — Same as pipe but also exit copy mode. 🏁
previous-matching-bracket (emacs: M-C-b) — Move to the previous matching bracket. 🧩
previous-paragraph (vi: {) (emacs: M-{) — Move to the previous paragraph. 📄
previous-prompt [-o] — Move to the previous prompt. ⬅️
previous-word (vi: b) (emacs: M-b) — Move to the previous word. 📖
previous-space (vi: B) — Same as previous-word but treat all non-whitespace characters as part of a word. 🧵
rectangle-on — Turn on rectangle selection mode. 🔲
rectangle-off — Turn off rectangle selection mode. 🔳
rectangle-toggle (vi: v) (emacs: R) — Toggle rectangle selection mode. 🔲
recentre-top-bottom (emacs : C-l) — Cycles the current line between centre, top, and bottom. 🔄
refresh-on — Turn on automatic refresh of the content from the pane, so that new output appears while in copy mode. Automatic refresh is off by default; it will scroll only while the cursor is at the bottom and is paused while a selection is in progress. 🔄
refresh-off — Turn off automatic refresh of the content from the pane. ⏸️
refresh-now (vi: r) (emacs: r) — Refresh the content from the pane once. 🔄
refresh-toggle — Toggle automatic refresh of the content from the pane. 🔄
scroll-bottom — Scroll up until the current line is at the bottom while keeping the cursor on that line. ⬇️
scroll-down (vi: C-e) (emacs: C-Down) — scroll down, bestie. When mode-keys is vi, the cursor stays fixed relative to the text. 💫
scroll-down-and-cancel — literally scroll-down but it also dips out of copy mode if the cursor hits the bottom.
scroll-exit-on — turn ON the "exit copy mode when you scroll to the end of the buffer" behaviour — unless a selection is present, bc we're not gonna yeet your selection, no ma'am.
scroll-exit-off — turn that same exit-when-you-reach-the-end thing OFF. 🙈
scroll-exit-toggle — toggle it, iconically.
scroll-middle (vi: z) — scroll so the current line becomes the middle one, while keeping the cursor planted right there on that line. main character centering. 👑
scroll-to-mouse — scrolls the pane in copy-mode when it's bound to a mouse drag event. -e makes copy mode bail out when you're at the bottom.
scroll-top — scroll down until the current line sits at the top, cursor still chillin' on it.
scroll-up (vi: C-y) (emacs: C-Up) — scroll up. If mode-keys is vi, the cursor is fixed relative to the text.
search-again (vi: n) (emacs: n) — run the last search again, fr fr.
search-backward text (vi: ?) — search backwards for the text you specified.
search-backward-incremental text (emacs: C-r) — search backwards incrementally for the specified text. This one is expected to be used with the -i flag to the command-prompt command. 🧚
search-backward-text text — search backwards for the specified plain text.
search-forward text (vi: /) — search forward for the specified text.
search-forward-incremental text (emacs: C-s) — search forward incrementally for the specified text. Again: expected to be used with the -i flag to the command-prompt command.
search-forward-text text — search forward for the specified plain text.
search-reverse (vi: N) (emacs: N) — repeat the last search but backwards-ways: forward becomes backward and backward becomes forward. 🔄
select-line (vi: V) — select the current line.
select-word — select the current word.
selection-mode [char | word | line] — change the selection mode.
set-mark (vi: X) (emacs: X) — mark the current line.
start-of-line (vi: 0) (emacs: C-a) — move the cursor to the start of the line.
stop-selection — stop selecting, but without clearing the current selection you already have. 😌
toggle-position (vi: P) (emacs: P) — toggle whether the position indicator in the top right is visible.
top-line (vi: H) (emacs: M-R) — move to the top line.

Okay so the search commands come in several varieties, and this is important, so lock in: ‘search-forward’ and ‘search-backward’ search for a regular expression. The ‘-text’ variants search for a plain text string instead of a regular expression. The ‘-incremental’ ones do an incremental search and expect to be used with the -i flag to the command-prompt command. ‘search-again’ repeats the last search, and ‘search-reverse’ does the same thing but flips the direction (forward becomes backward and backward becomes forward). 💅

The default incremental search key bindings, ‘C-r’ and ‘C-s’, are designed to emulate emacs(1). When you first press them they let you type in a new search term; if you press them with an empty search term they repeat the previously used search term. chef's kiss emulation. 😭

The ‘next-prompt’ and ‘previous-prompt’ move between shell prompts, but — plot twist — they require the shell to emit an escape sequence (\033]133;A\033\\) to tell tmux where the prompts are located. If the shell doesn't do that, these commands will do nothing. The -o flag jumps to the beginning of the command output instead of the shell prompt. Finding the beginning of command output requires the shell to emit an escape sequence (\033]133;C\033\\) to tell tmux where the output begins. If the shell doesn't send these escape sequences, these commands do nothing. periodt. 💀

Copy commands may take an optional buffer prefix argument, and that's what's used to generate the buffer name — the default is ‘buffer’, so buffers end up named ‘buffer0’, ‘buffer1’ and so on. Pipe commands take a command argument, which is the command that the selected text gets piped into. ‘copy-pipe’ variants also copy the selection. The ‘-and-cancel’ variants of some commands exit copy mode after they've completed (for copy commands) or when the cursor reaches the bottom (for scrolling commands). ‘-no-clear’ variants do not clear the selection. And all the copy commands can take the -C and -P flags — -C suppresses setting the terminal clipboard when copying, while -P suppresses adding a paste buffer with the text. 🎀

The next and previous word keys skip over whitespace and treat consecutive runs of either word separators or other letters as words. Word separators can be customized with the word-separators session option. Next word moves to the start of the next word, next word end to the end of the next word, and previous word to the start of the previous word. The three next and previous space keys work similarly but treat all non-whitespace characters as part of a word. Setting word-separators to the empty string makes next/previous word equivalent to next/previous space. lowkey elegant. ✨

The jump commands enable quick movement within a line. For instance, typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character on the current line. A ‘;’ will then jump to the next occurrence. obsessed. 🔥

Commands in copy mode may be prefaced by an optional repeat count. With vi key bindings, a prefix is entered using the number keys; with emacs, the Alt (meta) key and a number begins prefix entry.

The synopsis for the copy-mode command is:

copy-mode [-dekHMqSu] [-s src-pane] [-t target-pane]

Enter copy mode. 🦋
-u enters copy mode and scrolls one page up, and -d one page down.
-H hides the position indicator in the top right.
-q cancels copy mode and any other modes.
-M begins a mouse drag (only valid if bound to a mouse key binding, see “MOUSE SUPPORT”).
-S enters copy-mode and scrolls when bound to a mouse drag event; see scroll-to-mouse.
-s copies from src-pane instead of target-pane.
-e specifies that scrolling to the bottom of the history (to the visible screen) should exit copy mode. This will not happen if a selection is present. And while in copy mode, pressing a key other than those used for scrolling will disable this behaviour. It's intended to allow fast scrolling through a pane's history, like this:

bind PageUp copy-mode -eu
bind PageDown copy-mode -ed

-k kills the pane when the mode is exited.

A number of preset arrangements of panes are available — these are called layouts, and they're basically the outfit changes of the tmux world. 👗 These may be selected with the select-layout command or cycled with next-layout (bound to ‘Space’ by default); once a layout is chosen, panes within it may be moved and resized as normal.

The following layouts are supported:

even-horizontal — panes are spread out evenly from left to right across the window.
even-vertical — panes are spread evenly from top to bottom.
main-horizontal — a large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom. Use the main-pane-height window option to specify the height of the top pane.
main-horizontal-mirrored — the same as main-horizontal but mirrored, so the main pane is at the bottom of the window.
main-vertical — a large (main) pane is shown on the left of the window and the remaining panes are spread from top to bottom in the leftover space on the right. Use the main-pane-width window option to specify the width of the left pane.
main-vertical-mirrored — the same as main-vertical but mirrored, so the main pane is on the right of the window.
tiled — panes are spread out as evenly as possible over the window in both rows and columns. geometric slay. 🧊

In addition, select-layout may be used to apply a previously used layout — the list-windows command displays the layout of each window in a form suitable for use with select-layout. For example:

$ tmux list-windows
0: ksh [159x48]
    layout: {"V":2,"L":{"t":"h","w":159,"h":48,"x":0,"y":0,"c":[{"t":"p","w":79,"h":48,"x":0,"y":0,"l":0,"i":0,"I":"%0"},{"t":"p","w":79,"h":48,"x":80,"y":0,"a":true,"i":1,"I":"%2"}]}}
$ tmux select-layout '{"V":2,"L":{"t":"h","w":159,"h":48,"x":0,"y":0,"c":[{"t":"p","w":79,"h":48,"x":0,"y":0,"l":0,"i":0,"I":"%0"},{"t":"p","w":79,"h":48,"x":80,"y":0,"a":true,"i":1,"I":"%2"}]}}'

tmux automatically adjusts the size of the layout for the current window size. Note that a layout cannot be applied to a window with more panes than that from which the layout was originally defined. 🚫

Commands related to windows and panes are as follows:

break-pane [-abdPW] [-F format] [-n window-name] [-s src-pane] [-t dst-window] [-x width] [-y height] [-X x-position] [-Y y-position] (alias: breakp) — break src-pane off from its containing window to make it the only pane in dst-window.

break-pane [-abdPW] [-F format] [-n window-name] [-s src-pane] [-t dst-window] [-x width] [-y height] [-X x-position] [-Y y-position]
      (alias: breakp)

With -a or -b, the window is moved to the next index after or before (existing windows are moved if necessary). If -d is given, the new window does not become the current window. The -P option prints information about the new window after it has been created — by default it uses the format ‘#{session_name}:#{window_index}.#{pane_index}’ but a different format may be specified with -F. 📋

If the -W option is given, src-pane is lifted out of the tiled layout and made floating. The -x and -y options set the width and height of the floating pane in columns and lines respectively — the default is half the window width and a quarter the window height. The -X and -Y options set the position of the upper-left corner of the pane; if omitted, new floating panes are cascaded from the top-left of the window. The -x, -y, -X, and -Y options may be followed by ‘%’ to specify a percentage of the window size. 📐

If the pane had previously been floating, the position and sizes are restored from the saved values not specified by the -x, -y, -X, and -Y options.

If -d is given, the active pane is not changed — it just stays right where it is. The pane must not already be floating or hidden, and the window must not be zoomed.

🫧 COMMANDS (still going, bestie, we're so back) 🫧

capture-pane

capture-pane [-aeFHILpPRqCJMN] [-b buffer-name] [-E end-line] [-S
        start-line] [-t target-pane]

alias: capturep

Okay so this one grabs everything that's currently sitting inside a pane. If you pass -p, the output comes straight to stdout, and if you don't, it goes into the buffer you named with -b — or into a brand new buffer if you didn't name one. 💾

-a — use the alternate screen, and heads up, the history is not accessible when you do. If there's no alternate screen at all, you get an error back, unless you also passed -q.
-M — same energy as -a but for modes: if the pane is in a mode, this uses the screen for that mode.
-e — include escape sequences for text and background attributes in the output.
-C — also escapes non-printable characters as octal \xxx.
-T — ignore trailing positions that don't contain a character.
-N — preserve trailing spaces at the end of each line.
-J — preserve trailing spaces and join any wrapped lines. Also, -J implies -T, no cap.
-P — capture only output the pane has received that is the beginning of an as-yet incomplete escape sequence.
-L — stick the line number at the start of each line.
-I — include the time each line entered the history, or zero if that's not available.
-F — include the flags, where:
- - means no flags
- D means an unused line
- O means a line marked as output
- P means a line marked as a prompt
- X means a line containing extended cells
- H means a line with hyperlinks
-H — only hyperlinks in the specified lines get captured. If a line has multiple hyperlinks, they're separated by spaces.
-R — dumps the internal grid data, for diagnostics. (nerd mode activated 🔬)

And now the line range stuff, because this is where it gets spicy:

-S and -E set the starting and ending line numbers. Zero is the first line of the visible pane, and negative numbers are lines in the history. Give - to -S and that's the start of the history; give - to -E and that's the end of the visible pane. By default? You only capture the visible contents of the pane, bestie. Nothing more.

choose-client

choose-client [-hkNryZ] [-F format] [-f filter] [-K key-format] [-O
        sort-order] [-t target-pane] [template]

This throws a pane into client mode, where you can pick a client interactively off a list. Each client gets one line. A shortcut key shows up on the left in brackets so you can just grab one instantly, or you can navigate the list and choose / mess with an item using the keys below. 👑

-Z — zooms the pane.
-y — disables any confirmation prompts.

The keys you can use in client mode:

Enter — choose the selected client
Up — select the previous client
Down — select the next client
C-s — search by name
n — repeat last search forwards
N — repeat last search backwards
t — toggle whether the client is tagged
T — tag no clients
C-t — tag all clients
d — detach the selected client
D — detach the tagged clients
x — detach and HUP the selected client
X — detach and HUP the tagged clients
z — suspend the selected client
Z — suspend the tagged clients
f — enter a format to filter items
c — clear the current filter
O — change sort order
r — reverse sort order
v — toggle preview
i — change view (preview and client information)
F1 or C-h — display help
q — exit mode

Once a client is chosen, %% gets swapped out for the client name inside template, and the whole thing runs as a command. If you didn't give a template, then "detach-client -t '%%'" is what gets used. 🫶

-O — sets the initial sort order, one of name, size, creation (time), or activity (time).
-r — reverses the sort order.
-f — sets an initial filter. The filter is a format: if it evaluates to zero, that item in the list is not shown; otherwise it is shown. And if a filter would lead to an empty list, it's just ignored.
-F — the format for each item in the list.
-K — a format for each shortcut key. Both -F and -K are evaluated once for each line.

More flags:

-N — starts without the preview, or if you give it twice, starts with the larger preview.
-h — hides the pane containing the mode.
-k — kills the pane when the mode is exited.

Heads up: the choose-client command works only if at least one client is attached. No clients, no mode. 💀

choose-tree

choose-tree [-GhikNrswyZ] [-F format] [-f filter] [-K key-format] [-O
        sort-order] [-t target-pane] [template]

This one drops a pane into tree mode, where you can pick a session, window or pane out of a tree, interactively. Each session, window or pane is one line. Shortcut key shows up on the left in brackets for instant grabbing, or navigate the tree and choose / manipulate an item with the keys below. 🌳✨

-s — starts with sessions collapsed.
-w — starts with windows collapsed.
-Z — zooms the pane.
-y — disables any confirmation prompts.

The keys for tree mode:

Enter — choose the selected item
Up — select the previous item
Down — select the next item
S-Up — swap the current window with the previous one
S-Down — swap the current window with the next one
+ — expand the selected item
- — collapse the selected item
M-+ — expand all items
M-- — collapse all items
x — kill the selected item
X — kill the tagged items
< — scroll the list of previews left
> — scroll the list of previews right
C-s — search by name
m — set the marked pane
M — clear the marked pane
n — repeat last search forwards
N — repeat last search backwards
t — toggle whether the item is tagged
T — tag no items
C-t — tag all items
: — run a command for each tagged item
f — enter a format to filter items
c — clear the current filter
H — jump to the starting pane
O — change sort order
r — reverse sort order
v — toggle preview
i — change view (preview and session, window and pane information)
F1 or C-h — display help
q — exit mode

After a session, window or pane is chosen: the first instance of %% and all instances of %1 get replaced by the target inside template, and the result runs as a command. If you didn't give a template, "switch-client -t '%%'" is what's used. 💖

-O — sets the initial sort order, one of index, name, activity (time), or z.
-r — reverses the sort order.
-f — sets an initial filter. The filter is a format: evaluates to zero → item not shown; otherwise → shown. If a filter would make an empty list, it's ignored.
-F — the format for each item in the tree.
-K — a format for each shortcut key. Again, both are evaluated once for each line.
-G — include all sessions in any session groups in the tree, instead of only the first one.

And the rest:

-N — starts without the preview, or if given twice, with the larger preview.
-i — starts showing client information instead of the preview.
-h — hides the pane containing the mode.
-k — kills the pane when the mode is exited.

-h and -k are literally made to make using this mode inside a floating pane easier. Like, for example:

bind s 'new-pane -x50% -y50% -E; choose-tree -hks'

And the same rule as before: choose-tree works only if at least one client is attached. 🫠

customize-mode

customize-mode [-kNZ] [-F format] [-f filter] [-t target-pane]
        [template]

Puts a pane into customize mode, where you can browse and modify options and key bindings from a list. The option values shown in the list are for the active pane in the current window. 🎀

-Z — zooms the pane.

The keys you can use in customize mode are:

okay bestie, we're still in customize-mode and the keybindings are absolutely giving main character energy ✨💅. here's every single one, no cap:

Enter — Set pane, window, session or global option value
Up — Select previous item
Down — Select next item
+ — Expand selected item
- — Collapse selected item
M-+ — Expand all items
M-- — Collapse all items
s — Set option value or key attribute
S — Set global option value
w — Set window option value, if option is for pane and window
d — Set an option or key to the default
D — Set tagged options and tagged keys to the default
e — Open the value in an editor
u — Unset an option (set to default value if global) or unbind a key
U — Unset tagged options and unbind tagged keys
C-s — Search by name
n — Repeat last search forwards
N — Repeat last search backwards
t — Toggle if item is tagged
T — Tag no items
C-t — Tag all items
f — Enter a format to filter items
c — Clear the current filter
v — Toggle option information
F1 or C-h — Display help
q — Exit mode

-f specifies an initial filter: the filter is a format — if it evaluates to zero, the item in the list is not shown, otherwise it is shown. If a filter would lead to an empty list, it is ignored. -F specifies the format for each item in the tree.

-N starts without the option information. -k kills the pane when the mode is exited.

The customize-mode command works only if at least one client is attached. 💖

`switch-mode`

switch-mode [-kswZ] [-F format] [-t target-pane] [command]

Put a pane into switch mode, where a session or window may be chosen interactively from a list. Each session or window is shown on one line and the list is narrowed by typing: the typed text is matched against each item with fuzzy matching and only matching items are shown, sorted by how well they match. -s lists sessions (the default) and -w lists windows. -Z zooms the pane. The following keys may be used in switch mode:

Enter — Choose the selected item
Up — Select the previous item
Down — Select the next item
Escape — Exit mode

After a session or window is chosen, the first instance of %% and all instances of %1 are replaced by the target in command and the result executed as a command. If command is not given, switch-client -Zt '%%' is used. -F specifies the format for each item in the list. -k kills the pane when the mode is exited.

The appearance of matched characters is controlled by the switch-mode-match-style option. 👑

`display-panes`

display-panes [-kNZ] [-d duration] [-s source-window] [-t target-pane] [template]

(alias: displayp)

Put target-pane into panes mode, which displays a preview of the window and a visible indicator of each pane. If -s is given, the panes in source-window are displayed instead of those in the window containing target-pane. See the display-panes-colour, display-panes-active-colour, display-panes-border-style, display-panes-format and display-panes-time window options. The indicator is closed when a key is pressed (unless -N is given) or duration milliseconds have passed. If -d is not given, display-panes-time is used. A duration of zero means the indicator stays until a key is pressed. The mode is zoomed by default; -Z starts it unzoomed. -k kills the pane when the mode is exited. While the indicator is on screen, a pane may be chosen with the 0 to 9 keys or by clicking it with the mouse, which will cause template to be executed as a command with %% substituted by the pane ID. The default template is select-pane -t '%%'. 🦋

`find-window`

find-window [-iCNrTZ] [-t target-pane] match-string

(alias: findw)

Search for a glob(7) pattern or, with -r, regular expression match-string in window names, titles, and visible content (but not history). The flags control matching behavior: -C matches only visible window contents, -N matches only the window name and -T matches only the window title. -i makes the search ignore case. The default is -CNT. -Z zooms the pane.

The find-window command works only if at least one client is attached. ✨

`join-pane`

join-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]

(alias: joinp)

Like split-window, but instead of splitting dst-pane and creating a new pane, split it and move src-pane into the space. This can be used to reverse break-pane. The -b option causes src-pane to be joined to left of or above dst-pane.

If -s is omitted and a marked pane is present (see select-pane -m), the marked pane is used rather than the current pane.

If src-pane is floating and dst-pane is either unspecified or equal to src-pane, src-pane is returned to its previous position in the layout. 💜

`kill-pane`

kill-pane [-a] [-f filter] [-t target-pane]

(alias: killp)

Destroy the given pane. If no panes remain in the containing window, it is also destroyed. The -a option kills all panes in the window except the pane given with -t. When -a is given, -f specifies a filter. Only panes for which the filter is true are killed. 💀

`kill-window`

kill-window [-a] [-f filter] [-t target-window]

(alias: killw)

Kill the current window or the window at target-window, removing it from any sessions to which it is linked. The -a option kills all windows in the session except the window given with -t. When -a is given, -f specifies a filter. Only windows for which the filter is true are killed. 💅

`last-pane`

last-pane [-deZ] [-t target-window]

(alias: lastp)

Select the last (previously selected) pane. -Z keeps the window zoomed if it was zoomed. -e enables or -d disables input to the pane. 🌈

`last-window`

last-window [-t target-session]

(alias: last)

Select the last (previously selected) window. If no target-session is specified, select the last window of the current session. 🎀

`link-window`

link-window [-abdk] [-s src-window] [-t dst-window]

(alias: linkw)

Link the window at src-window to the specified dst-window. If dst-window is specified and no such window exists, the src-window is linked there. With -a or -b the window is moved to the next index after or before dst-window (existing windows are moved if necessary). If -k is given and dst-window exists, it is killed, otherwise an error is generated. If -d is given, the newly linked window is not selected. 🔗

`list-panes`

list-panes [-ars] [-F format] [-f filter] [-O sort-order] [-t target]

(alias: lsp)

If -a is given, target is ignored and all panes on the server are listed. If -s is given, target is a session (or the current session). If neither is given, target is a window (or the current window). -F specifies the format of each line and -f a filter. Only panes for which the filter is true are shown. See the “FORMATS” section. -O specifies the sort order: one of name (title), index, size (area), creation (time), or activity (time). -r reverses the sort order. 🫶

`list-windows`

list-windows [-ar] [-F format] [-f filter] [-O sort-order] [-t target-session]

(alias: lsw)

If -a is given, list all windows on the server. Otherwise, list windows in the current session or in target-session. -F specifies the format of each line and -f a filter. Only windows for which the filter is true are shown. See the “FORMATS” section. -O specifies the sort order: one of index, name, size (area), creation (time), or activity (time). -r reverses the sort order. 👑

`move-pane`

move-pane [-bdfhMv] [-D [lines]] [-l size] [-L [columns]] [-P position] [-R [columns]] [-s src-pane] [-t dst-pane] [-U [lines]] [-X x-position] [-Y y-position] [-z z-index]

(alias: movep)

Does the same as join-pane, except if given -D, -L, -P, -R, -U, -X, -Y or -z in which case move the target floating pane. -D, -L, -R and -U move it down, left, right or up by lines or columns (one if omitted). -P moves it to position, which may be one of:

top-left — Top left
top-centre — Top and horizontal centre
top-right — Top right
centre-left — Vertical centre and left
centre — Centre
centre-right — Vertical centre and right
bottom-left — Bottom left
bottom-centre — Bottom and horizontal centre
bottom-right — Bottom right
top-left-centre — Centre of top-left quadrant
top-right-centre — Centre of top-right quadrant
bottom-left-centre — Centre of bottom-left quadrant
bottom-right-centre — Centre of bottom-right quadrant
front — Front of floating panes
back — Back of floating panes
forward — Forward one floating pane
backward — Backward one floating pane
forward-loop — Forward but back if already at front
backward-loop — Backward but front if already at back

-X and -Y move it to an absolute position. -z moves the pane to the given z-index, where zero is the front.

-M begins a mouse drag (only valid if bound to a mouse key binding, see “MOUSE SUPPORT”). 🖱️

move-window [-abrdk] [-s src-window] [-t dst-window] (alias: movew) — okay so this is basically link-window's sibling but with ✨commitment✨: the window at src-window gets moved to dst-window instead of being duplicated. With -r, every window in the session gets renumbered in sequential order, respecting the base-index option. slay.
new-window [-abdEkPS] [-c start-directory] [-e environment] [-F format] [-n window-name] [-t target-window] [shell-command [argument ...]] (alias: neww) — bestie, make a new window 💖 With -a or -b, the new window gets inserted at the next index after or before the specified target-window, pushing windows up if necessary; otherwise target-window is literally just where the new window lands.

If -d is given, the session does not make the new window the current window (so it chills in the background, no cap). If -E is given, the initial pane is created without a running command. target-window represents the window to be created; if the target already exists you get an error, unless the -k flag is used, in which case it is destroyed 💀. window-name is the name given to the new window, if any.

If -S is given, an existing window is selected instead of creating a new one (unless -d is also given, in which case the command does nothing at all — it's giving ghost). target-window is preferred if it already identifies an existing window; otherwise a window named window-name is selected if one exists.

shell-command is the command to execute. If shell-command is not specified, the value of the default-command option is used. -c specifies the working directory in which the new window is created.

When the shell command completes, the window closes. See the remain-on-exit option to change this behaviour.

-e takes the form ‘VARIABLE=value’ and sets an environment variable for the newly created window; it may be specified multiple times.

The TERM environment variable must be set to ‘screen’ or ‘tmux’ for all programs running inside tmux. New windows will automatically have ‘TERM=screen’ added to their environment, but care must be taken not to reset this in shell startup files or by the -e option. ⚠️ don't sabotage yourself.

The -P option prints information about the new window after it has been created. By default, it uses the format ‘#{session_name}:#{window_index}’ but a different format may be specified with -F.

new-pane [-AbCDefhIkKLMOPvWZ] [-B border-lines] [-c start-directory] [-e environment] [-F format] [-l size] [-m message] [-p percentage] [-R inactive-border-style] [-s style] [-S active-border-style] [-t target-pane] [-T title] [-x width] [-y height] [-X x-position] [-Y y-position] [shell-command [argument ...]] (alias: newp) — creates a new floating pane 🦋 the iconique floaty ones. The -x and -y options set the width and height of the floating pane in columns and lines respectively. The default is half the window width and a quarter the window height. The -X and -Y options set the position of the upper-left corner of the pane. If omitted, new floating panes are cascaded from the top-left of the window. The -x, -y, -X, and -Y options may be followed by ‘%’ to specify a percentage of the window size. -B sets the pane border lines for floating panes; see pane-border-lines. -M may be used when bound to a mouse drag key; the new floating pane is resized to follow the mouse drag. -A creates a floating pane which remains visible above a zoomed pane. -O creates a modal pane. A modal pane is always the active pane and prevents interaction with any other panes while it is active — main character energy, fr fr 👑. A window can only have one modal pane and it must be a floating pane. With -K, all keys, including the prefix key, are passed directly to the modal pane. With -C, the modal pane is closed when the mouse is clicked outside it. With -D, the modal pane is closed when ‘Escape’ or ‘C-c’ is pressed.

The -L option makes new-pane behave like split-window.

All other options have the same meaning as for the split-window command.

next-layout [-t target-window] (alias: nextl) — move a window to the next layout and rearrange the panes to fit. glow up era ✨
next-window [-a] [-t target-session] (alias: next) — move to the next window in the session. If -a is used, move to the next window with an alert 🔔.
pipe-pane [-IOo] [-t target-pane] [shell-command] (alias: pipep) — pipe output sent by the program in target-pane to a shell command or vice versa. A pane may only be connected to one command at a time, so any existing pipe is closed before shell-command is executed. The shell-command string may contain the special character sequences supported by the status-left option. If no shell-command is given, the current pipe (if any) is closed.

-I and -O specify which of the shell-command output streams are connected to the pane: with -I stdout is connected (so anything shell-command prints is written to the pane as if it were typed); with -O stdin is connected (so any output in the pane is piped to shell-command). Both may be used together and if neither are specified, -O is used.

The -o option only opens a new pipe if no previous pipe exists, allowing a pipe to be toggled with a single key, for example:

bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'

so handy bestie, iykyk 💅

previous-layout [-t target-window] (alias: prevl) — move to the previous layout in the session.
previous-window [-a] [-t target-session] (alias: prev) — move to the previous window in the session. With -a, move to the previous window with an alert.
rename-window [-t target-window] new-name (alias: renamew) — rename the current window, or the window at target-window if specified, to new-name. name it something cute 🎀.
resize-pane [-MTZ] [-D lines] [-L columns] [-R columns] [-U lines] [-x width] [-y height] [-t target-pane] (alias: resizep) — resize a pane, up, down, left or right by a specified adjustment with -U, -D, -L or -R; or to an absolute size with -x or -y. The adjustment is given in lines or columns (the default is 1); -x and -y may be a given as a number of lines or columns or followed by ‘%’ for a percentage of the window size (for example ‘-x 10%’). If target-pane is floating, -U, -D, -L, and -R target their respective borders, and negative values may be given. With -Z, the active pane is toggled between zoomed (occupying the whole of the window) and unzoomed (its normal position in the layout).

-M begins mouse resizing (only valid if bound to a mouse key binding, see “MOUSE SUPPORT”).

-T trims all lines below the current cursor position and moves lines out of the history to replace them.

resize-window [-aADLRU] [-t target-window] [-x width] [-y height] [adjustment] (alias: resizew) — resize a window, up, down, left or right by adjustment with -U, -D, -L or -R, or to an absolute size with -x or -y. The adjustment is given in lines or cells (the default is 1). -A sets the size of the largest session containing the window; -a the size of the smallest. This command will automatically set window-size to manual in the window options.
respawn-pane [-Ek] [-c start-directory] [-e environment] [-t target-pane] [shell-command [argument ...]] (alias: respawnp) — reactivate a pane in which the command has exited (see the remain-on-exit window option). If shell-command is not given, the command used when the pane was created or last respawned is executed. The pane must be already inactive, unless -k is given, in which case any existing command is killed 💀. If -E is given, the pane is left without a running command. -c specifies a new working directory for the pane. The -e option has the same meaning as for the new-window command.
respawn-window [-Ek] [-c start-directory] [-e environment] [-t target-window] [shell-command [argument ...]] (alias: respawnw) — reactivate a window in which the command has exited (see the remain-on-exit window option). If shell-command is not given, the command used when the window was created or last respawned is executed. The window must be already inactive, unless -k is given, in which case any existing command is killed. If -E is given, the window is left with one pane and without a running command. -c specifies a new working directory for the window. The -e option has the same meaning as for the new-window command.
rotate-window [-DUZ] [-t target-window] (alias: rotatew) — rotate the positions of the panes within a window, either upward (numerically lower) with -U or downward (numerically higher). -Z keeps the window zoomed if it was zoomed. spin spin spin 🌀
select-layout [-Enop] [-t target-pane] [layout-name] (alias: selectl) — choose a specific layout for a window. If layout-name is not given, the last preset layout used (if any) is reapplied. -n and -p are equivalent to the next-layout and previous-layout commands. -o applies the last set layout if possible (undoes the most recent layout change). -E spreads the current pane and any panes next to it out evenly.
select-pane [-DdeLlMmRUZ] [-T title] [-t target-pane] (alias: selectp) — make pane target-pane the active pane in its window. If one of -D, -L, -R, or -U is used, respectively the pane below, to the left, to the right, or above the target pane is used. -Z keeps the window zoomed if it was zoomed. -l is the same as using the last-pane command. -e enables or -d disables input to the pane. -T sets the pane title.

-m and -M are the marked pane girlies ✨ — one sets it, one clears it. There's only one marked pane at a time bestie, so the second you mark a new one the old one gets 💀 cleared, no exceptions. And why do we care? Because the marked pane is the default target for -s on join-pane, move-pane, swap-pane and swap-window. Main character pane behaviour, honestly 👑.

🪟 `select-window`

select-window [-lnpT] [-t target-window]
              (alias: selectw)

Picks the window at target-window 💖. And listen — -l, -n and -p are literally just the last-window, next-window and previous-window commands wearing a disguise 🎭. Then there's -T: if you pass it and the selected window is already the current window, it behaves like last-window instead. Sneaky little toggle, we love her 🌸.

✂️ `split-window`

split-window [-bdefhIkPvZ] [-B border-lines] [-c start-directory] [-e
        environment] [-F format] [-l size] [-m message] [-p percentage]
        [-R inactive-border-style] [-s style] [-S active-border-style]
        [-t target-pane] [-T title] [shell-command [argument ...]]
              (alias: splitw)

Okay so this is the icon herself: creates a brand new pane by splitting target-pane 🎀.

-d — the session does not make the new pane the current pane. It gets born but stays in the background, humble queen 🙈.
-Z — zooms if the window isn't zoomed, or keeps it zoomed if it already is.
-s — sets the style for the pane content.
-S — sets the border style when the pane is active.
-R — sets the border style when the pane is inactive. (Both of these are the "see STYLES" girlies 💅.)
-T — sets the pane title.

Then the geometry section, and it matters, so pay attention bestie:

-h does a horizontal split and -v does a vertical split. If you specify neither? -v is assumed. The default is right there, no cap 🌈.
-l specifies the size of the new pane — in lines for a vertical split, or in columns for a horizontal split. And the size can be followed by ‘%’ to mean a percentage of the available space 🌸.
-p is just shorthand for that percentage thing. Same energy, fewer keystrokes ✨.
-B sets the pane border lines for floating panes — go read pane-border-lines for the deets 🦋.
-b — the new pane gets created to the left of or above target-pane. Baby goes first 🥺.
-f — makes a new pane spanning the full window height (with -h) or the full window width (with -v), instead of just splitting the active pane. Full send 💀.

Now, floating panes get their own lil rules. If target-pane is floating, a new floating pane is created adjacent to it with equal sizes 👯. The position is decided by the -h, -v, and -b flags. And if any part of the new pane wouldn't be visible on screen, target-pane and the new pane both get resized to fit. Teamwork, fr fr 🫶.

-k keeps the pane open after the optional shell-command exits, and waits for a key press before closing it. The message shown is controlled by the remain-on-exit-format option. And -m message is the same as -k but also sets the remain-on-exit-format option for this pane to message. Two-for-one, iconic 🎀.

-W waits until shell-command exits, then returns its exit status. Like so:

$ tmux new-pane -W 'vi afile'
$ echo $?
0

-E — or just an empty shell-command, ('') — creates an empty pane with no command running in it. display-message -I can write to an empty pane, iykyk 👀.

-I creates an empty pane and forwards any output from stdin to it. Example time:

$ make 2>&1|tmux new-pane -dI &

🔄 `swap-pane`

swap-pane [-dDUZ] [-s src-pane] [-t dst-pane]
              (alias: swapp)

Swaps two panes, periodt 🔁.

-U — if you use it and don't give a source pane with -s, then dst-pane gets swapped with the previous pane (the one before it numerically).
-D — swaps with the next pane (the one after it numerically).
-d — tells tmux not to change the active pane, stay put bestie 🙅.
-Z — keeps the window zoomed if it was zoomed.

And the plot twist 👑: if -s is omitted and there's a marked pane hanging around (see select-pane -m), the marked pane is used instead of the current pane. Marked girlies stay winning.

🔁 `swap-window`

swap-window [-d] [-s src-window] [-t dst-window]
              (alias: swapw)

Basically link-window's cousin, except the source and destination windows get swapped 💫. It's an error if no window exists at src-window — like, actual error, not a vibe 💀. And if -d is given, the new window does not become the current window.

Same deal as before: if -s is omitted and there's a marked pane (see select-pane -m), the window containing the marked pane is used rather than the current window 🫶.

✂️ `unlink-window`

unlink-window [-k] [-t target-window]
              (alias: unlinkw)

Unlinks target-window 🎀. Here's the rules, listen closely:

Unless -k is given, a window may only be unlinked if it is linked to multiple sessions — windows may not be linked to no sessions, that's not a thing bestie 🚫.
If -k is specified and the window is linked to only one session, it is unlinked and destroyed 💀. Gone. Poof.

🌈 KEY BINDINGS 🌈

tmux lets a command be bound to most keys, with or without a prefix key ✨. When you're specifying keys, most of them just represent themselves (like ‘A’ to ‘Z’, casual). Ctrl keys can be prefixed with ‘C-’ or ‘^’, Shift keys with ‘S-’, and Alt (meta) with ‘M-’ 💅. And on top of that, these special key names are accepted: Up, Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space, and Tab.

Okay important note bestie: to bind the ‘"’ or ‘'’ keys you need quotation marks. Yes really. Like this:

bind-key '"' split-window
bind-key "'" new-window

A command bound to the Any key will execute for all keys which don't have a more specific binding. Catch-all energy, we stan 🌸.

Commands related to key bindings are as follows:

🎀 `bind-key`

bind-key [-nr] [-N note] [-T key-table] key [command [argument ...]]
              (alias: bind)

Binds key to command 💖. Keys are bound in a key table, and here's the tea:

By default (no -T), the key gets bound in the prefix key table. That table is used for keys pressed after the prefix key — for example, by default ‘c’ is bound to new-window in the prefix table, so ‘C-b c’ creates a new window 🎉.
The root table is for keys pressed without the prefix key. Binding ‘c’ to new-window in the root table (⚠️ not recommended bestie) means a plain ‘c’ creates a new window. Chaos.
Keys can also be bound in custom key tables, and the switch-client -T command is how you switch to them from a key binding 🦋.
-r — indicates this key may repeat. See the initial-repeat-time and repeat-time options ⭐.
-N — attaches a note to the key (shown with list-keys -N), and you clear it by passing an empty string.
The -r and -N flags can both be used without command to alter an existing binding 👑

To view the default bindings and possible commands, go see the list-keys command 🫶.

📋 `list-keys`

list-keys [-1aNr] [-F format] [-O sort-order] [-P prefix-string] [-T
        key-table] [key]
              (alias: lsk)

Lists key bindings ✨.

-F — specifies the format of each line. See the “FORMATS” section 🌈.
-T — specifies a key-table to list from.
-1 — lists only the first matching key.
-O — specifies the sort order: one of ‘key’, ‘modifier’, ‘name’ (that's the table name).
-r — reverses the sort order 🔃.

If no format is given, there are two forms, bestie:

The default lists keys as bind-key commands.
-N lists only keys with attached notes, and shows only the key and note for each key 📝.

With the default form, all key tables are listed unless specified otherwise. With the -N form, only keys in the root and prefix key tables are listed by default; -T also lists only keys in key-table. -P specifies a prefix to print before each key 🎀. And -a lists the command for keys that don't have a note rather than skipping them. No key left behind 💅.

📨 `send-keys`

send-keys [-FHKlMRX] [-c target-client] [-N repeat-count] [-t
        target-pane] [key ...]
              (alias: send)

Sends a key or keys to a window or client 📬. Each argument key is the name of the key (like ‘C-a’ or ‘NPage’) to send; and if the string isn't recognised as a key, it gets sent as a series of characters. Fine, we improvise 💁.

-K — keys are sent to target-client instead, so they're looked up in the client's key table rather than in target-pane.

All arguments are sent sequentially, first to last, in order, no jumping the queue 😤. And if no keys are given and the command is bound to a key, then that key is used. Self-referential, iconic.

-l — disables key name lookup and processes the keys as literal UTF-8 characters 🦋.
-H — expects each key to be a hexadecimal number for an ASCII character 🔢.
-R — causes the terminal state to be reset 🔄.
-M — passes through a mouse event (only valid if bound to a mouse key binding, see “MOUSE SUPPORT”) 🐭.
-X — sends a command into copy mode, see the “WINDOWS AND PANES” section 👀.
-N — specifies a repeat count.
-F — expands formats in arguments where appropriate ✨.

🎯 `send-prefix`

send-prefix [-2] [-t target-pane]

Sends the prefix key to a window as if it was pressed 🎹 — or with -2, the secondary prefix key. Yes, there's a second one. She has layers 💅.

🔓 `unbind-key`

unbind-key [-anq] [-T key-table] key
              (alias: unbind)

Unbinds the command bound to key 💔. -n and -T work the same as they do for bind-key. If -a is present, all key bindings are removed — every single one, scorched earth, no survivors 💀. The -q option prevents errors being returned, so it just vibes quietly instead 🤫.

✨ OPTIONS ✨

The appearance and behaviour of tmux can be modified by changing the value of various options 💖. Each option belongs to one or multiple scopes (server, session, window, and pane) and has a type (string, number, key, colour, flag, choice, or command) 🌈.

Values of flag-type options may be one of: 1, on, yes, 0, off, or no 🟢🔴. For possible choice values, see the respective option; for key options, check the “KEY BINDINGS” section; and for colour options, the “STYLES” section 🎨.

The tmux server has a set of global server options which do not apply to any particular window or session or pane 👑. These are altered with the set-option -s command, or displayed with the show-options -s command ✨.

On top of that, each individual session may have a set of session options, and there is a separate set of global session options 🌸. Sessions which don't have a particular option configured inherit the value from the global session options — the family heirloom vibe 🫶. Session options are set or unset with the set-option command and may be listed with the show-options command. The available server and session options are listed under the set-option command 📜.

Similarly, a set of window options is attached to each window 🪟 and a set of pane options to each pane. Pane options inherit from window options — the vibes trickle down, bestie, it's a whole family tree. This means any pane option may be set as a window option to apply the option to all panes in the window without the option set, for example these commands will set the background colour to red for all panes except pane 0:

set -w window-style bg=red
set -pt:.0 window-style bg=blue

There is also a set of global window options from which any unset window or pane options are inherited. Window and pane options are altered with set-option -w and -p commands and displayed with show-option -w and -p.

tmux also supports user options which are prefixed with a @. User options may have any name, so long as they are prefixed with @, and be set to any string, no cap. For example:

$ tmux set -wq @foo "abc123"
$ tmux show -wv @foo
abc123

Options are managed with these commands:

💅 `set-option`

set-option [-aFgopqsuUw] [-t target-pane] option [value]
              (alias: set)

Set a pane option with -p, a window option with -w, a server option with -s, otherwise a session option. If the option is not a user option, -w or -s may be unnecessary — tmux will infer the scope from the option name, assuming -w for pane options. If -g is given, the global session or window option is set.

Array options may be set by giving a key in square brackets after the option name, for example command-alias[zoom].

Here's the flag rundown, so nothing slips past you:

-F — expands formats in the option value.
-u — unsets an option, so a session inherits the option from the global options (or with -g, restores a global option to the default).
-U — unsets an option (like -u) but if the option is a pane option also unsets the option on any panes in the window.
-o — prevents setting an option that is already set.
-q — suppresses errors about unknown or ambiguous options.
-a — append mode, see below.

value depends on the option and its type and can be omitted for flag and choice options to toggle its value (choice options toggle between the first two choices).

With -a, and if the option expects a string or a style, value is appended to the existing setting. For example:

set -g status-left "foo"
set -ag status-left "bar"

Will result in foobar. And:

set -g status-style "bg=red"
set -ag status-style "fg=blue"

Will result in a red background and blue foreground. Without -a, the result would be the default background and a blue foreground. 🎨

🫶 `show-options`

show-options [-AgHpqsvw] [-F format] [-t target-pane] [option]
              (alias: show)

Show the pane options (or a single option if option is provided) with -p, the window options with -w, the server options with -s, otherwise the session options. If the option is not a user option, -w or -s may be unnecessary — tmux will infer the scope from the option name, assuming -w for pane options. Global session or window options are listed if -g is used.

-v — shows only the option value, not the name. Just the tea, no label. 🍵
-F — format is used for each option.
-q — no error will be returned if option is unset.
-H — includes hooks (omitted by default).
-A — includes options inherited from a parent set of options; such options are marked with an asterisk.

✨ Available server options are ✨

`backspace` key

Set the key sent by tmux for backspace.

`buffer-limit` number

Set the number of buffers; as new buffers are added to the top of the stack, old ones are removed from the bottom if necessary to maintain this maximum length. 📚

`clear-on-attach` [on | off]

When enabled (the default), the client terminal switches to the alternate screen and clears it when a client is attached. When disabled, tmux does not enter the alternate screen; instead the existing terminal content is scrolled into the scrollback buffer so it remains accessible.

`command-alias[]` name=value

This is an array of custom aliases for commands. If an unknown command matches name, it is replaced with value. For example, after:

set -s command-alias[zoom] zoom='resize-pane -Z'

Using:

zoom -t:.1

Is equivalent to:

resize-pane -Z -t:.1

Note that aliases are expanded when a command is parsed rather than when it is executed, so binding an alias with bind-key will bind the expanded form. 👀

`codepoint-widths[]` string

An array option allowing widths of Unicode codepoints to be overridden. Note the new width applies to all clients. Each entry is of the form codepoint=width, where codepoint may be a UTF-8 character, an identifier of the form U+number where the number is a hexadecimal number, or a range of the form U+number-U+number.

`copy-command` shell-command

Give the command to pipe to if the copy-pipe copy mode command is used without arguments.

`theme` [detect | terminal | light | dark]

Whether tmux should use the detected client theme (detect), use terminal ANSI colours (terminal), or force the light or dark theme.

`dark-theme-black`, `dark-theme-white`, `dark-theme-light-grey`, `dark-theme-dark-grey`, `dark-theme-green`, `dark-theme-yellow`, `dark-theme-red`, `dark-theme-blue`, `dark-theme-cyan`, `dark-theme-magenta`, `light-theme-black`, `light-theme-white`, `light-theme-light-grey`, `light-theme-dark-grey`, `light-theme-green`, `light-theme-yellow`, `light-theme-red`, `light-theme-blue`, `light-theme-cyan` and `light-theme-magenta` colour

Set the theme colours. These are the named colours themeblack, themewhite, themelightgrey, themedarkgrey, themegreen, themeyellow, themered, themeblue, themecyan and thememagenta which may be used in styles and elsewhere a colour is accepted. The dark-theme-* set is used when the client reports a dark background and the light-theme-* set when it reports a light background; an unknown background is treated as dark. 🌗

`default-client-command` command

Set the default command to run when tmux is called without a command. The default is new-session.

`default-terminal` terminal

Set the default terminal for new windows created in this session — the default value of the TERM environment variable. For tmux to work correctly, this must be set to screen, tmux or a derivative of them.

`escape-time` time

Set the time in milliseconds for which tmux waits after an escape is input to determine if it is part of a function or meta key sequences.

`editor` shell-command

Set the command used when tmux runs an editor.

`exit-empty` [on | off]

If enabled (the default), the server will exit when there are no active sessions.

`exit-unattached` [on | off]

If enabled, the server will exit when there are no attached clients.

`extended-keys` [on | off | always]

Controls how modified keys (keys pressed together with Control, Meta, or Shift) are reported. This is the equivalent of the modifyOtherKeys xterm(1) resource.

When set to on, the program inside the pane can request one of two modes: mode 1 which changes the sequence for only keys which lack an existing well-known representation; or mode 2 which changes the sequence for all keys. When set to always, modes 1 and 2 can still be requested by applications, but mode 1 will be forced instead of the standard mode. When set to off, this feature is disabled and only standard keys are reported.

tmux will always request extended keys itself if the terminal supports them. See also the extkeys feature for the terminal-features option, the extended-keys-format option and the pane_key_mode variable.

`extended-keys-format` [csi-u | xterm]

Selects one of the two possible formats for reporting modified keys to applications. This is the equivalent of the formatOtherKeys xterm(1) resource. For example, C-S-a will be reported as ^[[27;6;65~ when set to xterm, and as ^[[65;6u when set to csi-u. ⌨️

`focus-events` [on | off]

When enabled, focus events are requested from the terminal if supported and passed through to applications running in tmux. Attached clients should be detached and attached again after changing this option.

`focus-follows-mouse` [on | off]

When enabled and mouse is on, moving the mouse into a pane selects it.

`get-clipboard` [both | request | buffer | off]

Controls the behaviour when an application requests the clipboard from tmux.

If off, the request is ignored; if buffer, tmux responds with the newest paste buffer; request causes tmux to request the clipboard from the most recently used client (if possible) and send the reply (if any) back to the application; both is the same as request but also creates a paste buffer.

See also the set-clipboard option. 📋

`history-file` path

If not empty, a file to which tmux will write command prompt history on exit and load it from on start.

`input-buffer-size` bytes

Maximum of bytes allowed to read in escape and control sequences. Once reached, the sequence will be discarded.

`message-limit` number

Set the number of error or information messages to save in the message log for each client.

`prompt-history-limit` number

Set the number of history items to save in the history file for each type of command prompt.

`set-clipboard` [on | external | off]

Attempt to set the terminal clipboard content using the xterm(1) escape sequence, if there is an Ms entry in the terminfo(5) description (see the “TERMINFO EXTENSIONS” section).

If it's set to on, tmux will ✨both✨ accept the escape sequence that creates a buffer and try to set the terminal clipboard. If it's set to external, tmux tries to set the terminal clipboard but ignores any attempts by applications to set tmux buffers. And if it's off? tmux neither accepts the clipboard escape sequence nor tries to touch the clipboard at all. 💅

Heads up bestie — this whole feature has to be enabled in xterm(1) first by setting the resource:

disallowedWindowOps: 20,21,SetXprop

Or by changing that property from the xterm(1) interactive menu whenever you need it. 🎀

🌈 `terminal-features[]` string

Set terminal features for terminal types read from terminfo(5). tmux has a whole set of named terminal features, and each one applies the appropriate changes to the terminfo(5) entry in use. 🦋

tmux can detect features for a few common terminals, and this option is how you easily tell tmux about features supported by terminals it can't detect. The terminal-overrides option lets you set individual terminfo(5) capabilities instead — terminal-features is meant for classes of functionality supported in a standard way but just not reported by terminfo(5). Careful out here: only configure this with features the terminal actually supports, fr fr. 🙈

This is an array option where each entry is a colon-separated string made up of a terminal type pattern (matched using glob(7) patterns) followed by a list of terminal features. A feature may be suffixed with @ to disable it; for example, xterm*:sync@. The available features are:

256 — Supports 256 colours with the SGR escape sequences.
appesc — Supports application escape key mode, where the Escape key sends a sequence that cannot be mistaken for the start of another key.
clipboard — Allows setting the system clipboard.
ccolour — Allows setting the cursor colour.
cstyle — Allows setting the cursor style.
extkeys — Supports extended keys.
focus — Supports focus reporting.
hyperlinks — Supports OSC 8 hyperlinks.
ignorefkeys — Ignore function keys from terminfo(5) and use the tmux internal set only.
margins — Supports DECSLRM margins.
mouse — Supports xterm(1) mouse sequences.
osc7 — Supports the OSC 7 working directory extension.
overline — Supports the overline SGR attribute.
progressbar — Supports the OSC 9;4 progress bar extension.
rectfill — Supports the DECFRA rectangle fill escape sequence.
RGB — Supports RGB colour with the SGR escape sequences.
sixel — Supports SIXEL graphics.
strikethrough — Supports the strikethrough SGR escape sequence.
sync — Supports synchronized updates.
title — Supports xterm(1) title setting.
usstyle — Allows underscore style and colour to be set.
utf8 — Supports UTF-8 output.

🎀 `terminal-overrides[]` string

Allow terminal descriptions read using terminfo(5) to be overridden. Each entry is a colon-separated string made up of a terminal type pattern (matched using glob(7) patterns) and a set of name=value entries. 💖

So like, say you wanna set the clear terminfo(5) entry to \e[H\e[2J for all terminal types matching rxvt*:

rxvt*:clear=\e[H\e[2J

The terminal entry value gets passed through strunvis(3) before interpretation. ⭐

🌸 `user-keys[]` key

Set list of user-defined key escape sequences. Each item is associated with a key named User0, User1, and so on. Obsessed with this one ngl.

For example:

set -s user-keys[0] "\e[5;30012~"
bind User0 resize-pane -L 3

💜 `variation-selector-always-wide` [`on` | `off`]

Always treat Unicode variation selector 16 as marking a wide character. This is a feature of some terminals as part of their Unicode 14 support. 🧚

🍓 Available session options are:

activity-action [any | none | current | other]

Set action on window activity when monitor-activity is on. any means activity in any window linked to a session causes a bell or message (depending on visual-activity) in the current window of that session, none means all activity is ignored (equivalent to monitor-activity being off), current means only activity in windows other than the current window are ignored, and other means activity in the current window is ignored but not those in other windows. 👑

assume-paste-time milliseconds

If keys are entered faster than one in milliseconds, they are assumed to have been pasted rather than typed and tmux key bindings are not processed. The default is one millisecond and zero disables. ⏱️

base-index index

Set the base index from which an unused index should be searched when a new window is created. The default is zero.

bell-action [any | none | current | other]

Set action on a bell in a window when monitor-bell is on. The values are the same as those for activity-action. 🔔

default-command shell-command

Set the command used for new windows (if not specified when the window is created) to shell-command, which may be any sh(1) command. The default is an empty string, which instructs tmux to create a login shell using the value of the default-shell option.

default-shell path

Specify the default shell. This is used as the login shell for new windows when the default-command option is set to empty, and must be the full path of the executable. When started tmux tries to set a default value from the first suitable of the SHELL environment variable, the shell returned by getpwuid(3), or /bin/sh. This option should be configured when tmux is used as a login shell. 🫶

default-size XxY

Set the default size of new windows when the window-size option is set to manual or when a session is created with new-session -d. The value is the width and height separated by an x character. The default is 80x24.

destroy-unattached [off | on | keep-last | keep-group]

If on, destroy the session after the last client has detached. If off (the default), leave the session orphaned. If keep-last, destroy the session only if it is in a group and has other sessions in that group. If keep-group, destroy the session unless it is in a group and is the only session in that group. 💀

detach-on-destroy [off | on | no-detached | previous | next]

If on (the default), the client is detached when the session it is attached to is destroyed. If off, the client is switched to the most recently active of the remaining sessions. If no-detached, the client is detached only if there are no detached sessions; if detached sessions exist, the client is switched to the most recently active. If previous or next, the client is switched to the previous or next session in alphabetical order. 🔥

display-time time

Set the amount of time for which status line messages and other on-screen indicators are displayed. If set to 0, messages and indicators are displayed until a key is pressed. time is in milliseconds.

history-limit lines

Set the maximum number of lines held in pane history. 📜

initial-repeat-time time

Set the time in milliseconds for the initial repeat when a key is bound with the -r flag. This allows multiple commands to be entered without pressing the prefix key again. See also the repeat-time option. If initial-repeat-time is zero, repeat-time is used for the first key press.

key-table key-table

Set the default key table to key-table instead of root.

lock-after-time number

Lock the session (like the lock-session command) after number seconds of inactivity. The default is not to lock (set to 0). 🔒

lock-command shell-command

Command to run when locking each client. The default is to run lock(1) with -np.

menu-style style

Set the menu style. See the “STYLES” section on how to specify style.

menu-selected-style style

Set the selected menu item style. See the “STYLES” section on how to specify style.

menu-border-style style

Set the menu border style. See the “STYLES” section on how to specify style.

menu-border-lines type

Set the type of characters used for drawing menu borders. See popup-border-lines for possible values for border-lines.

message-command-style style

Set status line message command style. This is used for the command prompt with vi(1) keys when in command mode. For how to specify style, see the “STYLES” section.

message-format string

Set the format string for the prompt and message area. The special placeholder #{message} expands to the interactive prompt or message text and #{command_prompt} is set to 1 when the prompt is in command mode (vi). Style directives like fill, align, and width may be used in the format string. The default uses a conditional to select between message-style and message-command-style. ✨

message-line [0 | 1 | 2 | 3 | 4]

Set line on which status line messages and the command prompt are shown.

message-style style — sets the style of status line messages. This one covers messages and the command prompt, and the message gets drawn right on top of whatever status line is already there. A width attribute (either a fixed number of columns or a percentage like 50%) limits how wide the prompt area is, and an align attribute (left, centre, right) decides where it sits horizontally. If that width is smaller than the full terminal width, the normal status bar content stays visible around the prompt area, cute right? The fill attribute is what the default message-format uses to clear the background. Wanna know how to write a style? Go peek at STYLES 💅
mouse [on | off] — set it on and tmux captures the mouse, meaning mouse events can be bound as key bindings. Deets live in MOUSE SUPPORT 🐭
prefix key — sets the key that counts as the prefix key. On top of the standard keys listed under KEY BINDINGS, you can also set this to the special key None if you want, like, no prefix at all 👑
prefix2 key — sets a secondary key that also works as a prefix key. Same deal as prefix: None is allowed.
prefix-timeout time — how many milliseconds tmux waits after you hit the prefix before it just gives up and dismisses it. Set it to zero and the timeout is fully disabled, no cap.
prompt-cursor-colour colour — the colour of the cursor inside the command prompt.
prompt-command-cursor-colour colour — the colour of the cursor in the command prompt specifically when vi(1) keys are enabled and the prompt is chillin' in command mode.
prompt-cursor-style style — the style of the cursor in the command prompt. Available styles? Check the cursor-style options, bestie.
prompt-command-cursor-style style — same thing but for when vi(1) keys are on and the prompt is in command mode. Again, see the cursor-style options for what styles exist.
renumber-windows [on | off] — turn this on and whenever a window closes in a session, the other windows get automatically renumbered in numerical order. It respects the base-index option if you've set one. off means no renumbering, leave them alone 🙈
repeat-time time — lets you fire off multiple commands without smashing the prefix key again, within the given number of milliseconds (default is 500, iconic). Whether a key actually repeats is decided when it's bound, using the -r flag to bind-key. Repeat is enabled for the default keys bound to the resize-pane command. Also see the initial-repeat-time option ✨
set-titles [on | off] — attempts to set the client terminal title using the tsl and fsl terminfo(5) entries, if those exist. tmux automatically sets these to the \e]0;...\007 sequence if the terminal looks like it's xterm(1). Heads up: this option is off by default.
set-titles-string string — the string used to set the client terminal title when set-titles is on. Formats get expanded, check FORMATS 🌈
silence-action [any | none | current | other] — picks the action for window silence when monitor-silence is on. The values are the exact same ones as for activity-action.
status [off | on | 2 | 3 | 4 | 5] — show or hide the status line, or say how big it is. on gives you a status line one row tall; 2, 3, 4 or 5 give you more rows.
status-format[] format — the format used for each line of the status line. The default builds the top status line out of all those individual status options listed below ✨
status-interval interval — refresh the status line every interval seconds. Default behaviour is an update every 15 seconds. Set it to zero and redrawing at an interval is disabled entirely.
status-justify [left | centre | right | absolute-centre] — where the window list sits in the status line: left, centre or right. centre puts the window list in the relative centre of whatever free space exists; absolute-centre uses the centre of the entire horizontal space. Subtle difference, but it matters 💅
status-keys [vi | emacs] — picks vi or emacs-style key bindings for the status line, like at the command prompt. Default is emacs, unless VISUAL or EDITOR environment variables are set and contain the string vi.
status-left string — the display string (by default the session name) shown to the left of the status line. The string gets passed through strftime(3). Also go read FORMATS and STYLES. For details on setting names and titles, see NAMES AND TITLES.

Some examples, bestie:

#(sysctl vm.loadavg)
#[fg=yellow,bold]#(apm -l)%%#[default] [#S]

And the default is [#S] .

status-left-length length — the max length of the left component of the status line. Default is 10.
status-left-style style — the style of the left part of the status line. For how to write a style, see STYLES.
status-position [top | bottom] — where the status line lives.
status-right string — the display string to the right of the status line. By default it shows the current pane title in double quotes, plus the date and the time. Just like status-left, the string gets passed to strftime(3) and character pairs get replaced.
status-right-length length — the max length of the right component of the status line. Default is 40.
status-right-style style — the style of the right part of the status line. Again, STYLES section for the how-to.
status-style style — the style for the status line. You already know where to look: STYLES 💖
update-environment[] variable — the list of environment variables that get copied into the session environment whenever a new session is created or an existing one is attached. Any variables that don't exist in the source environment are marked to be removed from the session environment — as if -r was passed to the set-environment command.
visual-activity [on | off | both] — if on, tmux shows a message instead of sending a bell when activity happens in a window that has the monitor-activity window option enabled. Set it to both and you get a bell and a message. Double trouble 🎀
visual-bell [on | off | both] — if on, a message pops up on a bell in a window that has the monitor-bell window option enabled, instead of it being passed through to the terminal (which is what normally makes the actual sound). both gives you the bell and the message. Also see the bell-action option.
visual-silence [on | off | both] — if monitor-silence is enabled, this prints a message after the interval has expired on a given window, instead of firing off a bell. both means a bell and a message, obviously 😌
word-separators string — sets what the session thinks counts as word separator characters, for the sake of the next and previous word commands in copy mode. A space in string matches any character with the Unicode White_Space property.

Available window options are: 👑

aggressive-resize [on | off] — aggressively resize the chosen window. Meaning tmux resizes the window to the size of the smallest or largest session (see the window-size option) for which it's the current window, instead of the session it's attached to. The window can resize when the current window changes on another session. This option is great for full-screen programs that support SIGWINCH, and honestly terrible for interactive stuff like shells. Pick your fighter 💀
automatic-rename [on | off] — controls automatic window renaming. With this on, tmux renames the window automatically using the format given by automatic-rename-format. This flag gets automatically disabled for an individual window when a name is specified at creation with new-window or new-session, or later with rename-window, or with a terminal escape sequence. You can also switch it off globally with:

set-option -wg automatic-rename off

automatic-rename-format format — the format (see FORMATS) used when the automatic-rename option is enabled.
clock-mode-colour colour — sets the clock colour 🕰️
clock-mode-style [12 | 24 | 12-with-seconds | 24-with-seconds] — sets the clock's hour format.
display-panes-active-colour colour — the colour the display-panes command uses to show the indicator for the active pane.
display-panes-border-style style — the style of the borders in panes mode used by the display-panes command. Style how-to is in STYLES.
display-panes-colour colour — the colour the display-panes command uses to show the indicators for the inactive panes.
display-panes-format format — the format of the text shown by the display-panes command, expanded once for each pane.
display-panes-time time — how many milliseconds the indicators shown by the display-panes command hang around for.
fill-character format — the format used to fill terminal areas that a pane isn't using. It's expanded once for areas inside the window with is_inside set, and once for areas outside the window with is_outside set.
main-pane-height height — and also
main-pane-width width — set the width or height of the main (left or top) pane in the main-horizontal, main-horizontal-mirrored, main-vertical or main-vertical-mirrored layouts. Suffix it with % and it becomes a percentage of the window size ✨
copy-mode-match-style style — the style of search matches in copy mode. STYLES section, as always 🫶
copy-mode-mark-style style — the style of the line containing the mark in copy mode. Yep, STYLES 💜
copy-mode-current-match-style style — sets the glow-up for the current search match when you're in copy mode ✨. Wanna know how to build a style? Check the “STYLES” section bestie 💅
copy-mode-position-format format — the format of that lil position indicator in copy mode 📍
copy-mode-position-style style — style for the position indicator in copy mode 🎀 (STYLES section has the deets on specifying style)
copy-mode-selection-style style — style for your selection in copy mode 💖 (again, “STYLES” section, you know the drill)
copy-mode-current-line-number-style style — style for the current line number in copy mode 🌟 (“STYLES” section!)
copy-mode-current-line-style style — style for the line the cursor is chillin' on in copy mode 👑 (“STYLES” section)
copy-mode-line-number-style style — style for all the line numbers in copy mode 🔢 (“STYLES” section, mwah)
copy-mode-line-numbers [off | default | absolute | relative | hybrid] — show line numbers in copy mode, fr fr. Let's break it down:
- off — hides them, bye 👋
- default — shows line numbers matching the copy mode position indicator and goto-line
- absolute — shows absolute line numbers
- relative — shows line numbers relative to the cursor
- hybrid — shows the current line number as absolute, and every other line number as relative ✨

With off or default, the position indicator and goto-line use the same numbering. With absolute, relative and hybrid, they use absolute line numbers. Noted 📝

mode-keys [vi | emacs] — use vi or emacs-style key bindings in copy mode 🎹. Default is emacs, unless VISUAL or EDITOR contains ‘vi’ (then you're a vi girlie, iykyk)
mode-style style — sets the window modes style. “STYLES” section for how, bestie 💜
monitor-activity [on | off] — monitor for activity in the window 👀. Windows with activity get highlighted in the status line, slay
monitor-bell [on | off] — monitor for a bell 🔔 in the window. Windows with a bell get highlighted in the status line
monitor-silence [interval] — monitor for silence (aka no activity) in the window within interval seconds 🤫. Windows that have been silent for the interval get highlighted in the status line. An interval of zero disables the monitoring, periodt
other-pane-height height — sets the height of the other panes (not the main pane) in the main-horizontal and main-horizontal-mirrored layouts 📐. If this is set to 0 (the default), it has no effect, so it's giving nothing. If both main-pane-height and other-pane-height are set, the main pane grows taller to make the other panes the specified height — but it will never shrink to do so. If suffixed by ‘%’, this is a percentage of the window size 💯
other-pane-width width — like other-pane-height, but it sets the width of other panes in the main-vertical and main-vertical-mirrored layouts 📏
pane-active-border-style style — sets the pane border style for the currently active pane 🌈. “STYLES” section for how. Heads up: attributes are ignored 🙈
pane-base-index index — like base-index, but for the starting index of pane numbers 🔢
pane-border-format format — sets the text shown in pane border status lines ✍️
pane-border-indicators [off | colour | arrows | both] — indicate the active pane by colouring only half of the border (but only in windows with exactly two panes!), by displaying arrow markers, by drawing both, or by drawing neither 🎯
pane-border-lines type — sets the type of characters used for drawing pane borders. type can be one of:
- single — single lines using ACS or UTF-8 characters
- double — double lines using UTF-8 characters
- heavy — heavy lines using UTF-8 characters
- simple — simple ASCII characters
- number — the pane number
- spaces — space characters
- none — no border for floating panes

‘double’ and ‘heavy’ will fall back to standard ACS line drawing when UTF-8 is not supported 🫶

pane-border-status [off | top | bottom | top-floating | bottom-floating] — turn pane border status lines off, or set their position 📌. If set to top-floating or bottom-floating, status lines are shown only on floating panes 🪄
pane-border-style style — sets the pane border style for panes aside from the active one ✨. “STYLES” section for how. Attributes? Ignored, bestie 🙈
popup-style style — sets the popup style 🎀. See the “STYLES” section on how to specify style. Attributes are ignored
popup-border-style style — sets the popup border style 💅. See the “STYLES” section on how to specify style. Attributes are ignored
popup-border-lines type — sets the type of characters used for drawing popup borders. type can be one of:
- single — single lines using ACS or UTF-8 characters (default)
- rounded — a variation of single with rounded corners using UTF-8 characters 🫧
- double — double lines using UTF-8 characters
- heavy — heavy lines using UTF-8 characters
- simple — simple ASCII characters
- padded — simple ASCII space character
- none — no border

‘double’ and ‘heavy’ will fall back to standard ACS line drawing when UTF-8 is not supported 🌸

pane-scrollbars [off | modal | on | auto-hide] — when enabled, a character based scrollbar appears on the left or right of each pane 📜. A filled section of the scrollbar, known as the ‘slider’, represents the position and size of the visible part of the pane content 👀

If set to on the scrollbar is visible all the time and the pane is narrowed by the width of the scrollbar. If set to modal the scrollbar only appears when the pane is in copy mode or view mode, and auto-hides when not in use. If set to auto-hide the scrollbar is available all the time but auto-hides when not in use. With modal and auto-hide, the scrollbar overlays the pane and does not narrow or reflow it, iconic ✨

🪝 HOOKS 🪝

Okay so tmux lets commands run on all sorts of triggers, and those triggers are called hooks. Most tmux commands have an after hook, and on top of that there's a whole bunch of hooks that aren't attached to any command at all 🌟

Hooks live as array options — the members of that array get executed in order when the hook fires. And just like options, different hooks can be global or belong to a session, a window, or a pane. You configure them with the set-hook or set-option commands, and you display them with show-hooks or show-options -H. These next two commands? Literally the same, no cap:

set-hook -g pane-mode-changed[style] 'display-message changed'
set-option -g pane-mode-changed[style] 'display-message changed'

Heads up: setting a hook without specifying an array key clears the hook and sets the first member of the array 🫶

A command's after hook runs after that command completes — except when the command is itself being run as part of a hook. Those after hooks are named with an after- prefix. For example, this one adds a hook that selects the even-vertical layout after every split-window:

set-hook -g after-split-window "selectl even-vertical"

And if a command fails? The command-error hook fires 💀. For example, this could be used to write to a log file:

set-hook -g command-error "run-shell \"echo 'a tmux command failed' >>/tmp/log\""

The hooks ✨

In addition to the after hooks, these are the hooks available:

alert-activity — runs when a window has activity. See monitor-activity.
alert-bell — runs when a window has received a bell. See monitor-bell.
alert-silence — runs when a window has been silent. See monitor-silence.
client-active — runs when a client becomes the latest active client of its session.
client-attached — runs when a client is attached.
client-closed — runs when a client is closed.
client-created — runs when a client is created.
client-detached — runs when a client is detached.
client-focus-in — runs when focus enters a client.
client-focus-out — runs when focus exits a client.
client-resized — runs when a client is resized.
client-session-changed — runs when a client's attached session is changed.
client-light-theme — runs when a client switches to a light theme ☀️
client-dark-theme — runs when a client switches to a dark theme 🌙
command-error — runs when a command fails.
marked-pane-changed — runs when the marked pane is set or cleared.
pane-activity — runs when there is new output in a pane.
pane-bell — runs when a pane receives a bell.
pane-command-finished — runs when an OSC 133 command finishes in a pane.
pane-command-started — runs when an OSC 133 command starts in a pane.
pane-created — runs when a pane is created or respawned.
pane-died — runs when the program running in a pane exits, but remain-on-exit is on so the pane has not closed 😭
pane-exited — runs when the program running in a pane exits.
pane-focus-in — runs when the focus enters a pane, if the focus-events option is on.
pane-focus-out — runs when the focus exits a pane, if the focus-events option is on.
pane-mode-changed — runs when a pane changes mode.
pane-mode-entered — runs when a pane enters a mode.
pane-mode-exited — runs when a pane exits a mode.
pane-moved — runs when a pane is moved to another window.
pane-prompt-closed — runs when a prompt in a pane is closed.
pane-prompt-opened — runs when a prompt is opened in a pane.
pane-resized — runs when a pane is resized.
pane-set-clipboard — runs when the terminal clipboard is set using the xterm(1) escape sequence 📋
pane-shell-prompt — runs when an OSC 133 shell prompt starts in a pane.
pane-title-changed — runs when a pane title is changed.
session-closed — runs when a session is closed.
session-created — runs when a new session is created.
session-added-to-group — runs when a session is added to a session group.
session-removed-from-group — runs when a session is removed from a session group.
session-renamed — runs when a session is renamed.
session-window-changed — runs when a session changes its active window.
window-closed — runs when a window is closed.
window-created — runs when a window is created.
window-layout-changed — runs when a window layout is changed.
window-linked — runs when a window is linked into a session.
window-pane-changed — runs when a window changes its active pane.
window-renamed — runs when a window is renamed.
window-resized — runs when a window is resized. This may happen after the client-resized hook runs.
window-unzoomed — runs when a window is unzoomed.
window-zoomed — runs when a window is zoomed.
window-unlinked — runs when a window is unlinked from a session.

Managing hooks 🛠️

Hooks are managed with these commands:

`set-hook`

set-hook [-agpERTuw] [-B name:what:format] [-t target-pane] hook-name
        [command]

Without -E or -R, this sets (or, with -u, unsets) the hook hook-name to command. And btw, the flags are the exact same as for set-option 👯

With -B, the name:what:format thing uses the same subscription syntax as refresh-client -B:

name is the hook to run,
what selects the session, pane, all panes, window, or all windows,
and format is expanded once a second.

With -T, the hook is run only when format is true. For monitor hooks, name must begin with @. If a command is given, it gets stored as the @ hook command; otherwise only the monitor is created or replaced. Important note bestie: monitor hooks are not inherited — the hook only runs from the scope where it was created. And with -u, the subscription named by -B is removed 🫡

With -E, you fire the user event named hook-name, and hook-name must begin with @.

With -R, you run hook-name immediately. Boom, right now, no waiting 💥

`show-hooks`

show-hooks [-Bgpw] [-F format] [-t target-pane] [hook]

Shows hooks ✨. The flags are the same as for show-options.

With -B, it shows the subscriptions installed with set-hook -B. With -F, format is used for each hook 🎀

🐭 MOUSE SUPPORT 🐭

okay bestie, if the mouse option is on, tmux lets you bind mouse events as keys. iconic. every key name is a mouse event (like MouseUp1) plus a location suffix. the suffixes are:

Pane — the contents of a pane
Border — a pane border
Status — the status line window list
StatusLeft — the left part of the status line
StatusRight — the right part of the status line
StatusDefault — any other part of the status line
ScrollbarSlider — the scrollbar slider
ScrollbarUp — above the scrollbar slider
ScrollbarDown — below the scrollbar slider
Empty — empty space in the window
ControlN — on control range N

(peep the STYLES section for the tea on control ranges 💅)

and here's the whole mouse event menu, no cap:

WheelUp       WheelDown
MouseDown1    MouseUp1      MouseDrag1   MouseDragEnd1
MouseDown2    MouseUp2      MouseDrag2   MouseDragEnd2
MouseDown3    MouseUp3      MouseDrag3   MouseDragEnd3
SecondClick1  SecondClick2  SecondClick3
DoubleClick1  DoubleClick2  DoubleClick3
TripleClick1  TripleClick2  TripleClick3

so the SecondClick events fire on the second click of a double click — even if there might be a third click coming that fires TripleClick instead of DoubleClick. messy? a little. that's the rules tho.

each one gets a location suffix tacked on, like MouseDown1Status. don't forget the suffix, she's important 🎀

there's also the special token {mouse} or = that you can use as the target-window or target-pane in commands bound to mouse key bindings. it resolves to the window or pane the mouse event actually happened over — like the window in the status line where button 1 got released for a MouseUp1Status binding, or the pane the wheel was scrolled over for a WheelDownPane binding. literally knows where you're pointing 🫶

the send-keys -M flag can forward a mouse event to a pane.

and the default key bindings let the mouse select and resize panes, copy text, and switch windows using the status line. all of these kick in if the mouse option is turned on. turn it on bestie, it's the moment ✨

🌈 FORMATS 💖

some commands take the -F flag with a format argument. it's a string that controls the output format of the command. format variables go inside #{ and }, like #{session_name}. the possible variables are listed in the table below (iykyk, we're getting there), or you can use the name of a tmux option to get that option's value, or the name of an environment variable. some variables have a shorter alias like #S. also: ## becomes a single #, #, becomes a ,, and #} becomes a }.

Conditionals happen when you prefix with ?. for each pair of two arguments: if the variable in the first of the pair exists and isn't zero, the second of the pair gets chosen, otherwise it keeps going. if none of the paired conditions match, the default value is chosen. if there's an unpaired final argument, that's the default. if not, the default is the empty string. for example:

#{?session_attached,attached,not attached} includes attached if the session is attached, and not attached if it's unattached
#{?automatic-rename,yes,no} includes yes if automatic-rename is enabled, no if not
#{?#{n:window_name},#{window_name} - } includes the window name with a dash separator if there's a window name, or the empty string if the window name is empty
#{?session_format,format1,window_format,format2,format3} includes format1 for a session format, format2 for a window format, or format3 for neither a session nor a window format

conditionals can be nested arbitrarily, go off. but inside a conditional, , and } must be escaped as #, and #}, unless they're part of a #{...} replacement. for example:

#{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W

String comparisons? yes ma'am. prefix two comma-separated alternatives with ==, !=, <, >, <= or >= and a colon. so #{==:#{host},myhost} gets replaced by 1 if you're running on myhost, otherwise 0. || and && evaluate to true if any or all of the comma-separated alternatives are true, like #{||:#{pane_in_mode},#{alternate_on}}. ! evaluates to true if the value is false and vice versa, like #{!:#{pane_in_mode}}. and !! converts a value to a canonical boolean form — 1 for true, 0 for false — so #{!!:non-empty string} evaluates to 1. slay.

An m does a glob(7) pattern or regular expression comparison. first argument is the pattern, second is the string to compare. an optional argument gives flags:

r — the pattern is a regular expression instead of the default glob(7) pattern
i — ignore case
z — do a fuzzy match
p — like z but returns a list of matched positions

a fuzzy match matches plain terms as sequences where each character must appear in order but not necessarily consecutively. terms beginning with ' are exact substring matches, ^ anchors a term at the start, $ anchors it at the end, ! inverts a term, and | separates alternative groups. examples bestie:

#{m:*foo*,#{host}}
#{m/ri:^A,MYVAR}
#{m/z:dev bash,dev:1 bash}
#{m/z:^dev | ^prod,prod:1 ssh}

A C searches pane content for a glob(7) pattern or regular expression, and evaluates to zero if it's not found, or a line number if it is. like m, an r flag means search for a regular expression and i ignores case. so: #{C/r:^Start} 🌸

Numeric operators! prefix two comma-separated alternatives with an e and an operator. an optional f flag after the operator means use floating point numbers, otherwise integers. then you can follow it with a number giving the decimal places for the result. the operators are:

addition +
subtraction -
multiplication *
division /
modulus m or % (heads up: % must be escaped as %% in formats that also get expanded by strftime(3))
numeric comparison operators ==, !=, <, <=, > and >=

so #{e|*|f|4:5.5,3} multiplies 5.5 by 3 and gives a result with four decimal places, and #{e|%%:7,3} returns the modulus of 7 and 3. a replaces a numeric argument with its ASCII equivalent, so #{a:98} results in b. c replaces a tmux colour with its six-digit hexadecimal RGB value — and if you give it an argument of f or b, it instead produces the SGR escape sequence to set the foreground or background colour respectively. cute AND useful 🎀

You can cap the length of the resulting string by prefixing it with an =, a number and a colon. positive numbers count from the start of the string, negative from the end. so #{=5:pane_title} includes at most the first five characters of the pane title, and #{=-5:pane_title} the last five. a suffix or prefix can be given as a second argument — if provided, it gets appended or prepended to the string when the length has been trimmed. for example #{=/5/...:pane_title} appends ... if the pane title is more than five characters. similarly, p pads the string to a given width, so #{p10:pane_title} results in a width of at least 10 characters. a positive width pads on the left, a negative on the right. n expands to the length of the variable and w to its width when displayed, like #{n:window_name}. and R repeats the first argument a number of times given by the second, so #{R:a,3} gives you aaa. periodt.

Prefixing a time variable with t: converts it to a string, so if #{window_activity} gives 1445765102, then #{t:window_activity} gives Sun Oct 25 09:25:02 2015. add p (t/p) and you get a shorter but less accurate time format for times in the past. r (t/r) gives the time relative to the current time, like 1m or 2m23s. d (t/d) gives the difference from the time to the current time in seconds (future times are negative). and you can give a custom format with an f suffix — note that % must be escaped as %% if the format is separately being passed through strftime(3), for example in the status-left option: #{t/f/%%H#:%%M:window_activity}, see strftime(3).

The I: prefix interrogates the client. I/f is true if tmux believes the client supports the given terminal feature, like I/f:RGB. I/c is true if a client has the given terminfo(3) capability, like I/c:smcup. and I/e gives the value of a client environment variable, like #{I/e:FOO}. nosy in the best way 👑

The b: and d: prefixes are basename(3) and dirname(3) of the variable respectively. q: escapes sh(1) special characters — with an h suffix it escapes hash characters (so # becomes ##), with a it escapes tmux command arguments, and with s it uses single quotes.

⚠️ real talk: some variables like pane_title and pane_path are set by escape sequences received from the pane and may contain arbitrary content, including shell metacharacters. so use q: to escape these with commands passed to run-shell, if-shell, or pipe-pane. do not skip this bestie, it's giving security 💀

E: expands the format twice — so #{E:status-left} is the result of expanding the content of the status-left option rather than the option itself. T: is like E: but also expands strftime(3) specifiers. S:, W:, P: or L: loop over each session, window, pane or client and insert the format once for each. L:, S: and W: can take an optional sort argument: /i, /n, /t to sort by index, name, or last activity time — plus /r to sort in reverse order. /r also works with P: to reverse the sort order; panes are sorted by creation order by default. P: can additionally take /i to sort by pane index or /z to sort by z-index. so S/nr: sorts sessions by name in reverse order. for each of these, two comma-separated formats may be given, and the second one is used for the current window, active pane, or active session. for example, to get a list of windows formatted like the status line:

#{W:#{E:window-status-format} ,#{E:window-status-current-format} }

okay so inside the W: loop, bestie, there's a little bonus: user options (@name) from the windows next door are available with a next_ or prev_ prefix. So if the next window has a user option like @color, you get to call it next_@color. cute, right? 💅

Then O: loops over every single option — and if an option is an array, it loops once for each array item, so you get every last crumb. 🍓 O: can also be handed a flag to pick which options table you're rummaging through:

s — the session table
w — the window table
p — the pane table
v — the server table

g chooses global options. And the default? That's s. periodt.

V: loops over each environment variable. Its flags go like this:

s — session environment
g — global environment
c — client environment

Then N: — it checks whether a window name exists (with no suffix at all, or with the w suffix) or whether a session name exists (that's the s suffix). So for example N/w:foo gets replaced with 1 if there's a window named foo hanging around. 🦋

A prefix that looks like s/foo/bar/: swaps foo for bar all the way through. And the first argument can be an extended regular expression, plus a final argument of i makes it ignore case — like s/a(.)/\1x/i: would turn abABab into bxBxbx. 🤯 You can also use a totally different delimiter character so you don't trip over literal slashes sitting in your pattern. Like s|foo/|bar/|: will substitute foo/ with bar/ throughout. no cap.

Multiple modifiers? Separate them with a semicolon (;), as in #{T;=10:status-left}, which caps the resulting strftime(3)-expanded string at at most 10 characters. 🎀

And there's more, because of course there is: the last line of a shell command's output can be dropped in using #(). So #(uptime) inserts the system's uptime. 💖

Heads up though — when it's building formats, tmux does not wait around for #() commands to finish. It just uses the previous result from running that same command, or a placeholder if the command has never been run before. If the command hasn't exited, the most recent line of output gets used — but the status line will not be updated more than once a second.

Commands get run using /bin/sh, with the tmux global environment set (peep the GLOBAL AND SESSION ENVIRONMENT section for that one).

An l says: interpret this string literally, do not expand it. Like #{l:#{?pane_in_mode,yes,no}} just becomes #{?pane_in_mode,yes,no}. untouched, protected, iconic. ✨

The A modifier shows one frame out of a list, taking turns: #{A/count:frame,frame,...} or #{A:frame,frame,...}. Each frame gets shown for count periods of 100 milliseconds before it hands over to the next one, and after the last it wraps right back to the first. If you don't give a count, one is used. 🌀

Lowkey important: the A modifier is only expanded in the status line and pane-border-format. And if it's present, the status line or the pane borders get redrawn every 100 milliseconds. So like, #{A/2:|,/,-,\} shows those four frames in turn, changing every 200 milliseconds. slay. 🌈

The following variables are available, where appropriate:

okay bestie the format variable table is a WHOLE saga and we're still in it, no thoughts just vibes — here's the rest 💖

active_window_index — index of the active window in the session 🫶
alternate_on — 1 when the pane is living in the alternate screen ✨
alternate_saved_x — the saved cursor X over in the alternate screen
alternate_saved_y — the saved cursor Y over in the alternate screen
bracket_paste_flag — the pane's bracketed paste flag
buffer_created — when the buffer got created ⏰
buffer_full — the whole entire buffer content
buffer_name — name of the buffer
buffer_sample — a lil sample of the start of the buffer
buffer_size — size of the specified buffer in bytes
client_activity — the last time the client had any activity
client_cell_height — height of each client cell, in pixels
client_cell_width — width of each client cell, in pixels
client_colours — how many colours the client supports 🌈
client_control_mode — 1 if the client is in control mode
client_created — when the client was created
client_discarded — bytes discarded when the client fell behind 😭
client_flags — list of client flags
client_height — height of the client
client_key_table — the current key table
client_last_session — name of the client's last session
client_name — name of the client
client_pid — PID of the client process
client_prefix — 1 if the prefix key has been pressed ⌨️
client_readonly — 1 if the client is read-only
client_session — name of the client's session
client_termfeatures — the client's terminal features, if any
client_termname — terminal name of the client
client_termtype — terminal type of the client, if it's available
client_tty — pseudo terminal of the client
client_uid — UID of the client process
client_user — user of the client process
client_utf8 — 1 if the client supports UTF-8
client_width — width of the client
client_written — bytes written to the client
command — name of the command in use, if any
command_list_alias — command alias when you're listing commands
command_list_name — command name when you're listing commands
command_list_usage — command usage when you're listing commands
config_files — list of configuration files that got loaded 📂
cursor_blinking — 1 if the cursor is blinking
copy_cursor_hyperlink — the hyperlink under the cursor in copy mode
copy_cursor_line — the line the cursor is chillin' on in copy mode
copy_cursor_word — the word under the cursor in copy mode
copy_cursor_x — cursor X position in copy mode
copy_cursor_y — cursor Y position in copy mode
copy_line_numbers — 1 if line numbers are showing in copy mode 🔢
copy_position — the position shown in the copy mode indicator
copy_position_limit — the limit shown in the copy mode indicator
current_file — the current configuration file
cursor_character — the character sitting at the cursor in the pane
cursor_colour — cursor colour in the pane 🎨
cursor_flag — pane cursor flag
cursor_shape — cursor shape in the pane
cursor_very_visible — 1 if the cursor is in very visible mode 👀
cursor_x — cursor X position in the pane
cursor_y — cursor Y position in the pane
history_added — number of lines scrolled into the pane history
history_bytes — number of bytes in the window history
history_collected — number of oldest pane history lines discarded at the history limit
history_generation — a generation that gets incremented when the pane history is cleared or reflowed
history_limit — maximum window history lines
history_size — size of history, in lines
hook — name of the running hook, if any 🪝
hook_client — name of the client where the hook ran, if any
hook_fire_count — how many times the hook has fired
hook_fire_time — the last time the hook fired
hook_last — the previous value for a monitor hook
hook_monitor_format — format for a monitor hook
hook_monitor_target — target for a monitor hook
hook_pane — ID of the pane where the hook ran, if any
hook_session — ID of the session where the hook ran, if any
hook_session_name — name of the session where the hook ran, if any
hook_value — the new value for a monitor hook
hook_window — ID of the window where the hook ran, if any
hook_window_index — index of the window where the hook ran, if any
hook_window_name — name of the window where the hook ran, if any
host, #H — hostname of the local host 🏠
host_short, #h — hostname of the local host, minus the domain name
insert_flag — pane insert flag
key_string — string representation of the key binding
key_repeat — 1 if the key binding is repeatable 🔁
key_note — note of the key binding
key_prefix — global key prefix
key_table — table name of the key binding
key_command — command of the key binding
key_has_repeat — 1 if the list contains a repeatable key
key_string_width — maximum key_string width in the list
key_table_width — maximum key_table width in the list
keypad_cursor_flag — pane keypad cursor flag
keypad_flag — pane keypad flag
last_window_index — index of the last window in the session
line — line number in the list
loop_index — index of the item in the W:, P:, S:, or L: loop 🔄
loop_last_flag — 1 if it's the last window, pane, session, or client in the W:, P:, S:, or L: loop
mouse_all_flag — pane mouse all flag 🐭
mouse_any_flag — pane mouse any flag
mouse_button_flag — pane mouse button flag
mouse_hyperlink — hyperlink under the mouse, if any
mouse_line — line under the mouse, if any
mouse_sgr_flag — pane mouse SGR flag
mouse_standard_flag — pane mouse standard flag
mouse_status_line — the status line the mouse event went down on
mouse_status_range — range type or argument of the mouse event on the status line
mouse_utf8_flag — pane mouse UTF-8 flag
mouse_word — word under the mouse, if any
mouse_x — mouse X position, if any
mouse_y — mouse Y position, if any
next_session_id — unique session ID for the next new session 🆔
next_window_active — 1 if the next window in the W: loop is active
next_window_index — index of the next window in the W: loop
option_array_key — array key, if the option is an array item
option_has_array_key — 1 if the option array key is present
option_has_value — 1 if the option value is present
option_is_array — 1 if the option is an array
option_is_hook — 1 if the option is a hook
option_is_parent — 1 if the option is inherited
option_is_string — 1 if the option is a string
option_is_user — 1 if the option is a user option
option_name — name of the option
option_value — value of the option
option_value_only — 1 if only option values are gonna be shown
origin_flag — pane origin flag
pane_active — 1 if it's the active pane ⭐
pane_at_bottom — 1 if the pane is at the bottom of the window
pane_at_left — 1 if the pane is at the left of the window
pane_at_right — 1 if the pane is at the right of the window
pane_at_top — 1 if the pane is at the top of the window
pane_bg — pane background colour
pane_bottom — bottom of the pane
pane_command_duration — current or most recent OSC 133 command duration, in seconds
pane_command_end_time — time the most recent OSC 133 command ended
pane_command_running — 1 if an OSC 133 command is running
pane_command_start_time — time the current or most recent OSC 133 command started
pane_command_status — exit status from the most recent OSC 133 command
pane_current_command — the current command, if available
pane_current_path — the current path, if available
pane_dead — 1 if the pane is dead 💀
pane_dead_signal — exit signal of the process in a dead pane
pane_dead_status — exit status of the process in a dead pane
pane_dead_time — exit time of the process in a dead pane
pane_fg — pane foreground colour
pane_flags — pane flags
pane_floating_flag — 1 if the pane is floating 🎈
pane_format — 1 if the format is for a pane
pane_height — height of the pane
pane_id, #D — unique pane ID
pane_in_mode — number of modes the pane is in
pane_index, #P — index of the pane
pane_input_off — 1 if input to the pane is disabled 🔇
pane_key_mode — extended key reporting mode in this pane
pane_last — 1 if it's the last pane
pane_last_output_time — the last time the pane produced output
pane_last_prompt_time — time the most recent OSC 133 prompt began
pane_left — left of the pane
pane_marked — 1 if this is the marked pane
pane_marked_set — 1 if a marked pane is set
pane_modal_flag — 1 if the pane is modal
pane_mode — name of the pane mode, if any
pane_output_generation — a generation that gets incremented when pane output is processed
pane_path — path of the pane (the application can set this one 👀)
pane_pid — PID of the first process in the pane
pane_pipe — 1 if the pane is being piped 🚰

okay bestie we're still deep in the variable list and it is long long, but you're doing amazing, keep scrolling 💖

pane_pipe_pid — the PID of the pipe process, if there is one
pane_private_modes — list of the DECSET private modes that are enabled
pane_pb_state — the pane's progress bar state 🦋 one of hidden, normal, error, indeterminate or paused (an application can set this one)
pane_pb_progress — the pane's progress bar progress percentage (yep, an application can set this too)
pane_right — right edge of the pane
pane_search_string — the last search string you typed in copy mode
pane_start_command — the command the pane was started with
pane_start_command_list — the command the pane was started with, but quoted
pane_start_path — the path the pane was started with
pane_synchronized — 1 if the pane is synchronized
pane_tabs — the pane's tab positions
pane_title, aka #T — the title of the pane (an application can set this)
pane_top — top of the pane
pane_tty — the pane's pseudo terminal
pane_unseen_changes — 1 if there were changes in the pane while you were in a mode
pane_unzoomed_height — height of the pane when it is not zoomed
pane_unzoomed_width — width of the pane when it is not zoomed
pane_width — width of the pane
pane_x — X position of the pane
pane_y — Y position of the pane
pane_z — Z position of the pane
pane_zoomed_flag — 1 if the pane is zoomed
pid — server PID
prev_window_active — 1 if the previous window in the W: loop is active
prev_window_index — index of the previous window in the W: loop
rectangle_toggle — 1 if rectangle selection is activated
refresh_active — 1 if copy mode refresh is active
scroll_position — your scroll position in copy mode
scroll_region_lower — bottom of the scroll region in the pane
scroll_region_upper — top of the scroll region in the pane
search_count — count of search results
search_count_partial — 1 if the search count is a partial count
search_match — the search match, if there is one
search_present — 1 if a search was started in copy mode
selection_active — 1 if a selection started and it changes along with the cursor in copy mode
selection_end_x — X position of the end of the selection
selection_end_y — Y position of the end of the selection
selection_mode — the selection mode
selection_present — 1 if a selection was started in copy mode
selection_start_x — X position of the start of the selection
selection_start_y — Y position of the start of the selection
server_sessions — number of sessions
session_active — 1 if the session is active
session_activity — time of the session's last activity
session_activity_flag — 1 if any window in the session has activity
session_alerts — list of window indexes with alerts
session_attached — number of clients the session is attached to
session_attached_list — list of clients the session is attached to
session_bell_flag — 1 if any window in the session has a bell
session_created — time the session was created
session_format — 1 if the format is for a session
session_group — name of the session group
session_group_attached — number of clients that the sessions in the group are attached to
session_group_attached_list — list of clients that the sessions in the group are attached to
session_group_list — list of sessions in the group
session_group_many_attached — 1 if multiple clients are attached to the sessions in the group
session_group_size — size of the session group
session_grouped — 1 if the session is in a group
session_id — unique session ID
session_last_attached — time the session was last attached
session_many_attached — 1 if multiple clients are attached
session_marked — 1 if this session contains the marked pane
session_name, aka #S — name of the session
session_path — working directory of the session
session_silence_flag — 1 if any window in the session has a silence alert
session_stack — window indexes in most recent order
session_windows — number of windows in the session
socket_path — server socket path
sixel_support — 1 if the server has support for SIXEL
start_time — server start time
synchronized_output_flag — 1 if the pane has synchronized output enabled
uid — server UID
user — server user
version — server version
window_active — 1 if the window is active
window_active_clients — number of clients viewing this window
window_active_clients_list — list of clients viewing this window
window_active_sessions — number of sessions on which this window is active
window_active_sessions_list — list of sessions on which this window is active
window_activity — time of the window's last activity
window_activity_flag — 1 if the window has activity
window_bell_flag — 1 if the window has a bell
window_bigger — 1 if the window is larger than the client (it's giving main character window ngl)
window_cell_height — height of each cell, in pixels
window_cell_width — width of each cell, in pixels
window_end_flag — 1 if the window has the highest index
window_flags, aka #F — window flags, with # escaped as ##
window_format — 1 if the format is for a window
window_height — height of the window
window_id — unique window ID
window_index, aka #I — index of the window
window_last_flag — 1 if the window is the last used
window_layout — window layout description, ignoring zoomed window panes
window_linked — 1 if the window is linked across sessions
window_linked_sessions — number of sessions this window is linked to
window_linked_sessions_list — list of sessions this window is linked to
window_manual_height — manual height of the window, if it's set
window_manual_width — manual width of the window, if it's set
window_marked_flag — 1 if the window contains the marked pane
window_modal_pane — the modal pane in the window, if there is one
window_name, aka #W — name of the window
window_offset_x — X offset into the window if it is larger than the client
window_offset_y — Y offset into the window if it is larger than the client
window_panes — number of panes in the window
window_raw_flags — window flags with nothing escaped
window_silence_flag — 1 if the window has a silence alert
window_stack_index — index in the session's most recent stack
window_start_flag — 1 if the window has the lowest index
window_visible_layout — window layout description, respecting zoomed window panes
window_width — width of the window
window_zoomed_flag — 1 if the window is zoomed
wrap_flag — pane wrap flag 🎀

and that's not even the end bestie, keep going 💜

✨ STYLES ✨

okay bestie, so tmux has a whole bunch of options for telling it what the interface should look like — the colours, the attributes, all of it 💅 Like status-style for your status line, that's the classic one.

plus — and this is the fun part — you can also drop styles inline into format options (think status-left) by wrapping them in #[ and ]. cute, right? 🎀

A style can just be the single term default, which means "use the default style please" (and that default might come from an option, like status-style in the status line). Or it can be a list of the following, separated by spaces or commas:

fg=colour — sets the foreground colour. The colour is one of: black, red, green, yellow, blue, magenta, cyan, white; if your terminal supports it the bright variants brightblack, brightred, ... ; colour0 to colour255 from the 256-colour set; default for the default colour; terminal for the terminal default colour; or a hexadecimal RGB string like #ffffff ✨
bg=colour — sets the background colour.
us=colour — sets the underscore colour.
none — sets no attributes at all (turns off anything currently active).
acs, bright (or bold), dim, underscore, blink, reverse, hidden, italics, overline, strikethrough, double-underscore, curly-underscore, dotted-underscore, dashed-underscore — sets an attribute. Any of these can be prefixed with no to unset it. (acs is the terminal alternate character set, iykyk.)
align=left (or noalign), align=centre, align=right — aligns text to the left, centre or right of the available space, if appropriate.
fill=colour — fills the available space with a background colour if appropriate.
dim=percentage — dims the foreground and background colours by a percentage.
width=N — sets the width of the styled area. N can be a column count or a percentage (for example 50%).
link=uri (or nolink) — makes the styled text an OSC 8 hyperlink to uri, for example #[link=https://example.com]text#[nolink]. This only gets emitted to terminals that have the hyperlinks feature (see terminal-features); it works in the status line and in other formats drawn with styles. The link keeps going until nolink, default, or an empty link= shows up. Also, the uri can't contain spaces or commas and it's length-limited, so no novel-length URLs bestie 😭
list=on, list=focus, list=left-marker, list=right-marker, nolist — marks the position of the various window list components in the status-format option: list=on marks the start of the list; list=focus is the part of the list that should be kept in focus if the whole list won't fit in the available space (usually the current window); list=left-marker and list=right-marker mark the text used to show that stuff got trimmed off the left or right of the list when there isn't enough room.
noattr — do NOT copy attributes from the default style.
push-default, pop-default — stores the current colours and attributes as the default, or resets to the previous default. A push-default affects every later use of the default term until a pop-default. Heads up though: only one default can be pushed (each push-default just replaces whatever default was saved before) 🙈
range=left, range=right, range=session|X, range=window|X, range=pane|X, range=user|X, range=control|N, norange — marks a range for mouse events in the status-format option. When a mouse event lands in the range=left or range=right range, the StatusLeft and StatusRight key bindings get triggered.

range=session|X, range=window|X and range=pane|X are ranges for a session, window or pane. These trigger the Status mouse key, with the target session, window or pane given by the X argument. X is a session ID, window index in the current session, or a pane ID. For these, the mouse_status_range format variable will be set to session, window or pane.

range=user|X is a user-defined range; it triggers the Status mouse key. The argument X will be available in the mouse_status_range format variable. X must be at most 15 bytes long, so keep it short bb.

range=control|N is a set of ranges for you to define custom behaviour with. N can be 0 through 9. When a mouse event occurs in the range=control|N range, the ControlN key binding is triggered. See “MOUSE SUPPORT” for the deets.

set-default — sets the current colours and attributes as the default, overwriting any previous default. > ⚠️ Warning bestie: the previous default cannot be restored. It's gone. Periodt.

Examples are:

fg=yellow bold underscore blink
bg=black,fg=default,noreverse

🌸 NAMES AND TITLES 🌸

tmux is very much a "know the difference" kind of bestie: names and titles are two different things, and confusing them is a vibes crime 💀

Windows and sessions have names. Names are what you use to target them, and they're what shows up in the status line and in the various lists — the name is the tmux identifier for a window or session.

Only panes have titles. A pane's title is typically set by whatever program is running inside that pane, using an escape sequence (the same way it'd set the xterm(1) window title in X(7)).

Windows themselves don't have titles — a window's title is just the title of its active pane. And tmux itself may set the title of the terminal the client is running in; see the set-titles option for that one ✨

A session's name gets set with the new-session and rename-session commands. A window's name gets set with one of:

A command argument (such as -n for new-window or new-session).
An escape sequence (if the allow-rename option is turned on):

$ printf '\033kWINDOW_NAME\033\\'

Automatic renaming, which sets the name to the active command in the window's active pane. See the automatic-rename option.

When a pane is first created, its title is the hostname. A pane's title can be set via the title setting escape sequence, for example:

$ printf '\033]2;My Title\033\\'

It can also be modified with the select-pane -T command 💅

🌈 GLOBAL AND SESSION ENVIRONMENT 🌈

When the server starts up, tmux copies the environment into the global environment; and on top of that, every session has its own session environment 🫶

When a window is created, the session environment and the global environment get merged. If a variable exists in both, the value from the session environment wins. That merged result is the initial environment passed to the new process.

The update-environment session option can be used to update the session environment from the client when a new session is created or an old one is reattached. tmux also initialises the TMUX variable with some internal info so commands can be executed from inside, and the TERM variable with the correct terminal setting of screen.

Variables in both the session and global environments can be marked as hidden. Hidden variables don't get passed into the environment of new processes — they can only be used by tmux itself (in formats, for example, see the “FORMATS” section) 👑

The commands for messing with and viewing the environment are:

set-environment [-Fhgru] [-t target-session] variable [value] — (alias: setenv) Set or unset an environment variable. If -g is used, the change happens in the global environment; otherwise it's applied to the session environment for target-session. If -F is present, then value is expanded as a format. The -u flag unsets a variable. -r means the variable should be removed from the environment before starting a new process. -h marks the variable as hidden.
show-environment [-hgs] [-t target-session] [variable] — (alias: showenv) Display the environment for target-session, or the global environment with -g. If variable is omitted, all variables get shown. Variables that have been removed from the environment are prefixed with -. If -s is used, the output is formatted as a set of Bourne shell commands. -h shows hidden variables (they're omitted by default, sneaky little things 🙈).

set-environment [-Fhgru] [-t target-session] variable [value]

show-environment [-hgs] [-t target-session] [variable]

💖 STATUS LINE 💖

tmux has an optional status line, and it lives in the bottom line of each terminal. Iconic behaviour honestly.

By default the status line is enabled and one line high (you can disable it or make it multiple lines with the status session option 💫), and it contains, from left to right: the name of the current session in square brackets; the window list; the title of the active pane in double quotes; and the time and date.

Each line of the status line is configured with the status-format option. The default is made of three parts: configurable left and right sections (which can contain dynamic content like the time or the output of a shell command — see the status-left, status-left-length, status-right, and status-right-length options below), plus a central window list.

By default the window list shows the index, name and (if any) flag of the windows present in the current session, in ascending numerical order. You can customise it with the window-status-format and window-status-current-format options. The flag is one of the following symbols appended to the window name 👇

* — Denotes the current window.
- — Marks the last window (previously selected).
# — Window activity is monitored and activity has been detected.
! — Window bells are monitored and a bell has occurred in the window.
~ — The window has been silent for the monitor-silence interval.
M — The window contains the marked pane.
Z — The window's active pane is zoomed.

The # symbol relates to the monitor-activity window option. And ooh — the window name gets printed in inverted colours if there's an alert (bell, activity or silence) present 😳

The colour and attributes of the status line are configurable too: the entire status line with the status-style session option, and individual windows with the window-status-style window option 💅

The status line automatically refreshes at an interval if it has changed, and that interval can be controlled with the status-interval session option.

Commands related to the status line are as follows:

clear-prompt-history [-T prompt-type] — (alias: clearphist) Clear status prompt history for prompt type prompt-type. If -T is omitted, then it clears history for all types. See command-prompt for the possible values of prompt-type.

clear-prompt-history [-T prompt-type]

`command-prompt`</p> 💬

command-prompt [-1bCeFiklNP] [-I inputs] [-p prompts] [-t target-client]
        [-T prompt-type] [template]

Opens up a command prompt inside a client, bestie. You'd use this from inside tmux to run commands interactively, like a little main character text box. 🎀

If template is there, it gets used as the command. And with -F, that template gets expanded as a format. ✨

If -I shows up, inputs is a comma-separated list of the starting text for each prompt. If -p is given, prompts is a comma-separated list of prompts shown in order — otherwise you just get one single prompt, built from template if present, or ':' if not. And -l disables splitting of inputs and prompts at commas, treating them literally. No splitting, no drama. 💅

Before the command runs, the first occurrence of the string ‘%%’ and all occurrences of ‘%1’ get replaced with the response to the first prompt, all ‘%2’ get replaced with the response to the second prompt, and so on for however many prompts you have. You can replace up to nine prompt responses (‘%1’ through ‘%9’). And ‘%%%’ is like ‘%%’ but any quotation marks get escaped. 🦋

-1 — makes the prompt accept only ONE key press, so the resulting input is a single character
-k — like -1 but the key press gets translated to a key name
-N — makes the prompt only accept numeric key presses
-C — panes keep getting updated while the prompt is displayed
-i — executes the command every time the prompt input changes instead of waiting for the user to exit the command prompt
-e — makes BSpace cancel an empty prompt
-P — opens the prompt inside a pane instead of on the status line

-T tells tmux what prompt-type you're working with. This changes what completions get offered when you hit Tab. The available types are: ‘command’, ‘search’. iykyk ✨

Now, these keys have special meaning in the command prompt, and it depends on the value of the status-keys option. Here's the whole vibe check, vi girlies and emacs girlies both eating:

Cancel command prompt — vi: q · emacs: Escape
Delete from cursor to start of word — emacs: C-w
Delete entire command — vi: d · emacs: C-u
Delete from cursor to end — vi: D · emacs: C-k
Execute command — vi: Enter · emacs: Enter
Get next command from history — emacs: Down
Get previous command from history — emacs: Up
Insert top paste buffer — vi: p · emacs: C-y
Look for completions — vi: Tab · emacs: Tab
Move cursor left — vi: h · emacs: Left
Move cursor right — vi: l · emacs: Right
Move cursor to end — vi: $ · emacs: C-e
Move cursor to next word — vi: w · emacs: M-f
Move cursor to previous word — vi: b · emacs: M-b
Move cursor to start — vi: 0 · emacs: C-a
Transpose characters — emacs: C-t

With -b, the prompt is shown in the background and the invoking client doesn't exit until it gets dismissed. 🫶

`confirm-before` 🙈

confirm-before [-by] [-c confirm-key] [-p prompt] [-t target-client]
        command
              (alias: confirm)

Asks for confirmation before executing command, because we do NOT run things impulsively around here. 🎀 If -p is given, prompt is the prompt to display — otherwise a prompt gets constructed from command. It may contain the special character sequences supported by the status-left option. With -b, the prompt is shown in the background and the invoking client doesn't exit until it gets dismissed. -y changes the default behaviour (that's if Enter alone is pressed) of the prompt to run the command. And -c changes the confirmation key to confirm-key; the default is ‘y’. ⭐

display-menu [-OM] [-b border-lines] [-c target-client] [-C
        starting-choice] [-H selected-style] [-s style] [-S
        border-style] [-t target-pane] [-T title] [-x position] [-y
        position] name key command [name key command ...]
              (alias: menu)

Displays a menu on target-client. And target-pane gives the target for any commands run from that menu. Menus are iconic, we love a dropdown moment. 💅

A menu gets passed as a series of arguments: first the menu item name, second the key shortcut (or empty for none), and third the command to run when that menu item is chosen. The name and command are formats — see the “FORMATS” and “STYLES” sections. If the name begins with a hyphen (-), then the item is disabled (shown dim) and may not be chosen. And the name may be empty for a separator line, in which case both the key and command should be omitted. ✨

-b — sets the type of characters used for drawing menu borders. See popup-border-lines for possible values for border-lines.
-H — sets the style for the selected menu item (see “STYLES”)
-s — sets the style for the menu (see “STYLES”)
-S — sets the style for the menu border (see “STYLES”)
-T — a format for the menu title (see “FORMATS”)
-C — sets the menu item selected by default, if the menu is not bound to a mouse key binding
-x and -y — give the position of the menu. Both may be a row or column number, or one of the special values below.

Okay so the special position values, memorize these fr fr:

C — Flag: Both — the centre of the terminal
R — Flag: -x — the right side of the terminal
P — Flag: Both — the bottom left of the pane
M — Flag: Both — the mouse position
L — Flag: Both — the position of the last menu
W — Flag: Both — the window position on the status line
S — Flag: -y — the line above or below the status line

Or it can be a format, which gets expanded including these additional variables 👑

popup_centre_x — Centered in the client
popup_centre_y — Centered in the client
popup_height — Height of menu or popup
popup_last_x — Left of the last menu
popup_last_y — Bottom of the last menu
popup_mouse_bottom — Bottom of at the mouse
popup_mouse_centre_x — Horizontal centre at the mouse
popup_mouse_centre_y — Vertical centre at the mouse
popup_mouse_top — Top at the mouse
popup_mouse_x — Mouse X position
popup_mouse_y — Mouse Y position
popup_pane_bottom — Bottom of the pane
popup_pane_left — Left of the pane
popup_pane_right — Right of the pane
popup_pane_top — Top of the pane
popup_status_line_y — Above or below the status line
popup_width — Width of menu or popup
popup_window_status_line_x — At the window position in status line
popup_window_status_line_y — At the status line showing the window

Each menu consists of items followed by a key shortcut shown in brackets. If the menu is too large to fit on the terminal, it is not displayed — it just does not show up, no cap. 😭 Pressing the key shortcut chooses the corresponding item. If the mouse is enabled and the menu was opened from a mouse key binding, releasing the mouse button with an item selected chooses that item, and releasing the mouse button without an item selected closes the menu. -O changes this behaviour so that the menu does not close when the mouse button is released without an item selected — the menu is not closed, and a mouse button must be clicked to choose an item. 🖱️

-M tells tmux the menu should handle mouse events; by default only menus opened from mouse key bindings do so.

And these keys are available in menus:

Enter — Choose selected item
Up — Select previous item
Down — Select next item
q — Exit menu

`display-message` 💌

display-message [-aCIjlNpv] [-c target-client] [-d delay] [-t
        target-pane] [message]
              (alias: display)

Displays a message. If -p is given, the output is printed to stdout — otherwise it's displayed in the target-client status line for up to delay milliseconds. If delay isn't given, the display-time option is used; a delay of zero waits for a key press. -N ignores key presses and closes only after the delay expires. If -C is given, the pane keeps getting updated while the message is displayed. If -l is given, message is printed unchanged — no format expansion, literally as-is. Otherwise, the format of message is described in the “FORMATS” section, and information is taken from target-pane if -t is given, otherwise from the active pane. 🌸

If -j is given, message is parsed as JSON and printed. 🦋

-v prints verbose logging as the format is parsed, and -a lists the format variables and their values. Obsessed with a good debug moment.

-I forwards any input read from stdin to the empty pane given by target-pane. 🫶

display-popup [-BCEkN] [-b border-lines] [-c target-client] [-d
        start-directory] [-e environment] [-h height] [-s style] [-S
        border-style] [-t target-pane] [-T title] [-w width] [-x
        position] [-y position] [shell-command [argument ...]]
              (alias: popup)

Displays a popup running shell-command (or default-command when it's omitted) on target-client. A popup is a rectangular box drawn over the top of any panes — floating window energy, main character behaviour, we love it. 👑 If the command is run inside an existing popup, that popup gets modified. And in that case, only the -b, -B, -C, -E, -EE, -K, -N, -s, and -S options are accepted — everything else is straight-up ignored. 💀

-E closes the popup automatically when shell-command exits. Two -Es (-EE) closes the popup only if shell-command exited with success. And -k allows any key to dismiss the popup instead of only ‘Escape’ or ‘C-c’. ✨

-x, -y — these two set where the popup lands, and they mean exactly the same thing they mean over in display-menu. same energy, different command 💅
-w, -h — popup width and height, and bestie both of these can be a percentage too (just slap a % on the end). leave them out entirely and you get half the terminal size, no biggie.
-B — no border around the popup. bye border. 🙈
-b — sets what kind of characters get used to draw the popup borders. heads up though: if -B is in play, -b is just ignored, like it's not even there. for the possible values of border-lines, go peek at popup-border-lines.
-s — the style for the popup itself, and -S — the style for the popup border (see "STYLES").
-e — takes the form VARIABLE=value and sets an environment variable for the popup. and yes you can stack it, specify it as many times as you want. ✨
-T — a format for the popup title (see "FORMATS").
-C — closes any popup on the client. all of them. gone.
-N — disables any -E, -EE, or -k option you specified earlier. like an undo button for those three.

`show-prompt-history [-T prompt-type]`

(alias: showphist)

Shows you the status prompt history for the prompt type prompt-type. if you skip -T? then it just shows you the history for all the types, because why gatekeep. also, go check command-prompt for what values prompt-type is allowed to be. 🌸

🫧 BUFFERS 🫧

OK so tmux keeps a whole little collection of named paste buffers, and every single one of them is either explicitly named or automatically named. let's break that down:

explicitly named buffers get their name when you create them with the set-buffer or load-buffer commands — or when you rename an automatically named buffer using set-buffer -n.
automatically named buffers just get handed a name like buffer0001, buffer0002, and so on, counting up.

Once you hit the buffer-limit option, the oldest automatically named buffer gets deleted to make room. and the explicitly named ones? they're not subject to buffer-limit at all, they're built different 👑 — and you can delete them yourself with the delete-buffer command.

You can add buffers using copy-mode, or with the set-buffer and load-buffer commands, and then paste them into a window with the paste-buffer command. and here's a handy one: if you run a buffer command and don't specify which buffer, it just assumes the most recently added automatically named buffer. iykyk.

Oh also — there's a configurable history buffer maintained for each window too. by default it keeps up to 2000 lines, but you can change that with the history-limit option (see the set-option command above).

The buffer commands are as follows:

`choose-buffer [-kNryZ] [-F format] [-f filter] [-K key-format] [-O sort-order] [-t target-pane] [template]`

Puts a pane into buffer mode, where you can pick a buffer interactively from a list. every buffer gets shown on one line. there's a shortcut key shown on the left in brackets so you can just jump straight to one, or you can navigate the list and choose/manipulate stuff with the keys below. -Z zooms the pane. -y disables any confirmation prompts (living dangerously, love that).

the following keys may be used in buffer mode:

Enter — Paste selected buffer
Up — Select previous buffer
Down — Select next buffer
C-s — Search by name or content
n — Repeat last search forwards
N — Repeat last search backwards
t — Toggle if buffer is tagged
T — Tag no buffers
C-t — Tag all buffers
p — Paste selected buffer
P — Paste tagged buffers
d — Delete selected buffer
D — Delete tagged buffers
e — Open the buffer in an editor
f — Enter a format to filter items
c — Clear the current filter
O — Change sort order
r — Reverse sort order
v — Toggle preview
F1 or C-h — Display help
q — Exit mode

Once a buffer is chosen, %% gets replaced by the buffer name inside template, and the result is executed as a command. if you didn't give a template at all, then "paste-buffer -p -b '%%'" is what gets used. ✨

-O — the initial sort order, one of creation (time), name, or size.
-r — reverses the sort order.
-f — an initial filter, and the filter IS a format — if it evaluates to zero the item in the list isn't shown, otherwise it is shown. and if a filter would lead to an empty list, it's just ignored (no empty-list violence here 💀).
-F — the format for each item in the list, and -K — a format for each shortcut key. both of these get evaluated once for each line.
-N — starts without the preview.
-k — kills the pane when the mode is exited.
The choose-buffer command only works if at least one client is attached.

`clear-history [-H] [-t target-pane]`

(alias: clearhist)

Removes and frees the history for the specified pane. with -H it also wipes all the hyperlinks. clean slate bestie 🧹

`delete-buffer [-b buffer-name]`

(alias: deleteb)

Deletes the buffer named buffer-name — or, if you didn't name one, the most recently added automatically named buffer gets the boot.

`list-buffers [-r] [-F format] [-f filter] [-O sort-order]`

(alias: lsb)

Lists the global buffers. -F sets the format of each line, and -f sets a filter — only buffers where the filter is true get shown. see the "FORMATS" section for that. -O picks the sort order, one of name, size, or creation (time), and -r flips that sort order around. 🌈

`load-buffer [-w] [-b buffer-name] [-t target-client] path`

(alias: loadb)

Loads the contents of the specified paste buffer from path. if you hand it -w, the buffer also gets sent to the clipboard for target-client using the xterm(1) escape sequence — if possible. and if path is -, the contents are read from stdin.

`paste-buffer [-dprS] [-b buffer-name] [-s separator] [-t target-pane]`

(alias: pasteb)

Inserts the contents of a paste buffer into the specified pane. don't specify a pane and it pastes into the current one. by default control characters are sanitized with vis(3); -S disables that. and with -d, it also deletes the paste buffer after.

when outputting, any linefeed (LF) characters in the paste buffer get replaced with a separator — by default, carriage return (CR). you can set a custom separator with the -s flag. the -r flag means do no replacement (which is the same as a separator of LF). and if you pass -p, paste bracket control codes get inserted around the buffer, if the application has requested bracketed paste mode. 🫶

`save-buffer [-a] [-b buffer-name] path`

(alias: saveb)

Saves the contents of the specified paste buffer to path. the -a option appends to the file instead of overwriting it. and if path is -, the contents get written to stdout.

`set-buffer [-aw] [-b buffer-name] [-t target-client] [-n new-buffer-name] data`

(alias: setb)

Sets the contents of the specified buffer to data. give it -w and the buffer also gets sent to the clipboard for target-client using the xterm(1) escape sequence — if possible. the -a option appends to the buffer instead of overwriting it. and the -n option renames the buffer to new-buffer-name.

`show-buffer [-b buffer-name]`

(alias: showb)

Displays the contents of the specified buffer. simple as that. 💖

✨ MISCELLANEOUS ✨

Miscellaneous commands are as follows:

`clock-mode [-t target-pane]`

Displays a large clock. that's it that's the command. iconic honestly 🕐

`if-shell [-bF] [-t target-pane] shell-command command [command]`

(alias: if)

Executes the first command if shell-command (run with /bin/sh) returns success — or the second command otherwise. before it gets executed, shell-command is expanded using the rules from the "FORMATS" section, including the ones relevant to target-pane. with -b, shell-command runs in the background.

if you give it -F, then shell-command is not executed — instead it's considered successful if it's neither empty nor zero (after formats are expanded). cute little logic check.

`lock-server`

(alias: lock)

Locks each client individually by running the command specified by the lock-command option. 🔒

`run-shell [-bCE] [-c start-directory] [-d delay] [-t target-pane] [shell-command [argument ...]]`

(alias: run)

Executes shell-command using /bin/sh — or, with -C, a tmux command — in the background, without creating a window. before being executed, shell-command gets expanded using the rules specified in the "FORMATS" section. and if you give it argument values, they're available as #{1}, #{2}, and so on. for example:

run-shell 'myscript.sh #{1} #{2}' foo bar

with -b, the command runs in the background. -d waits delay seconds before starting the command. -E redirects the command's stderr to stdout instead of just ignoring it. if -c is given, the current working directory gets set to start-directory. and if -C is not given, any output to stdout is displayed in view mode (in the pane specified by -t, or the current pane if -t is omitted) after the command finishes. if the command fails, the exit status is displayed too. 🌟

`wait-for [-ELSUlv] [-F format] [-w waiter] name`

(alias: wait)

When used with no options at all, this prevents the client from exiting until it gets woken using wait-for -S with the same channel. when -L is used, the channel is locked, and any clients that try to lock that same channel get made to wait until the channel is unlocked with wait-for -U.

With -E, tmux waits for the next event with name. events include hook and notification names, and user @ events generated by set-hook -E or set-hook -B. if -F is given, format must also be true. if -v is given, event payload keys get printed (whether or not format is true). 👀

-l lists the waiters for name, and -w wakes waiter on name immediately.

💅 EXIT MESSAGES 💅

So when a tmux client dips out, it leaves a little note behind, bestie. It's gonna be one of these:

detached (from session ...) — the client just detached like a normal, well-adjusted queen. No drama.
detached and SIGHUP — the client detached AND its parent yeeted a SIGHUP at it (like when you do detach-client -P). Rude but valid.
lost tty — the client's tty(4) or pty(4) got destroyed out of nowhere. literally just evaporated 😭
terminated — the client got taken out with SIGTERM.
too far behind — client's in control mode and lowkey couldn't keep up with all the data tmux was throwing at it. not the client's fault, it's just a lot 🫠
exited — the server exited because it had no sessions. empty house energy.
server exited — the server exited when it caught a SIGTERM.
server exited unexpectedly — the server crashed or otherwise bailed without telling the client why. the betrayal.

🦋 TERMINFO EXTENSIONS 🦋

Okay so tmux speaks some unofficial bonus features from terminfo(5). You do NOT normally need to set these by hand — instead just use the terminal-features option, periodt. But here's the whole lore anyway because I love you:

AX — an existing extension that tells tmux the terminal supports default colours. ✨
Bidi — tells tmux the terminal supports the VTE bidirectional text extensions.
Cs, Cr — set the cursor colour. Cs takes a single string argument and uses it to set the colour; Cr takes no arguments and restores the default cursor colour. If it's set, you can do a sequence like this to change the cursor colour from inside tmux:

$ printf '\033]12;red\033\\'

The colour is an X(7) colour, see XParseColor(3).

Cmg, Clmg, Dsmg, Enmg — set, clear, disable or enable DECSLRM margins. These get set automatically if the terminal reports it's VT420 compatible.
Dsbp, Enbp — disable and enable bracketed paste. Set automatically if the XT capability is present.
Dseks, Eneks — disable and enable extended keys.
Dsesc, Enesc — disable and enable application escape key mode.
Dsfcs, Enfcs — disable and enable focus reporting. Set automatically if the XT capability is present.
Hls — set or clear a hyperlink annotation.
Nobr — tells tmux the terminal does not use bright colors for bold display.
Rect — tells tmux the terminal supports rectangle operations.
Smol — enable the overline attribute.
Smulx — set a styled underscore. The single parameter is one of: 0 for no underscore, 1 for normal underscore, 2 for double underscore, 3 for curly underscore, 4 for dotted underscore and 5 for dashed underscore. so many underscores, we're so spoiled 💅
Setulc, Setulc1, ol — set the underscore colour or reset to the default. Setulc is for RGB colours and Setulc1 for ANSI or 256 colours. The Setulc argument is (red * 65536) + (green * 256) + blue where each is between 0 and 255.
Ss, Se — set or reset the cursor style. If set, a sequence like this can change the cursor to an underline:

$ printf '\033[4 q'

If Se is not set, Ss with argument 0 will be used to reset the cursor style instead.

Spb — set the state and progress for the OSC9;4 progress bar.
Swd — set the opening sequence for the working directory notification. The sequence is terminated using the standard fsl capability.
Sxl — indicates the terminal supports SIXEL.
Sync — start (parameter is 1) or end (parameter is 2) a synchronized update.
Tc — indicate the terminal supports the 'direct colour' RGB escape sequence (for example, \e[38;2;255;255;255m).
- If supported, this is used for the initialize colour escape sequence (which may be enabled by adding the 'initc' and 'ccc' capabilities to the tmux terminfo(5) entry).
- This is equivalent to the RGB terminfo(5) capability.
Ms — store the current buffer in the host terminal's selection (clipboard). See the set-clipboard option above and the xterm(1) man page.
XT — this is an existing extension capability that tmux uses to mean the terminal supports the xterm(1) title set sequences and to automatically set some of the capabilities above.

👑 CONTROL MODE 👑

tmux serves a whole other textual interface called control mode, and it's giving "let the apps talk to tmux directly." It lets applications communicate with tmux using a simple text-only protocol. no frills, just vibes and bytes. 🫶

In control mode, a client sends tmux commands or command sequences terminated by newlines on standard input. Each command will produce exactly one block of output on standard output. An output block is a %begin line followed by the output (which may be empty), and it ends with a %end or %error. The %begin and its matching %end or %error have three arguments: an integer time (as seconds from epoch), command number, and flags (currently not used). For example:

%begin 1363006971 2 1
0: ksh* (1 panes) [80x24] [layout {"V":2,"L":{"t":"p","w":80,"h":24,"x":0,"y":0,"a":true,"i":0,"I":"%2"}}] @2 (active)
%end 1363006971 2 1

The refresh-client -C command may be used to set the size of a client in control mode.

In control mode, tmux also outputs notifications. A notification will never occur inside an output block — that's the rule, no cap.

The following notifications are defined:

%client-detached client — the client has detached.
%client-session-changed client session-id name — the client is now attached to the session with ID session-id, which is named name.
%config-error error — an error has happened in a configuration file.
%continue pane-id — the pane has been continued after being paused (if the pause-after flag is set, see refresh-client -A).
%exit [reason] — the tmux client is exiting immediately, either because it is not attached to any session or an error occurred. If present, reason describes why the client exited.
%extended-output pane-id age ... : value — new form of %output sent when the pause-after flag is set. age is the time in milliseconds for which tmux had buffered the output before it was sent. Any subsequent arguments up until a single ':' are for future use and should be ignored.
%layout-change window-id window-layout window-visible-layout window-flags — the layout of a window with ID window-id changed. The new layout is window-layout and the window's visible layout is window-visible-layout. If the new-layouts flag is set, both layout fields use the new format string; see refresh-client -f. The window flags are window-flags.
%message message — a message sent with the display-message command.
%output pane-id value — a window pane produced output. value escapes non-printable characters and backslash as octal \xxx.
%pane-mode-changed pane-id — the pane with ID pane-id has changed mode.
%paste-buffer-changed name — paste buffer name has been changed.
%paste-buffer-deleted name — paste buffer name has been deleted.
%pause pane-id — the pane has been paused (if the pause-after flag is set).
%session-changed session-id name — the client is now attached to the session with ID session-id, which is named name.
%session-renamed name — the current session was renamed to name.
%session-window-changed session-id window-id — the session with ID session-id changed its active window to the window with ID window-id.
%sessions-changed — a session was created or destroyed.
%subscription-changed name session-id window-id window-index pane-id ... : value — the value of the format associated with subscription name has changed to value. See refresh-client -B. Any arguments after pane-id up until a single ':' are for future use and should be ignored.
%unlinked-window-add window-id — the window with ID window-id was created but is not linked to the current session.
%unlinked-window-close window-id — the window with ID window-id, which is not linked to the current session, was closed.
%unlinked-window-renamed window-id new-name — the window with ID window-id, which is not linked to the current session, was renamed.
%window-add window-id — the window with ID window-id was linked to the current session.
%window-close window-id — the window with ID window-id closed.
%window-pane-changed window-id pane-id — the active pane in the window with ID window-id changed to the pane with ID pane-id.
%window-renamed window-id name — the window with ID window-id was renamed to name.

🌸 ENVIRONMENT 🌸

When tmux boots up, it peeks at these environment variables, like a little vibe check before the party starts:

EDITOR — if the command in here contains the string vi, and VISUAL is not set, tmux goes with vi-style key bindings. This gets overridden by the mode-keys and status-keys options. (She's just a suggestion bestie, the options always win 💅)
HOME — the user's login directory. If it's unset, tmux goes and consults the passwd(5) database instead, like asking the group chat when your friend isn't picking up.
LC_CTYPE — the character encoding locale(1). Okay this one does two separate jobs, so pay attention:
- For output to the terminal: UTF-8 gets used if you gave the -u option, or if LC_CTYPE contains "UTF-8" or "UTF8". Otherwise it's ASCII-only, and every non-ASCII character gets replaced with underscores (_). 💀
- For input: tmux always runs with a UTF-8 locale, no negotiation. If en_US.UTF-8 is provided by the operating system, that's what's used and LC_CTYPE is straight-up ignored for input. Otherwise, LC_CTYPE tells tmux what the UTF-8 locale is called on this system. And if the locale named by LC_CTYPE isn't available, or isn't a UTF-8 locale? tmux exits with an error message. She said what she said 😭
LC_TIME — the date and time locale(1) format. It's what feeds the locale-dependent strftime(3) format specifiers. ✨
PWD — the current working directory to be set in the global environment. This can be genuinely useful if it contains symbolic links. But heads up: if the value here doesn't match the actual current working directory, the variable is ignored, and the result of getcwd(3) is used instead. No lying in this household 🙈
SHELL — the absolute path to the default shell for new windows. See the default-shell option for the details.
TMUX_TMPDIR — the parent directory of the directory that holds the server sockets. See the -L option for the whole story.
VISUAL — if the command in this variable contains the string vi, use vi-style key bindings. Overridden by the mode-keys and status-keys options, same as EDITOR.

📁 FILES 📁

~/.tmux.conf
$XDG_CONFIG_HOME/tmux/tmux.conf
~/.config/tmux/tmux.conf

→ these are the default tmux configuration file. Yes bestie, multiple locations, she's flexible like that 🦋

/etc/tmux.conf — the system-wide configuration file.

✨ EXAMPLES ✨

Wanna spin up a brand new tmux session running vi(1)? Say less:

$ tmux new-session vi

Most commands have a shorter form, aka an alias. For new-session, that alias is new:

$ tmux new vi

Alternatively, you can just type the shortest unambiguous form of a command and it'll accept that. But if several commands match, it lists them out for you, like:

$ tmux n
ambiguous command: n, could be: new-session, new-window, next-window

Inside an active session, you can make a new window by typing C-b c — that's Ctrl followed by the b key, followed by the c key.

Windows can be navigated with: C-b 0 (jump to window 0), C-b 1 (jump to window 1), and so on and so on; C-b n grabs the next window; and C-b p goes to the previous one. Hop around like you own the place 👑

A session can be detached with C-b d — or by some outside event, like ssh(1) disconnecting on you, rude — and then reattached with:

$ tmux attach-session

Type C-b ? and it lists the current key bindings for the current window. Use up and down to scroll through the list, or press q to bail out. 🎀

If you want commands to run when the tmux server starts up, drop them in the ~/.tmux.conf config file. Some common faves include:

Changing the default prefix key:

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

Turning the status line off, or changing its colour:

set-option -g status off
set-option -g status-style bg=blue

Setting other options, like the default command, or locking after 30 minutes of inactivity:

set-option -g default-command "exec /bin/ksh"
set-option -g lock-after-time 1800

Creating new key bindings:

bind-key b set-option status
bind-key / command-prompt "split-window 'exec man %%'"
bind-key S command-prompt "new-window -n %1 'ssh %1'"

👀 SEE ALSO 👀

pty(4)

👑 AUTHORS 👑

Nicholas Marriott <nicholas.marriott@gmail.com> — the icon, the legend, the one who made your terminal life cute fr fr 💖

And that's the whole page bestie, you made it to the end!! 🌈 This version is the Debian one, dated September 23, 2026, for the page TMUX(1) — which, yes, means you genuinely read all of it and I'm so proud of you, that's main character energy if I've ever seen it. Go forth and multiplex 💅✨🫶

📦 where this page comes from

arch rolling: tmux 3.8-1 · BSD
fedora 44: tmux 3.8-2.fc44 · ISC AND BSD-2-Clause AND BSD-3-Clause AND SSH-short AND LicenseRef-Fedora-Public-Domain
nixpkgs unstable: tmux 3.8
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

TMUX(1)

💖 TMUX(1) 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

👑 DEFAULT KEY BINDINGS 👑

✨ COMMAND PARSING AND EXECUTION ✨

🔍 PARSING SYNTAX 🔍

✨ COMMANDS ✨

🫶 CLIENTS AND SESSIONS 🫶

has-session 💅

kill-server 💀

kill-session 🔥

list-clients 📋

list-commands 🎀

list-sessions 🌸

lock-client 🔒

lock-session 🔒✨

new-session 🌈

refresh-client 🧚

rename-session ✏️

server-access 🔐

show-messages 📨

source-file 📂

start-server ⭐

suspend-client 😴

switch-client 🔁

WINDOWS AND PANES 🪟✨

🫧 COMMANDS (still going, bestie, we're so back) 🫧

capture-pane

choose-client

choose-tree

customize-mode

switch-mode

display-panes

find-window

join-pane

kill-pane

kill-window

last-pane

last-window

link-window

list-panes

list-windows

move-pane

🪟 select-window

✂️ split-window

🔄 swap-pane

🔁 swap-window

✂️ unlink-window