This used to be a single ~/.tmux.conf. It is now five small files, split by
reason for change. Keys live in bindings.conf, looks in statusline.conf,
behavior in options.conf. When I want to change how a key behaves I know the
file before I open an editor. The edit loop is find the file, change a line,
press C-a r.
This is not a big config. The five files add up to 77 lines, comments and blank
lines included, short enough to read top to bottom in one sitting. Splitting it
is not about escaping an unmanageable file. It is a structure I carry through
~/dotfiles-macos, where the Neovim config and the shell config follow the same
rule. Small files, one concern each, linked with stow.
This runs on macOS with tmux 3.8 from Homebrew. Where something is
version-dependent or machine-specific, I say so. There is no plugin manager
involved and no plugin at all.
TL;DR
There isn’t much to my tmux configuration. A five-line tmux.conf sources four
files (options, terminal, bindings, status line), and ~/.config/tmux is a
symlink to the .config/tmux directory in my dotfiles repo, so tmux finds it
through its normal config discovery.
I don’t use a plugin manager, and there are no plugins. Two scripts in
~/dotfiles-macos/scripts/ round out the workflow. One builds a three-pane
workspace, and the other raises a persistent pi session in a popup without
leaving the current pane. The bindings also hand C-h, C-j, C-k, C-l and
C-\ to Neovim when it is the active pane, which is what vim-tmux-navigator
needs on the tmux side.
It’s not meant to be a universal tmux setup. It’s the multiplexer shaped to make
this particular machine comfortable to work in, and the files are split so that
shape stays easy to edit.
Configuration Layout
The source of truth lives in my ~/dotfiles-macos repo.
~/dotfiles-macos/.config/tmux/
├── tmux.conf # thin orchestrator
├── options.conf # session and input behavior
├── terminal.conf # terminal capabilities
├── bindings.conf # keys
└── statusline.conf # status line
~/.config/tmux is a symlink to that directory, created by running stow .
from the repo root. There is no ~/.tmux.conf, and XDG_CONFIG_HOME is not
set. tmux also looks for ~/.config/tmux/tmux.conf, and on this machine that is
the only location that exists, so the symlink is the config tmux reads.
The orchestrator is the whole config set.
# Load shared portable config files
source-file ~/.config/tmux/options.conf
source-file ~/.config/tmux/terminal.conf
source-file ~/.config/tmux/bindings.conf
source-file ~/.config/tmux/statusline.conf
The orchestrator does nothing but list the files in order. The two helper
scripts live in ~/dotfiles-macos/scripts/, which is on the Stow ignore list.
They are not linked into $HOME, and the bindings and the alias call them by
their repo path.
Configuring Options
options.conf sets session and input behavior.
# Configure general session and window behavior
set -g base-index 1
set -g renumber-windows on
set -g extended-keys on
set -g extended-keys-format csi-u
# Configure key and input behavior
set -g mode-keys vi
set -s escape-time 10
# Configure mouse and focus handling
set -g mouse off
set -g focus-events on
Windows start at 1 with base-index, not the default 0. renumber-windows
closes the gap when you kill a window, so your C-a <number> habit stays
accurate.
extended-keys needs a recent tmux, and extended-keys-format is a later
addition. With the csi-u format, terminal apps get distinct key events instead
of losing modifiers. The same keystroke that means Enter in one app and C-j in
another stays tellable. That matters since C-j, C-h, and friends do real
work in the bindings below, and is the reason the config requires a recent tmux.
On a bare tmux 3.8 I checked that extended-keys is off and the format is
xterm, so both lines change behavior.
escape-time is the milliseconds tmux waits to tell an Escape from the start of
an escape sequence. Ten is the value I want, and on a bare tmux 3.8 it is
already the default, so the line makes that explicit rather than lowering
anything. It’s the number Neovim users tend to land on. I keep it for the
editor, not for tmux.
mouse off and mode-keys vi set the tone. Everything in this config is
keyboard-driven. Panes are resized, selected, and copied entirely by key, so the
mouse is dead weight once it is off. On a bare tmux 3.8 here, mouse is on, so
this line is doing real work. mode-keys would also resolve to vi on this
machine because EDITOR is nvim, but I keep the line so it does not depend on
that.
focus-events forwards focus in and out to the pane. It is off by default.
Terminal apps like Neovim can then react to the terminal losing focus instead of
assuming the window is gone.
Configuring the Terminal
terminal.conf is about what the terminal underneath can actually do.
# Enable undercurl and terminal color support
set -su terminal-overrides
set -as terminal-overrides ',*:Smulx=\E[4::%p1%dm'
set -as terminal-overrides ',*:Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m'
set -g default-terminal "tmux-256color"
set -as terminal-overrides ',xterm-256color:RGB'
The Smulx and Setulc entries are the undercurl. Smulx is the styled
underline capability and Setulc supplies its color. Neovim renders diagnostics
with curly underlines, and these entries are how that capability gets described
to tmux.
set -su resets the override list to its default and set -as appends, so this
file builds the effective list in order, and order matters within it. This is
the one place in the whole config where ordering is a real dependency.
default-terminal "tmux-256color" is the TERM every app inside tmux sees. It is
also the default on tmux 3.8, so like escape-time this line is explicit rather
than corrective. The last override adds the RGB capability to xterm-256color
so tmux knows truecolor can pass through. Without it, colors can degrade to the
256-color palette.
This file exists so the editor renders correctly, not so tmux looks good. The
undercurls and truecolor are for the Neovim config that EDITOR points at.
Configuring Bindings
bindings.conf is where the muscle memory lives.
# Set prefix key
set -g prefix C-a
unbind C-b
bind-key C-a send-prefix
# Create window splits
unbind %
bind | split-window -h
unbind '"'
bind - split-window -v
# Reload configuration
bind r source-file ~/.config/tmux/tmux.conf
# Resize panes with prefix
bind j resize-pane -D 5
bind k resize-pane -U 5
bind l resize-pane -R 5
bind h resize-pane -L 5
bind m resize-pane -Z
# Prefix-based pane switching (use with prefix key, e.g. C-a C-h)
bind C-h select-pane -L
bind C-j select-pane -D
bind C-k select-pane -U
bind C-l select-pane -R
bind C-\\ select-pane -l
# Pass pane navigation keys to Neovim because vim-tmux-navigator needs tmux to hand them over
is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+/)?g?\\.?(view|l?n?vim?x?|fzf)(diff)?(-wrapped)?$'"
bind -n C-h if-shell "$is_vim" 'send-keys C-h' 'select-pane -L'
bind -n C-j if-shell "$is_vim" 'send-keys C-j' 'select-pane -D'
bind -n C-k if-shell "$is_vim" 'send-keys C-k' 'select-pane -U'
bind -n C-l if-shell "$is_vim" 'send-keys C-l' 'select-pane -R'
bind -n C-\\ if-shell "$is_vim" 'send-keys C-\\' 'select-pane -l'
# Configure copy mode bindings
bind -T copy-mode-vi C-h select-pane -L
bind -T copy-mode-vi C-j select-pane -D
bind -T copy-mode-vi C-k select-pane -U
bind -T copy-mode-vi C-l select-pane -R
bind -T copy-mode-vi C-\\ select-pane -l
# Launch pi
bind y run-shell "~/dotfiles-macos/scripts/pi-launcher.sh"
The prefix moves from C-b to C-a. C-b is a stretch. C-a sits under the
left hand. The cost is that a literal Ctrl-A in an app needs two presses, so
C-a C-a reaches readline’s move-to-line-start. I paid that cost years ago and
never went back.
Splits read like their shape. | goes vertical side-by-side and - stacks
horizontally, matching the character you press. These bindings split the pane
you are currently in, so the flow is split, work, split. The wrapper below is
where the main pane is targeted. It names the original main pane explicitly
when it builds the initial layout.
C-a r re-sources tmux.conf, which pulls all four files again. Editing
bindings.conf then reloading once is the entire edit loop. No server restart,
no plugin manager, no rehash.
Resize keys mirror Vim. j/k/l/h nudge panes in the obvious directions by
five cells, and m toggles zoom.
Pane Navigation and Neovim
Pane jumping has two layers. The prefix layer is C-a followed by
C-h/C-j/C-k/C-l, and C-a C-\ flips back to the last pane. The
copy-mode-vi table gets the same set, so navigation works whether you are at a
prompt or busy selecting text.
The second layer is the bind -n set, which needs no prefix at all. That is the
tmux half of vim-tmux-navigator, the plugin my Neovim config loads. The
is_vim check looks at the processes on the pane’s tty and matches vim,
nvim, view and fzf along with their variants. If the pane is running one
of them, tmux sends the key through and the plugin on the Neovim side decides
whether to move between splits or hand control back to tmux. If not, tmux
selects the pane itself. The result is one set of keys for moving around, no
matter whether the boundary is a Neovim split or a tmux pane.
Configuring the Status Line
statusline.conf keeps the chrome honest.
# Configure status line and window styling
set -g status-position top
set -g status-justify absolute-centre
set -g status-style "bg=default"
set -g window-status-current-style "fg=yellow bold"
set -g status-right ""
set -g status-left ""
The status line sits at the top, not the bottom. In the wrapper layout below,
the bottom of the main pane is given over to a scratch strip, so the top is
where the status line is allowed to live.
bg=default makes it transparent, which means it blends with the terminal
background instead of drawing a bar. The current window is bold yellow, and the
left and right sides carry no clock, no hostname, and no session name. The only
thing on screen is which window you are in.
The Wrapper Session
The tmux-s alias in .zshrc points at
~/dotfiles-macos/scripts/tmux-sessionaire.sh.
#!/usr/bin/env bash
set -euo pipefail
SESSION_NAME="${SESSION_NAME:-dev}"
WINDOW_NAME="${WINDOW_NAME:-main}"
command -v tmux &>/dev/null || {
printf '%s\n' 'Not found: tmux' >&2
exit 1
}
if ! tmux has-session -t "=$SESSION_NAME" 2>/dev/null; then
main_pane_id="$(tmux new-session -d -s "$SESSION_NAME" -n "$WINDOW_NAME" -P -F '#{pane_id}')"
tmux split-window -h -l 10% -t "$main_pane_id"
tmux split-window -v -l 10% -t "$main_pane_id"
tmux select-pane -t "$main_pane_id"
fi
if [[ -n "${TMUX:-}" ]]; then
tmux switch-client -t "=$SESSION_NAME"
else
exec tmux attach-session -t "=$SESSION_NAME"
fi
It is a bash script, not a tmux config hook, because it is multi-step and has to
run before tmux attaches. It runs under bash regardless of the interactive
shell.
On first run it creates a dev session with a main window and captures the
pane id straight from new-session. Then it splits off two thin panes from the
main pane, a 10% strip on the right and a 10% strip below it. The main pane
stays selected.
The = prefix on the session name makes tmux match it exactly. Without it, tmux
treats the target as a prefix match, so a session named dev-something could be
picked up by accident.
The layout is the point of the script. One big pane owns the work, the right
rail is a good place for something like a test runner or log stream, and the
bottom strip is a scratch shell. The script only builds the geometry. What you
put in the rails is your business.
If you are already inside tmux it switches to dev. Otherwise it attaches.
Session and window names are env-overridable, but I have never needed to change
them.
This lives behind the alias and nowhere else. Plain tmux keeps its default
behavior, so the opinionated layout only shows up when I ask for it.
C-a y runs pi-launcher.sh, which raises pi, the terminal coding agent I use,
in a popup over whatever I am doing. This is where tmux and pi meet.
#!/usr/bin/env bash
set -euo pipefail
pane_path="$(tmux display-message -p '#{pane_current_path}')"
path_hash="$(printf '%s' "$pane_path" | md5 -q | cut -c1-8)"
session="pi-$path_hash"
if ! tmux has-session -t "$session" 2>/dev/null; then
tmux new-session -d -s "$session" -c "$pane_path" pi
fi
tmux display-popup -w 80% -h 80% -E "tmux attach-session -t $session"
The trick is the session name. It hashes the current directory, so the session
is pi-<hash> keyed to where the pane is. First press in a directory creates a
detached session that starts pi there. Every later press in the same directory
attaches to the same session. pi keeps its state, the popup reappears over your
panes, and nothing is spawned into the working pane.
The hash uses macOS’s md5 -q and takes the first eight hex characters. That is
plenty for directory uniqueness in practice, and it is not portable to Linux,
where the command is md5sum. This script only has to work on this machine.
display-popup opens 80% wide and 80% tall, centered over everything. When I
close the popup the pi session stays alive in the background, detached. That is
a feature and a cost. State survives, but so does the session. They sit around
until killed by hand, one per directory that has ever spawned one.
Tradeoffs and Caveats
The prefix is C-a, and that costs you an app key. A literal Ctrl-A in a
shell or in readline takes two presses (C-a then C-a). The escape hatch is
firmly in place, but it is a thing you must get used to.
The no-prefix navigation keys are taken from every other program. Outside
Neovim, vim and fzf, C-l selects the pane to the right instead of clearing the
screen, and C-h, C-j and C-k stop reaching the shell as well. That is the
price of one set of keys for both Neovim splits and tmux panes.
Mouse is entirely off. No drag-selecting, no mouse wheel scrollback inside
panes, no click-to-focus. Keyboard only. That is a deliberate choice, and some
people will rightly hate it.
The wrapper is opinionated about layout. tmux-s always gives you the main
pane plus two thin rails. It is a workspace shape, not a terminal. When you want
a plain pane, plain tmux is still there, untouched.
The status line tells you almost nothing. No clock, no hostname, no session
name. The only glanceable data is the highlighted current window. Useful signals
were traded away for a quiet screen.
pi popups leave sessions behind. Every directory with a C-a y press owns a
detached session forever. They are cheap and invisible, but they accumulate, and
the cleanup is manual.
The pi launcher is macOS only. It calls md5 -q directly and has no
fallback. It also runs with set -e and no guards, so pressing the key
somewhere it cannot work simply does nothing visible.
This config assumes a recent tmux. extended-keys and
extended-keys-format are recent additions, and I do not guard either of them.
On an old distro tmux this config would error at startup, which is fine for my
machine and worth knowing before you copy it.
Where I Landed
The load order is this.
1. options
2. terminal
3. bindings
4. statusline
Nothing here reads a value that an earlier file wrote, except terminal.conf,
where the overrides have to build up in order. The same is mostly true of load
order in the shell post. Only a few lines are real dependencies, and everything
else would survive reordering.
I won’t pretend the split is required. tmux would load a single ~/.tmux.conf
with the same result, and at 77 lines you could read it all in one sitting. One
file is the reasonable default, and I have no argument against it for a config
that small.
I keep five files anyway, for three reasons that hold even at this size.
The first is diff scoping. A change to keys touches bindings.conf and nothing
else, so every commit and every git log entry names the concern that moved. That
stays useful no matter how small the config is.
The second is consistency with the rest of ~/dotfiles-macos. The Neovim config
and the shell config follow the same shape, small files, one concern each,
linked through stow. When the tmux files follow the same rule, the structure of
the whole environment is learnable once.
The third is that the split is nearly free. Reloading re-parses all five files
in a blink, and the orchestrator is five obvious lines, so the cost is the tiny
mental jump from one file to another. I would merge the files back if the
equation ever flips. If the config shrank further or I stopped editing keys, the
extra structure might no longer be worth it. So far, the seams keep paying.
This is small enough to understand, structured enough that I know where to edit
it, and opinionated enough to make my workflow comfortable.
That’s really the point of the configuration. The five files aren’t necessary,
but each concern has a predictable home, and that makes the whole thing easier
for me to change without having to think about where something lives.
Related Posts