Sessions: Create, Attach, Detach, Repeat
What a Session Is
A tmux session is a container. Inside it are windows. Inside each window are panes. Inside each pane is a shell (or any program).
A session lives on the tmux server, which is a long-running background process on your machine. Sessions outlive your terminal. They do not outlive reboots, and they do not follow you across machines (unless you set up sharing, covered in chapter 11).
You can have as many sessions as you want. Most people keep one per project.
Creating Sessions
From the shell:
tmux # new unnamed session, attached
tmux new # same thing
tmux new -s work # new session named "work", attached
tmux new -s work -d # new session named "work", detached
tmux new -s work -c ~/code # start in ~/code
-d is useful when you want the session running but don't want to switch to it yet. Scripting uses it heavily (chapter 9).
From inside tmux:
<prefix> :new -s reading
Drops you into the command prompt with :new prefilled, lets you finish it. More on the command prompt in chapter 6.
Naming sessions
Always name sessions you'll keep around:
tmux new -s dotfiles
tmux new -s api
tmux new -s reading
Numeric IDs are fine for one-offs. Named sessions are much easier to reattach to:
tmux a -t api
Beats remembering "was it session 2 or session 3?".
Listing Sessions
tmux ls # from the shell
tmux list-sessions # same
Output:
api: 3 windows (created Sun Apr 20 09:12:00 2026)
dotfiles: 1 windows (created Sat Apr 19 18:34:21 2026)
reading: 2 windows (created Sun Apr 20 10:01:44 2026) (attached)
(attached) marks sessions you're currently viewing in some terminal. A session can have multiple clients attached simultaneously.
From inside tmux:
<prefix> s
An interactive session list appears. Use j/k to navigate, Enter to switch. q or Esc to exit.
Attaching and Detaching
tmux attach # most recent session
tmux a # short for attach
tmux a -t work # specific session
tmux a -t w # prefix match works. "w" matches "work"
Detach from inside tmux:
<prefix> d # detach this client
<prefix> D # choose which client to detach (useful for multi-attach)
Attach to a session that doesn't exist yet, creating it if needed:
tmux new -A -s work # attach if "work" exists, create it if not
That -A flag is gold. Put it in a shell alias and you never need to remember whether a session already exists:
alias t='tmux new -A -s'
t work # attach or create
t dotfiles # attach or create
Renaming
From inside a session:
<prefix> $ # rename the current session
A prompt appears at the bottom. Type the new name. Enter.
From the shell:
tmux rename-session -t old new
Switching Sessions
From inside tmux:
<prefix> s # interactive session picker
<prefix> ( # previous session
<prefix> ) # next session
<prefix> L # the last session you were in
For everyday use, rebind something shorter (chapter 7). <prefix> s is most people's default.
Targeting by name
Any time tmux asks for a target, you can pass a partial name:
tmux a -t ap # matches "api"
tmux kill-session -t read # matches "reading"
Ambiguous? tmux complains:
more than one session matches
Use more characters until it's unique.
Killing Sessions
tmux kill-session -t work # kill specific session
tmux kill-session # kill the attached session
tmux kill-server # nuke everything
From inside a session:
<prefix> :kill-session
When you kill a session, every pane inside it is killed, which means every running process gets SIGHUP. Long-running commands die. If you wanted to preserve work, detach and kill something else.
The "kill all but this" pattern
tmux kill-session -a # kill all sessions except the current one
tmux kill-session -a -t work # kill all sessions except "work"
Useful Friday afternoon: kill everything except the one session you want on Monday.
The Attached vs Detached Distinction
This is the one mental model to lock in:
- A session exists whether or not a terminal is attached to it
- Attaching just shows the session in your terminal
- Detaching just hides it; the session lives on
Once this clicks, you stop being afraid of closing terminals. Your shells don't die. They wait.
A Session Per Project
Common pattern: one session per active project, named after the project. Combined with the -A flag:
alias t='tmux new -A -s'
cd ~/code/api
t api
Now every time you open a terminal and run t api, you end up in the same session you had yesterday. Opening a second terminal and running t api gives you a second client on the same session: you see the same cursor moving in both windows. Useful for pair work or for watching a long build from a second monitor.
Sharing a Session Across Terminals
Two terminals, same session:
# terminal A
tmux new -s shared
# terminal B
tmux a -t shared
Both terminals now show the same panes. Useful for pair programming over a shared SSH server. Covered more in chapter 11.
Session Groups (Advanced)
A tmux feature most users never touch: two sessions can share a set of windows but have independent cursors:
tmux new -s work
tmux new -s work-secondary -t work # linked to work's windows
Now work and work-secondary share windows but can be on different windows at the same time. Niche. Mentioned for completeness.
Common Pitfalls
"I typed exit in the last pane and my session died." Expected. Exiting every shell ends the session. Use <prefix> d to leave a session running.
"I detached, and now tmux ls shows nothing." The server quits when the last session ends. If you killed all panes in the only session instead of detaching, everything is gone. Use <prefix> d to detach, not exit.
"I have twenty sessions and can't remember which is which." You probably stopped naming them. tmux ls and some kill-session calls get you back to a clean state. Then adopt a naming convention.
"tmux a puts me in the wrong session." It attaches to the most recent one. Use -t name to be specific.
"I want tmux to start automatically in every new terminal." Add to ~/.bashrc or ~/.zshrc:
if [ -z "$TMUX" ]; then
tmux new -A -s main
fi
Starts or reattaches to a session named "main" whenever you open a shell. Some people love it; some find it annoying when they want a plain shell. Your call.
Next Steps
Continue to 03-windows.md to learn about windows, the second layer of tmux's hierarchy.