dotfiles/docs/terminal/tmux.mdx

---
title: tmux
description: tmux prefix, options, bindings, tpm plugins and the dotbar status line.
---

Terminal multiplexer. Used locally through the kitty tmux host (`super+t` in [kitty](/terminal/kitty)) and remotely on goliath.

| | |
| --- | --- |
| Source | `dot_config/tmux/tmux.conf`, `dot_config/tmux/tmux-nerd-font-window-name.yml`, `dot_config/tmux/executable_niri-title.sh` |
| Target | `~/.config/tmux/` |
| Install | `tmux` in `.chezmoidata/packages.yaml` (pacman, brew) |

tpm is a `git-repo` external in `.chezmoiexternal.toml`, cloned to `~/.config/tmux/plugins/tpm` when missing. `tmux.conf` ends with `run '~/.config/tmux/plugins/tpm/tpm'`. Plugins tpm installs (`prefix I`) land next to it and are ignored by chezmoi. [Ghostty](/terminal/ghostty) starts every surface in `tmux new-session -A -s main`.

## Options

The prefix is the default `ctrl+b`.

| Option | Value |
| --- | --- |
| `default-terminal` | `tmux-256color`; `xterm-kitty:Tc` override; features `RGB:usstyle:hyperlinks:clipboard:extkeys` |
| `extended-keys` | `always`, format `csi-u` |
| `base-index` / `pane-base-index` | `1` / `1`; `renumber-windows on` |
| `status-position` | `top` |
| `allow-passthrough` | `on` (kitty graphics for yazi previews); `TERM`, `TERM_PROGRAM` added to `update-environment` |
| `set-clipboard` | `on` (OSC 52) |
| `mouse` | `on` |
| `mode-keys` | `vi` |
| `set-titles` | `on`, `set-titles-string "#T (#S)"`, `status-interval 1`, `automatic-rename on` |
| `history-limit` | `50000` |
| Styling | `status-style` and `popup-style` use default bg; popup border rounded, `fg=#5c5c66` |

## Keybindings

| Key | Action |
| --- | --- |
| `S-Enter` (no prefix) | Sends `Esc [13;2u` |
| `prefix t` | New window in pane cwd; on sessions with `@ssh_host` set (by the Vicinae tmux-sessions extension), runs `ssh <host>` instead |
| `prefix [` / `prefix H` | Previous window |
| `prefix ]` / `prefix L` | Next window |
| `prefix %` | Split right, 30% width, pane cwd |
| `prefix "` | Split below, 25% height, pane cwd |
| `prefix Escape` | Copy mode |
| `ctrl+h/j/k/l` (no prefix) | Select pane left/down/up/right, or forward the key if the pane runs vim/nvim/fzf (`is_vim`) |
| `prefix ctrl+l` | Send `ctrl+l` (clear screen) |
| `prefix o` | tmux-sessionx picker (`@sessionx-bind`) |
| `C-Space` (no prefix) | tmux-palette |
| `M-f` / `M-m` | tmux-palette find pane / move pane |

### Copy mode (vi)

| Key | Action |
| --- | --- |
| `v` | Begin selection |
| `y` | Copy to `wl-copy` and exit |
| `Y` | Copy to `wl-copy` and cancel |
| Mouse drag end | Copy to `wl-copy` |
| `ctrl+h/j/k/l` | Select pane |

## Plugins

| Plugin | Settings |
| --- | --- |
| `tmux-plugins/tpm` | Plugin manager |
| `tmux-plugins/tmux-sensible` | Defaults |

### Status line (dotbar)

Top, rounded, centered (`absolute-centre`), left section on, right off, session on the left. Colors: bg `#0B0E14`, fg `#475266`, current `#BFBDB6`, session `#565B66`, prefix `#95E6CB`. Window format ` #W ` separated by ` • `; right text ` %H:%M `. Bold off. SSH indicator enabled with an icon; maximized icon only on the zoomed tab.

## tmux-nerd-font-window-name.yml

`show-name: true`, icon on the left, a fallback icon, blank multi-pane icon. Icons are defined for `mprocs`, `mm`, `macmon`, `make`, `zsh`, `nvim`, `devbox`, `psql`, `yazi`, `lazygit`, `gh`, `tv`, `docker`, `bun`, `node`, `npm`, `pnpm`, `go`, `bunx`, `claude`.

## niri-title.sh

Installed only on Linux `desktop`/`laptop` roles (gated in `.chezmoiignore.tmpl`). Given the pane command, path, tty and title, it prints a context segment for the window title read by [Niri](/desktop/niri), by priority:

1. `ssh`/`mosh-client`/`autossh`/`et`: the remote target.
2. `nvim`/`vim`: the pane title (current file).
3. Git repo: directory name and branch.
4. Otherwise the cwd basename.

`tmux.conf` does not currently call the script; its title string is `#T (#S)`.