Sessions

Understanding tmux sessions and the client-server architecture

Overview

A session in tmux is a single collection of pseudo terminals under the management of the tmux server. Sessions are the highest-level organizational unit in tmux and provide the foundation for tmux’s persistence model.

Each session is persistent and will survive accidental disconnection (such as SSH connection timeout) or intentional detaching.

Client-Server Architecture

Tmux operates using a client-server model where:

• Server: A single server process manages all sessions
• Clients: Multiple clients can connect to the server and attach to sessions
• Socket: The server and clients communicate through a socket in /tmp

Any number of tmux instances may connect to the same session, and any number of windows may be present in the same session. Once all sessions are killed, tmux exits.

# Start a new session
$ tmux new-session

# Reattach to an existing session
$ tmux attach

# List all sessions
$ tmux list-sessions

Session Lifecycle

Creating Sessions

From session.c:109-158, when a session is created:

1. A unique session ID is assigned (prefixed with $)
2. The session is added to the global sessions tree
3. Creation time and activity time are recorded
4. A session working directory is set

# Create a named session
$ tmux new-session -s my-session

# Create session with specific window name
$ tmux new-session -s dev -n editor

Session Identification

Sessions can be identified by:

• Session ID: Prefixed with $ (e.g., $0, $1)
• Session name: Exact name or glob pattern
• Prefix match: Partial name matching the start of a session name

From the man page (tmux.1:753-770):

Session by ID

$ tmux attach -t \$0

Detaching and Attaching

The key feature of sessions is their persistence:

# Detach from current session (within tmux)
Prefix d

# Or use command
$ tmux detach-client

# List available sessions
$ tmux list-sessions

# Attach to most recent session
$ tmux attach

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

From session.c:196-230, when a session is destroyed:

1. All windows are unlinked from the session
2. The session is removed from the global sessions tree
3. A session-closed notification is sent
4. Resources are freed when reference count reaches zero

Session Groups

Sessions can be grouped together to share windows. From the man page (tmux.1:1344-1370):

Sessions in the same group share the same set of windows - new windows are linked to all sessions in the group and any windows closed are removed from all sessions.

The current and previous window and any session options remain independent, and any session in a group may be killed without affecting the others.

# Create a new session in the same group
$ tmux new-session -t existing-session -s new-session

# Create a new named group
$ tmux new-session -s session1 -t mygroup
$ tmux new-session -s session2 -t mygroup

Session Management

From session.c, key session operations include:

Switching Windows

// From session.c:417-435
int session_next(struct session *s, int alert)
{
    struct winlink *wl;
    
    if (s->curw == NULL)
        return (-1);
    
    wl = winlink_next(s->curw);
    if (wl == NULL)
        wl = RB_MIN(winlinks, &s->windows);
    
    return (session_set_current(s, wl));
}

Key bindings for window navigation:

• Prefix n - Next window
• Prefix p - Previous window
• Prefix l - Last (previously selected) window
• Prefix 0-9 - Select window by number

Activity Tracking

From session.c:266-292, sessions track activity time for lock-after-time functionality:

void session_update_activity(struct session *s, struct timeval *from)
{
    if (from == NULL)
        gettimeofday(&s->activity_time, NULL);
    else
        memcpy(&s->activity_time, from, sizeof s->activity_time);
    
    // Auto-lock based on lock-after-time option
    if (s->attached != 0) {
        timerclear(&tv);
        tv.tv_sec = options_get_number(s->options, "lock-after-time");
        if (tv.tv_sec != 0)
            evtimer_add(&s->lock_timer, &tv);
    }
}

Session Options

Sessions have their own option hierarchy that inherits from global options:

# Set session option
$ tmux set-option -t my-session status-position top

# Set global session option
$ tmux set-option -g status-interval 5

# Show session options
$ tmux show-options -t my-session

Renaming Sessions

From session.c:232-248, session names are sanitized:

# Rename current session (within tmux)
Prefix $

# Or use command
$ tmux rename-session -t old-name new-name

Session names cannot contain : or . characters - they are automatically replaced with _.

Best Practices

1. Name your sessions: Use descriptive names for easier management
2. Use session groups: For pair programming or shared environments
3. Leverage persistence: Detach instead of closing terminal windows
4. Session scripts: Automate session creation with shell scripts
5. Monitor activity: Use list-sessions to see recent activity times

# Example session startup script
#!/bin/bash
tmux new-session -d -s dev -n editor
tmux send-keys -t dev:editor 'vim' C-m
tmux new-window -t dev -n shell
tmux new-window -t dev -n server
tmux send-keys -t dev:server 'npm run dev' C-m
tmux attach -t dev