tmux sessions are more than just windows and panes; they’re independent environments that can be detached and reattached, and giving them names is a game-changer for managing complex workflows.
Let’s see this in action. Imagine you’re working on three distinct projects: website, api, and docs.
First, start a new tmux session for your website project:
tmux new-session -s website
Inside this session, you can create windows for different tasks. For instance, one window for your frontend development, another for your backend, and a third for running tests.
# Inside the 'website' session
tmux new-window -t website:1 -n 'frontend'
tmux new-window -t website:2 -n 'backend'
tmux new-window -t website:3 -n 'tests'
Now, detach from this session:
tmux detach-client
You can then start a new session for your api project:
tmux new-session -s api
And set up its windows:
# Inside the 'api' session
tmux new-window -t api:0 -n 'api-dev'
tmux new-window -t api:1 -n 'logs'
Detach again:
tmux detach-client
Finally, start a session for docs:
tmux new-session -s docs
With its windows:
# Inside the 'docs' session
tmux new-window -t docs:0 -n 'editor'
tmux new-window -t docs:1 -n 'preview'
Now, your tmux server is running multiple, independent environments, each neatly organized by project name. To switch between them, you don’t have to remember cryptic session numbers. Instead, you list your sessions and reattach by name:
List all running sessions:
tmux ls
You’ll see output like:
api: 2 windows (created Mon Oct 23 10:00:00 2023) [80x24]
docs: 2 windows (created Mon Oct 23 10:05:00 2023) [80x24]
website: 3 windows (created Mon Oct 23 09:55:00 2023) [80x24]
Reattach to the website session:
tmux attach-session -t website
Or, if you’re already inside a tmux session and want to switch to another, you can use the prefix key (default Ctrl+b) followed by s to see a list and select, or directly use : to enter command mode and type switch-client -t api.
The core problem named sessions solve is context switching overhead. Without names, tmux sessions are numbered sequentially (0, 1, 2…). If you detach from session 1 and then create a new one, it becomes session 2, pushing your original session 1 to session 2, and so on. This numerical churn makes it hard to reliably reattach to a specific project’s environment. Naming sessions creates stable, human-readable identifiers that persist across reboots (if tmux is configured to save sessions) and detach/attach cycles. It allows you to think about your tmux environment in terms of "the api project" rather than "session number 3."
Internally, tmux maintains a server process that manages all active sessions. Each session is a distinct entity with its own set of windows and panes. When you name a session with -s, you’re essentially assigning a unique tag to that session object within the tmux server’s management table. This tag is then used by the client to locate and interact with the correct session. The new-session command creates a session and registers it under the given name. attach-session and detach-client use these names to find the desired session object.
The actual configuration for session management, like auto-saving and auto-reloading, lives in your ~/.tmux.conf. For instance, you can add these lines to have tmux automatically save sessions on exit and restore them on startup:
set -g session-save-name on
set -g session-restore-environment on
set -g session-restore-keys on
This means if you start tmux, create named sessions, and then exit tmux (not just detach), the next time you run tmux, it will attempt to restore those same named sessions.
A subtle but powerful aspect of named sessions is their integration with scripting and automation. You can write shell scripts that create, attach to, or send commands to specific named sessions, enabling reproducible development environments. For example, a script could start your website session, create all its necessary windows, and even run initial commands like npm install or git pull within them, all using commands like tmux send-keys -t website:frontend 'npm start' C-m.
The next logical step after mastering named sessions is to explore session multiplexing and team collaboration features within tmux.