Skip to content
KLKlema Labs
All guides
Guide

The tmux field guide

tmux is a free terminal tool that keeps your work running in the background and splits one window into several. Every shortcut starts the same way: press Ctrl+b, let go, then press one more key.

Updated

Practice here first.

Press a button and watch the screen change. With a keyboard, click the screen and use the real keys.

app1:code2:git

Two panes are open in the tab named code.

The violet outline shows which pane you are typing in.

The idea

Three levels, one inside the next.

Once you can see these, every shortcut below makes sense.

Session: app

Tab 1: code

pane
code
pane
server

Tab 2: git

pane
git
Session
One whole project. It keeps running in the background when you close the terminal app.
Tab
tmux calls it a window. A full screen inside the session. The names along the bottom bar are your tabs.
Pane
One terminal. A tab can hold one pane or several side by side.

On the bottom bar, the violet block is the session you are in, the highlighted name is the tab you are on, and the right side is the date and time.

Panes

Two or more terminals in one tab. Use them to watch two things at once, like your code on the left and the server log on the right.

  • Split left and right

    Stock tmux uses the % key.

    Uses the settings below
    Ctrl+bthen|

  • Split top and bottom

    Stock tmux uses the " key.

    Uses the settings below
    Ctrl+bthen-

  • Move to another pane

    h is left, j is down, k is up, l is right. The arrow keys work in stock tmux, and so does a click once the mouse is on.

    Uses the settings below
    Ctrl+bthenhjkl

  • Make one pane fill the screen

    The same keys bring the others back.

    Ctrl+bthenz

  • Resize a pane

    Or drag the dividing line with the mouse.

    Ctrl+bthenholdCtrland tap anarrow

  • Show a number on each pane

    Press the number while it shows to jump there.

    Ctrl+bthenq

  • Swap this pane with its neighbor

    Ctrl+bthen}or{

  • Try the next ready-made layout

    Even columns, even rows, one big and the rest small.

    Ctrl+bthenSpace

  • Move this pane into its own tab

    Ctrl+bthen!

  • Close a pane

    tmux asks first. Press y to confirm.

    exitorCtrl+bthenx

Tabs

tmux calls them windows. Each one is a full screen inside the session. Open a new one for a separate job, like git.

  • New tab

    Ctrl+bthenc

  • Next tab, previous tab

    Ctrl+bthennorp

  • Jump to a tab by its number

    Stock tmux counts from 0. The settings below start at 1 to match the keyboard.

    Ctrl+bthen1to9

  • Rename this tab

    Ctrl+bthen,

  • See every session and tab in a list

    Arrow to one, press Enter to go there.

    Ctrl+bthenw

  • Find a tab by name

    Ctrl+bthenf

  • Close a tab and everything in it

    Press y to confirm.

    Ctrl+bthen&

Sessions

One session per project. A session keeps working after you step out of it, which is the main reason to use tmux at all.

  • Step out and leave it running

    This is called detaching. Your server and anything else in the session keep going.

    Ctrl+bthend

  • Switch to another session

    Ctrl+bthens

  • Next session, previous session

    Ctrl+bthen)or(

  • Rename this session

    Ctrl+bthen$

  • Start a new named session

    tmux new -s app

  • List the sessions that are running

    tmux ls

  • Go back into a session

    tmux attach -t app

  • End a session for good

    tmux kill-session -t app

Scrolling and copying

Each pane keeps its own history. The settings below raise it to 50,000 lines and turn the mouse on.

  • Scroll up through old output

    With the mouse on, the trackpad or wheel does it. Press q to drop back to the bottom.

    scroll

  • Scroll with the keyboard

    Then use the arrows or Page Up. Press q to leave.

    Ctrl+bthen[

  • Search the old output

    While scrolled back. If your editor is set to vi, the keys are ? and / in its place.

    Ctrl+rsearches up,Ctrl+sdown

  • Copy text inside tmux

    Drag across it with the mouse on. It copies when you let go.

    dragthen paste withCtrl+bthen]

  • Copy text the normal Mac way

    Hold fn in Apple Terminal, or Option in iTerm2, while you drag.

    fnorOptionthenCmd+C

Help and extras

The handful of keys that make the rest easier to find.

  • List every shortcut tmux has

    Press q to close the list.

    Ctrl+bthen?

  • Type a tmux command by name

    Ctrl+bthen:

  • Type into every pane at once

    Enter it after Ctrl+b then the colon key. Use off to stop.

    setw synchronize-panes on

  • Reload the settings after editing them

    Uses the settings below
    Ctrl+bthenr

  • Show a big clock in the pane

    Ctrl+bthent

If something feels stuck

Almost every tmux scare is one of these five.

  • Typing does nothing

    A counter like [12/340] in the top right corner means you are scrolled back.

    q

  • One pane fills the screen and the rest are gone

    It is zoomed.

    Ctrl+bthenz

  • You closed the terminal app by mistake

    Nothing is lost. Open it again and go back in.

    tmux attach

  • You pressed Ctrl+b and changed your mind

    Esc

  • You restarted the computer

    A restart does end every session. Start the session again.

    tmux new -s app
Settings

The settings behind this guide.

Stock tmux works without any of this. These lines make the splits easier to remember, turn the mouse on, and dress the bottom bar.

  1. Install tmux. On a Mac with Homebrew: brew install tmux
  2. Save the file. Put these lines in a file named .tmux.conf in your home folder.
  3. Start a session. tmux new -s app
~/.tmux.conf
# ~/.tmux.conf
# Reload after edits: Ctrl+b then r

# Mouse: click panes, drag borders, scroll with the trackpad
set -g mouse on

# Colors and a long scrollback
set -g default-terminal "tmux-256color"
set -g history-limit 50000

# Tabs and panes count from 1, like the keyboard row
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

# Easier splits, opening in the folder you are already in
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
bind c new-window -c "#{pane_current_path}"

# Move between panes with h j k l
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Reload this file
bind r source-file ~/.tmux.conf \; display-message "tmux config reloaded"

# Status bar: session on the left, tabs, time on the right
set -g status-style "bg=#141424,fg=#e0e0e0"
set -g status-left-length 30
set -g status-left "#[bg=#7c3aed,fg=#ffffff,bold]  #S  #[default] "
set -g status-right "#[fg=#c4b5fd]%a %b %d  %I:%M %p "
setw -g window-status-current-style "bg=#c4b5fd,fg=#0b0b14,bold"
setw -g window-status-current-format " #I:#W "
setw -g window-status-format " #I:#W "
set -g pane-active-border-style "fg=#a78bfa"

# No delay after Esc
set -sg escape-time 10

Checked on tmux 3.7 on macOS.

In practice

How we run a build in it.

Every project at Klema Labs lives in its own tmux session, laid out the same way.

  • One session per project, named after the project.

    Switching projects is switching sessions. Nothing from one build leaks into another.

  • The first tab is split: code on the left, the server on the right.

    The server log is always in view, so an error shows up the moment it happens.

  • A second tab is kept for git.

    Commits and pushes happen away from the running server, in the same session.

  • Sessions are left running between sittings.

    Closing the terminal app does not stop the server. Going back in puts every pane where it was.

Have software you want built?

We design and ship custom platforms, portals and internal tools on fixed-price milestones. You own the code.

Start a projectSee our work