> ## 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.

# 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.

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

## 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.

```bash theme={null}
# 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

```bash theme={null}
# 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):

<CodeGroup>
  ```bash Session by ID theme={null}
  $ tmux attach -t \$0
  ```

  ```bash Session by name theme={null}
  $ tmux attach -t mysession
  ```

  ```bash Session by prefix theme={null}
  $ tmux attach -t mys  # Matches 'mysession'
  ```
</CodeGroup>

## Detaching and Attaching

The key feature of sessions is their persistence:

```bash theme={null}
# 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):

<Warning>
  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.
</Warning>

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

```bash theme={null}
# 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

```c theme={null}
// 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:

```c theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# Rename current session (within tmux)
Prefix $

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

<Info>
  Session names cannot contain `:` or `.` characters - they are automatically replaced with `_`.
</Info>

## 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

```bash theme={null}
# 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
```