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

# Quick Start Guide

> Get up and running with tmux in 5 minutes. Learn sessions, windows, panes, and essential keyboard shortcuts.

## Your First tmux Session

Let's get you productive with tmux quickly. This guide covers the essential concepts and commands you'll use daily.

<Steps>
  <Step title="Start tmux">
    Open your terminal and start your first tmux session:

    ```bash theme={null}
    tmux
    ```

    You'll see a new shell prompt with a green status bar at the bottom showing:

    * `[0]` - session name
    * `0:bash*` - window number and name
    * Your hostname and time on the right
  </Step>

  <Step title="Understand the prefix key">
    All tmux commands start with a prefix key: `C-b` (Ctrl-b)

    <Info>
      Press `Ctrl` and `b` together, release both keys, then press the command key. For example, `C-b c` means: press Ctrl-b, release, then press c.
    </Info>

    The prefix key tells tmux: "I'm about to give you a command, not the shell."
  </Step>

  <Step title="Create a new window">
    Press `C-b c` to create a new window.

    Notice the status bar now shows:

    ```
    [0] 0:bash- 1:bash*
    ```

    The `*` indicates your current window. The `-` marks the previous window.
  </Step>

  <Step title="Navigate between windows">
    Try these navigation commands:

    * `C-b n` - next window
    * `C-b p` - previous window
    * `C-b 0` - switch to window 0
    * `C-b 1` - switch to window 1
    * `C-b l` - toggle between current and last window
  </Step>

  <Step title="Split into panes">
    Now let's split a window into multiple panes:

    * `C-b %` - split vertically (left and right)
    * `C-b "` - split horizontally (top and bottom)

    Each pane is an independent terminal.
  </Step>

  <Step title="Navigate between panes">
    Move between panes:

    * `C-b o` - cycle to next pane
    * `C-b ↑` - move to pane above
    * `C-b ↓` - move to pane below
    * `C-b ←` - move to pane on left
    * `C-b →` - move to pane on right
    * `C-b ;` - move to previously active pane
  </Step>

  <Step title="Detach from session">
    Press `C-b d` to detach from the session.

    You'll see a message:

    ```
    [detached (from session 0)]
    ```

    Your session is still running in the background! All your windows and panes are preserved.
  </Step>

  <Step title="Reattach to session">
    Return to your session with:

    ```bash theme={null}
    tmux attach
    ```

    Everything is exactly as you left it.
  </Step>
</Steps>

## Essential Commands Reference

<Accordion title="Session Management">
  <CodeGroup>
    ```bash Create new session theme={null}
    # Default session (numbered)
    tmux

    # Named session
    tmux new -s mysession

    # Named session with window name
    tmux new -s mysession -n mywindow
    ```

    ```bash Attach to session theme={null}
    # Attach to last session
    tmux attach

    # Attach to specific session
    tmux attach -t mysession

    # Create or attach (attach if exists, create if not)
    tmux new -As mysession
    ```

    ```bash List and switch sessions theme={null}
    # List all sessions
    tmux ls

    # Inside tmux: switch sessions
    C-b s    # interactive session selector
    C-b (    # previous session
    C-b )    # next session
    ```

    ```bash Kill sessions theme={null}
    # Kill specific session
    tmux kill-session -t mysession

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

    # Kill tmux server (all sessions)
    tmux kill-server
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Window Management">
  | Key Binding | Action                                  |
  | ----------- | --------------------------------------- |
  | `C-b c`     | Create new window                       |
  | `C-b ,`     | Rename current window                   |
  | `C-b &`     | Kill current window (with confirmation) |
  | `C-b n`     | Next window                             |
  | `C-b p`     | Previous window                         |
  | `C-b 0-9`   | Switch to window by number              |
  | `C-b l`     | Switch to last active window            |
  | `C-b w`     | Interactive window list                 |
  | `C-b f`     | Find window by name                     |
  | `C-b .`     | Move window to different index          |
</Accordion>

<Accordion title="Pane Management">
  | Key Binding | Action                                |
  | ----------- | ------------------------------------- |
  | `C-b %`     | Split pane vertically                 |
  | `C-b "`     | Split pane horizontally               |
  | `C-b x`     | Kill current pane (with confirmation) |
  | `C-b o`     | Move to next pane                     |
  | `C-b ;`     | Move to previously active pane        |
  | `C-b ↑↓←→`  | Move to pane in direction             |
  | `C-b {`     | Swap with previous pane               |
  | `C-b }`     | Swap with next pane                   |
  | `C-b z`     | Toggle pane zoom (fullscreen)         |
  | `C-b !`     | Break pane into new window            |
  | `C-b q`     | Show pane numbers                     |
</Accordion>

<Accordion title="Pane Resizing">
  | Key Binding        | Action                       |
  | ------------------ | ---------------------------- |
  | `C-b C-↑`          | Resize pane up by 1 cell     |
  | `C-b C-↓`          | Resize pane down by 1 cell   |
  | `C-b C-←`          | Resize pane left by 1 cell   |
  | `C-b C-→`          | Resize pane right by 1 cell  |
  | `C-b M-↑`          | Resize pane up by 5 cells    |
  | `C-b M-↓`          | Resize pane down by 5 cells  |
  | `C-b M-←`          | Resize pane left by 5 cells  |
  | `C-b M-→`          | Resize pane right by 5 cells |
  | `C-b M-1` to `M-7` | Apply preset layouts         |
  | `C-b Space`        | Cycle through preset layouts |
</Accordion>

<Accordion title="Copy Mode and Scrollback">
  <Steps>
    <Step title="Enter copy mode">
      Press `C-b [` to enter copy mode and scroll through history.

      You'll see `[0/0]` in the top-right corner showing your position in history.
    </Step>

    <Step title="Navigate in copy mode">
      **Emacs mode** (default):

      * Arrow keys - move cursor
      * `C-Space` - begin selection
      * `M-w` - copy selection
      * `C-g` - exit copy mode

      **Vi mode** (if `set -g mode-keys vi` in config):

      * `h/j/k/l` - move cursor
      * `Space` - begin selection
      * `Enter` - copy selection
      * `q` - exit copy mode
    </Step>

    <Step title="Paste">
      Press `C-b ]` to paste the most recently copied text.
    </Step>
  </Steps>

  <Tip>
    Use `Page Up` as a shortcut to enter copy mode and scroll up one page immediately.
  </Tip>
</Accordion>

<Accordion title="Other Useful Commands">
  | Key Binding | Action                          |
  | ----------- | ------------------------------- |
  | `C-b ?`     | List all key bindings           |
  | `C-b :`     | Enter command prompt            |
  | `C-b t`     | Show clock                      |
  | `C-b i`     | Display window information      |
  | `C-b ~`     | Show previous messages          |
  | `C-b d`     | Detach from session             |
  | `C-b D`     | Choose client to detach         |
  | `C-b r`     | Redraw screen                   |
  | `C-b C-b`   | Send literal C-b to application |
</Accordion>

## Practical Workflow Example

Here's a common development workflow:

<Steps>
  <Step title="Create a development session">
    ```bash theme={null}
    tmux new -s dev
    ```
  </Step>

  <Step title="Set up your layout">
    * Start in your project directory
    * Press `C-b %` to split vertically
    * In the right pane, press `C-b "` to split horizontally

    You now have three panes:

    ```
    ┌─────────┬─────────┐
    │         │         │
    │  Code   │  Tests  │
    │         ├─────────┤
    │         │  Logs   │
    └─────────┴─────────┘
    ```
  </Step>

  <Step title="Run your development tools">
    * Left pane: Open your editor (`vim`, `nano`, etc.)
    * Top-right pane: Run your test watcher
    * Bottom-right pane: Tail your application logs
  </Step>

  <Step title="Detach when done">
    Press `C-b d` to detach. Your session keeps running.
  </Step>

  <Step title="Return later">
    ```bash theme={null}
    tmux attach -t dev
    ```

    Everything is still running!
  </Step>
</Steps>

## Remote Development Workflow

One of tmux's most powerful features is persistence over SSH:

<Steps>
  <Step title="SSH to remote server">
    ```bash theme={null}
    ssh user@remote-server
    ```
  </Step>

  <Step title="Start or attach to tmux">
    ```bash theme={null}
    # First time: create session
    tmux new -s work

    # Later: reattach to existing session
    tmux attach -t work
    ```
  </Step>

  <Step title="Do your work">
    Start long-running builds, tests, or processes.
  </Step>

  <Step title="Disconnect safely">
    Press `C-b d` to detach, then exit SSH:

    ```bash theme={null}
    exit
    ```

    Your tmux session keeps running on the server!
  </Step>

  <Step title="Reconnect anytime">
    ```bash theme={null}
    ssh user@remote-server
    tmux attach -t work
    ```

    Pick up exactly where you left off.
  </Step>
</Steps>

<Warning>
  If your SSH connection drops unexpectedly, tmux automatically detaches. Your session and all running processes continue uninterrupted.
</Warning>

## Basic Configuration

Create `~/.tmux.conf` to customize tmux:

```bash theme={null}
# Change prefix from C-b to C-a (like screen)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Increase scrollback buffer
set -g history-limit 10000

# Start window numbering at 1 instead of 0
set -g base-index 1
set -g pane-base-index 1

# Renumber windows when one is closed
set -g renumber-windows on

# Improve colors
set -g default-terminal "tmux-256color"

# Split panes using | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

# Reload config file
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Vi mode for copy
set -g mode-keys vi
```

After creating or editing the config:

```bash theme={null}
# Load configuration in running session
C-b : source-file ~/.tmux.conf

# Or restart tmux
tmux kill-server
tmux
```

## Common Patterns

<Accordion title="Create a session with multiple windows">
  ```bash theme={null}
  # Create session with specific layout
  tmux new-session -d -s myproject -n editor
  tmux send-keys -t myproject:editor 'cd ~/myproject && vim' C-m

  tmux new-window -t myproject -n tests
  tmux send-keys -t myproject:tests 'cd ~/myproject && npm test' C-m

  tmux new-window -t myproject -n server  
  tmux send-keys -t myproject:server 'cd ~/myproject && npm start' C-m

  # Attach to the session
  tmux attach -t myproject
  ```
</Accordion>

<Accordion title="Split window with commands">
  ```bash theme={null}
  # From shell: create session with splits
  tmux new-session -d -s dev 'vim'
  tmux split-window -h -t dev 'npm test'
  tmux split-window -v -t dev 'npm start'
  tmux attach -t dev
  ```
</Accordion>

<Accordion title="Share a session with another user">
  ```bash theme={null}
  # User 1: Create named session
  tmux new -s pair

  # User 2: Attach to same session
  tmux attach -t pair
  ```

  <Info>
    Both users need access to the same server and tmux socket. This is useful for pair programming or collaborative debugging.
  </Info>
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="tmux colors look wrong">
    Add to your shell configuration (`.bashrc`, `.zshrc`):

    ```bash theme={null}
    export TERM=xterm-256color
    ```

    And in `~/.tmux.conf`:

    ```bash theme={null}
    set -g default-terminal "tmux-256color"
    ```
  </Accordion>

  <Accordion title="Can't scroll with mouse wheel">
    Enable mouse support in `~/.tmux.conf`:

    ```bash theme={null}
    set -g mouse on
    ```

    Then reload config: `C-b : source-file ~/.tmux.conf`
  </Accordion>

  <Accordion title="Accidentally detached, how to reattach?">
    ```bash theme={null}
    # List sessions
    tmux ls

    # Attach to last session
    tmux attach

    # Attach to specific session
    tmux attach -t session-name
    ```
  </Accordion>

  <Accordion title="Want to close everything and start fresh">
    ```bash theme={null}
    # Kill all tmux sessions and server
    tmux kill-server

    # Start new session
    tmux
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Key Bindings" icon="keyboard">
    Press `C-b ?` inside tmux to see all default key bindings, or explore customization options.
  </Card>

  <Card title="Configuration" icon="gear">
    Learn advanced configuration options in `~/.tmux.conf` including status bar customization, custom key bindings, and hooks.
  </Card>

  <Card title="Command Reference" icon="book">
    Read the manual page (`man tmux`) for complete command documentation and options.
  </Card>

  <Card title="Community Resources" icon="users">
    Join the tmux community at [https://github.com/tmux/tmux](https://github.com/tmux/tmux) for plugins, themes, and support.
  </Card>
</CardGroup>

<Tip>
  The quickest way to learn is to practice! Try using tmux for your next project and the key bindings will become second nature.
</Tip>