Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tmux/tmux/llms.txt

Use this file to discover all available pages before exploring further.

​
Your First tmux Session

Let’s get you productive with tmux quickly. This guide covers the essential concepts and commands you’ll use daily.
1

Start tmux

Open your terminal and start your first tmux session:
tmux
You’ll see a new shell prompt with a green status bar at the bottom showing:
  • [0] - session name
  • 0:bash* - window number and name
  • Your hostname and time on the right
2

Understand the prefix key

All tmux commands start with a prefix key: C-b (Ctrl-b)
Press Ctrl and b together, release both keys, then press the command key. For example, C-b c means: press Ctrl-b, release, then press c.
The prefix key tells tmux: “I’m about to give you a command, not the shell.”
3

Create a new window

Press C-b c to create a new window.Notice the status bar now shows:
[0] 0:bash- 1:bash*
The * indicates your current window. The - marks the previous window.
4

Navigate between windows

Try these navigation commands:
  • C-b n - next window
  • C-b p - previous window
  • C-b 0 - switch to window 0
  • C-b 1 - switch to window 1
  • C-b l - toggle between current and last window
5

Split into panes

Now let’s split a window into multiple panes:
  • C-b % - split vertically (left and right)
  • C-b " - split horizontally (top and bottom)
Each pane is an independent terminal.
6

Navigate between panes

Move between panes:
  • C-b o - cycle to next pane
  • C-b ↑ - move to pane above
  • C-b ↓ - move to pane below
  • C-b ← - move to pane on left
  • C-b → - move to pane on right
  • C-b ; - move to previously active pane
7

Detach from session

Press C-b d to detach from the session.You’ll see a message:
[detached (from session 0)]
Your session is still running in the background! All your windows and panes are preserved.
8

Reattach to session

Return to your session with:
tmux attach
Everything is exactly as you left it.

​
Essential Commands Reference

# Default session (numbered)
tmux

# Named session
tmux new -s mysession

# Named session with window name
tmux new -s mysession -n mywindow
Key BindingAction
C-b cCreate new window
C-b ,Rename current window
C-b &Kill current window (with confirmation)
C-b nNext window
C-b pPrevious window
C-b 0-9Switch to window by number
C-b lSwitch to last active window
C-b wInteractive window list
C-b fFind window by name
C-b .Move window to different index
Key BindingAction
C-b %Split pane vertically
C-b "Split pane horizontally
C-b xKill current pane (with confirmation)
C-b oMove to next pane
C-b ;Move to previously active pane
C-b ↑↓←→Move to pane in direction
C-b {Swap with previous pane
C-b }Swap with next pane
C-b zToggle pane zoom (fullscreen)
C-b !Break pane into new window
C-b qShow pane numbers
Key BindingAction
C-b C-↑Resize pane up by 1 cell
C-b C-↓Resize pane down by 1 cell
C-b C-←Resize pane left by 1 cell
C-b C-→Resize pane right by 1 cell
C-b M-↑Resize pane up by 5 cells
C-b M-↓Resize pane down by 5 cells
C-b M-←Resize pane left by 5 cells
C-b M-→Resize pane right by 5 cells
C-b M-1 to M-7Apply preset layouts
C-b SpaceCycle through preset layouts
1

Enter copy mode

Press C-b [ to enter copy mode and scroll through history.You’ll see [0/0] in the top-right corner showing your position in history.
2

Navigate in copy mode

Emacs mode (default):
  • Arrow keys - move cursor
  • C-Space - begin selection
  • M-w - copy selection
  • C-g - exit copy mode
Vi mode (if set -g mode-keys vi in config):
  • h/j/k/l - move cursor
  • Space - begin selection
  • Enter - copy selection
  • q - exit copy mode
3

Paste

Press C-b ] to paste the most recently copied text.
Use Page Up as a shortcut to enter copy mode and scroll up one page immediately.
Key BindingAction
C-b ?List all key bindings
C-b :Enter command prompt
C-b tShow clock
C-b iDisplay window information
C-b ~Show previous messages
C-b dDetach from session
C-b DChoose client to detach
C-b rRedraw screen
C-b C-bSend literal C-b to application

​
Practical Workflow Example

Here’s a common development workflow:
1

Create a development session

tmux new -s dev
2

Set up your layout

  • Start in your project directory
  • Press C-b % to split vertically
  • In the right pane, press C-b " to split horizontally
You now have three panes:
┌─────────┬─────────┐
│         │         │
│  Code   │  Tests  │
│         ├─────────┤
│         │  Logs   │
└─────────┴─────────┘
3

Run your development tools

  • Left pane: Open your editor (vim, nano, etc.)
  • Top-right pane: Run your test watcher
  • Bottom-right pane: Tail your application logs
4

Detach when done

Press C-b d to detach. Your session keeps running.
5

Return later

tmux attach -t dev
Everything is still running!

​
Remote Development Workflow

One of tmux’s most powerful features is persistence over SSH:
1

SSH to remote server

ssh user@remote-server
2

Start or attach to tmux

# First time: create session
tmux new -s work

# Later: reattach to existing session
tmux attach -t work
3

Do your work

Start long-running builds, tests, or processes.
4

Disconnect safely

Press C-b d to detach, then exit SSH:
exit
Your tmux session keeps running on the server!
5

Reconnect anytime

ssh user@remote-server
tmux attach -t work
Pick up exactly where you left off.
If your SSH connection drops unexpectedly, tmux automatically detaches. Your session and all running processes continue uninterrupted.

​
Basic Configuration

Create ~/.tmux.conf to customize tmux: 
# Change prefix from C-b to C-a (like screen)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Increase scrollback buffer
set -g history-limit 10000

# Start window numbering at 1 instead of 0
set -g base-index 1
set -g pane-base-index 1

# Renumber windows when one is closed
set -g renumber-windows on

# Improve colors
set -g default-terminal "tmux-256color"

# Split panes using | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

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

# Vi mode for copy
set -g mode-keys vi
After creating or editing the config: 
# Load configuration in running session
C-b : source-file ~/.tmux.conf

# Or restart tmux
tmux kill-server
tmux

​
Common Patterns

# Create session with specific layout
tmux new-session -d -s myproject -n editor
tmux send-keys -t myproject:editor 'cd ~/myproject && vim' C-m

tmux new-window -t myproject -n tests
tmux send-keys -t myproject:tests 'cd ~/myproject && npm test' C-m

tmux new-window -t myproject -n server  
tmux send-keys -t myproject:server 'cd ~/myproject && npm start' C-m

# Attach to the session
tmux attach -t myproject

# From shell: create session with splits
tmux new-session -d -s dev 'vim'
tmux split-window -h -t dev 'npm test'
tmux split-window -v -t dev 'npm start'
tmux attach -t dev

# User 1: Create named session
tmux new -s pair

# User 2: Attach to same session
tmux attach -t pair
Both users need access to the same server and tmux socket. This is useful for pair programming or collaborative debugging.

​
Troubleshooting

Add to your shell configuration (.bashrc, .zshrc):
export TERM=xterm-256color
And in ~/.tmux.conf:
set -g default-terminal "tmux-256color"
Enable mouse support in ~/.tmux.conf:
set -g mouse on
Then reload config: C-b : source-file ~/.tmux.conf
# List sessions
tmux ls

# Attach to last session
tmux attach

# Attach to specific session
tmux attach -t session-name

# Kill all tmux sessions and server
tmux kill-server

# Start new session
tmux

​
Next Steps

Key Bindings

Press C-b ? inside tmux to see all default key bindings, or explore customization options.

Configuration

Learn advanced configuration options in ~/.tmux.conf including status bar customization, custom key bindings, and hooks.

Command Reference

Read the manual page (man tmux) for complete command documentation and options.

Community Resources

Join the tmux community at https://github.com/tmux/tmux for plugins, themes, and support.
The quickest way to learn is to practice! Try using tmux for your next project and the key bindings will become second nature.

Build docs developers (and LLMs) love

Get started for freeTalk to us