tmux Session Management: Complete Guide

Understanding the tmux Hierarchy

tmux organizes your terminal work in a three-level hierarchy: Sessions, Windows, and Panes. Understanding this structure is key to using tmux effectively.

text

Server
  |
  +-- Session: "project-a"
  |     |
  |     +-- Window 0: "editor"
  |     |     |
  |     |     +-- Pane 0: vim
  |     |     +-- Pane 1: terminal
  |     |
  |     +-- Window 1: "server"
  |     |     |
  |     |     +-- Pane 0: npm run dev
  |     |
  |     +-- Window 2: "logs"
  |           |
  |           +-- Pane 0: tail -f app.log
  |
  +-- Session: "project-b"
        |
        +-- Window 0: "code"
        |     |
        |     +-- Pane 0: vim
        |
        +-- Window 1: "tests"
              |
              +-- Pane 0: pytest --watch

A session is a collection of windows managed by tmux. Each session is an independent workspace that persists in the background, even when you are not connected to it. Sessions are the most important organizational unit because they represent entire project contexts. You can have one session per project, switch between them instantly, and each maintains its own set of windows, panes, working directories, and running processes.

A window is a single screen within a session, similar to a tab in a modern terminal emulator. Each window occupies the full terminal area and can be split into multiple panes.

A pane is a subdivision of a window. Panes allow you to view multiple terminals side by side within the same window.

Creating Sessions

There are several ways to create new tmux sessions, each suited for different workflows.

bash

# Start a new unnamed session (automatically numbered 0, 1, 2...)
tmux

# Create a named session (recommended)
tmux new -s project

# Create a named session in detached mode (runs in background)
tmux new -s project -d

# Create a session with a specific starting directory
tmux new -s project -c ~/code/project

# Create a session and name the first window
tmux new -s project -n editor

# Combine options: named session, starting directory, and window name
tmux new -s myapp -c ~/code/myapp -n code

Always name your sessions with tmux new -s name. Unnamed sessions get numeric IDs (0, 1, 2...) which are hard to remember and manage. Use short, meaningful names that identify the project or task, such as api, frontend, or dotfiles.

Listing and Selecting Sessions

When you have multiple sessions running, you need to list and switch between them.

bash

# List all active sessions from the command line
tmux ls

# Long form of the same command
tmux list-sessions

# Example output:
# api: 3 windows (created Sat Feb 22 10:30:00 2026)
# frontend: 2 windows (created Sat Feb 22 11:00:00 2026) (attached)
# docs: 1 windows (created Sat Feb 22 14:15:00 2026)

From inside tmux, you can use the interactive session picker with prefix + s. This shows a navigable list of all sessions with a preview of each session's windows and panes. Use the arrow keys to browse and Enter to switch.

bash

# Switch to a specific session by name (from inside tmux)
tmux switch-client -t api

# Switch to the previous session
# prefix + (

# Switch to the next session
# prefix + )

Attach and Detach

Attaching and detaching is the core mechanism that makes tmux sessions persistent. When you detach from a session, it continues running in the background. When you attach, you reconnect to it exactly where you left off.

bash

# Detach from the current session (keyboard shortcut)
# prefix + d

# Attach to the most recently used session
tmux attach
tmux a          # short alias

# Attach to a specific named session
tmux attach -t project

# Create a new session or attach if it already exists (best practice)
tmux new -A -s project

# Attach to a session and detach all other clients from it
tmux attach -d -t project

Recommended: The create-or-attach pattern

The tmux new -A -s name command is the most practical way to work with sessions. If the session exists, it attaches to it. If not, it creates a new one. This means you can always run the same command without worrying about whether the session already exists.

bash

# Add this to your shell aliases for quick access
alias ta='tmux new -A -s'

# Usage: just type the session name
ta project    # Creates "project" session or attaches to it
ta api        # Creates "api" session or attaches to it

Session Persistence

Session persistence is the killer feature of tmux, especially for remote work. tmux sessions survive SSH disconnects, terminal window closures, and accidental exits. Your processes keep running and your workspace remains exactly as you left it.

Here is a typical remote work workflow that demonstrates why session persistence is so valuable:

bash

# Step 1: SSH into the remote server
ssh user@server.example.com

# Step 2: Start or attach to your tmux session
tmux new -A -s work

# Step 3: Work normally - edit files, run builds, tail logs
vim src/app.py
# ... hours of productive work ...

# Step 4: Your WiFi drops, or you close your laptop
# (connection is lost - but tmux session keeps running!)

# Step 5: Later, reconnect via SSH
ssh user@server.example.com

# Step 6: Reattach to your session - everything is exactly as you left it
tmux attach -t work
# Your vim session is still open, your builds are still running,
# your log tailing is still going

This workflow is invaluable for long-running processes on remote servers. Database migrations, large compilation jobs, training ML models, or monitoring logs -- all continue running safely inside tmux regardless of your network connection status.

Important limitation

tmux sessions persist as long as the tmux server process is running. They will be lost if the server is rebooted or the tmux server is killed. For persistence across reboots, use plugins like tmux-resurrect or tmux-continuum (see Best Practices below).

Renaming and Managing Sessions

As your workflow evolves, you may need to rename, reorganize, or clean up sessions.

bash

# Rename the current session (keyboard shortcut)
# prefix + $

# Rename a session from the command line
tmux rename-session -t old-name new-name

# Kill a specific session
tmux kill-session -t project

# Kill all sessions except the current one
tmux kill-session -a

# Kill all sessions except a specific one
tmux kill-session -a -t main

# Kill the entire tmux server (all sessions, windows, panes)
tmux kill-server

Use tmux kill-session -t name to cleanly remove sessions you no longer need. This is preferable to killing individual panes or windows because it ensures all associated processes are properly terminated.

Session Scripting

One of the most powerful features of tmux is the ability to automate session setup with shell scripts. Instead of manually creating windows and panes each time, write a script that builds your entire development environment in one command.

bash

#!/bin/bash
# dev-session.sh - Automated development environment setup

SESSION="dev"

# Check if session already exists
tmux has-session -t $SESSION 2>/dev/null

if [ $? -eq 0 ]; then
    echo "Session '$SESSION' already exists. Attaching..."
    tmux attach -t $SESSION
    exit 0
fi

# Create a new detached session with the first window named "editor"
tmux new-session -d -s $SESSION -n editor

# Open the editor in the first window
tmux send-keys -t $SESSION:editor "vim ." Enter

# Create a second window for general terminal use
tmux new-window -t $SESSION -n terminal

# Create a third window for watching logs
tmux new-window -t $SESSION -n logs
tmux send-keys -t $SESSION:logs "tail -f /var/log/app.log" Enter

# Select the editor window as the active window
tmux select-window -t $SESSION:editor

# Attach to the session
tmux attach -t $SESSION

Here is a more advanced script that creates a web development workspace with split panes:

bash

#!/bin/bash
# web-dev.sh - Full-stack web development workspace

SESSION="webapp"
PROJECT_DIR="$HOME/code/webapp"

tmux has-session -t $SESSION 2>/dev/null
if [ $? -eq 0 ]; then
    tmux attach -t $SESSION
    exit 0
fi

# Window 1: Code editing
tmux new-session -d -s $SESSION -n code -c $PROJECT_DIR
tmux send-keys -t $SESSION:code "vim ." Enter

# Window 2: Servers (split into two panes)
tmux new-window -t $SESSION -n servers -c $PROJECT_DIR
tmux send-keys -t $SESSION:servers "npm run dev" Enter
tmux split-window -h -t $SESSION:servers -c $PROJECT_DIR
tmux send-keys -t $SESSION:servers "npm run api" Enter

# Window 3: Testing
tmux new-window -t $SESSION -n tests -c $PROJECT_DIR
tmux send-keys -t $SESSION:tests "npm test -- --watch" Enter

# Window 4: Git and general terminal
tmux new-window -t $SESSION -n git -c $PROJECT_DIR
tmux send-keys -t $SESSION:git "git status" Enter

# Start on the code window
tmux select-window -t $SESSION:code
tmux attach -t $SESSION

Save these scripts somewhere in your PATH (e.g., ~/.local/bin/) and make them executable with chmod +x. You can then launch your entire workspace with a single command.

Best Practices

Name sessions by project

Use meaningful session names that correspond to your projects or tasks. Names like api, frontend, docs, or infra are immediately recognizable when switching sessions. Avoid generic names or relying on numeric IDs.

Use the `tmux new -A -s` pattern

Always use tmux new -A -s name instead of separate new/attach commands. This idempotent approach means the same command works whether the session exists or not, making it perfect for shell aliases and scripts.

Organize windows by task type

Within each session, create dedicated windows for different activities: one for editing code, one for running servers, one for tests, and one for git operations. This keeps your workspace organized and lets you switch contexts quickly with prefix + number.

Use tmux-resurrect for reboot persistence

By default, tmux sessions are lost when the server reboots. Install tmux-resurrect to save and restore session state including window layouts, pane arrangements, and working directories. Pair it with tmux-continuum for automatic saving and restoring.

bash

# With TPM (Tmux Plugin Manager) in your ~/.tmux.conf:
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

# Enable auto-restore
set -g @continuum-restore 'on'

# Manual save: prefix + Ctrl-s
# Manual restore: prefix + Ctrl-r

Clean up idle sessions

Periodically review your running sessions with tmux ls and kill any that you no longer need. Too many sessions can consume system resources and make session switching confusing. Use tmux kill-session -t name to remove individual sessions.

tmux Session Management: Complete Guide

Understanding the tmux Hierarchy

Creating Sessions

Listing and Selecting Sessions

Attach and Detach

Recommended: The create-or-attach pattern

Session Persistence

Important limitation

Renaming and Managing Sessions

Session Scripting

Best Practices

Name sessions by project

Use the `tmux new -A -s` pattern

Organize windows by task type

Use tmux-resurrect for reboot persistence

Clean up idle sessions

Official Documentation

Related Articles

tmux - Terminal Multiplexer

tmux Cheat Sheet: All Key Bindings & Commands

tmux Split Window & Pane Management Guide

tmux Plugins Guide: TPM, Resurrect, Continuum & More

Understanding the tmux Hierarchy

Creating Sessions

Listing and Selecting Sessions

Attach and Detach

Recommended: The create-or-attach pattern

Session Persistence

Important limitation

Renaming and Managing Sessions

Session Scripting

Best Practices

Name sessions by project

Use the tmux new -A -s pattern

Organize windows by task type

Use tmux-resurrect for reboot persistence

Clean up idle sessions

Official Documentation

Related Articles

tmux - Terminal Multiplexer

tmux Cheat Sheet: All Key Bindings & Commands

tmux Split Window & Pane Management Guide

tmux Plugins Guide: TPM, Resurrect, Continuum & More

Use the `tmux new -A -s` pattern