# Tmux Configuration Personal tmux setup on macOS with tmux 3.6a, [[Ghostty]], and [[Neovim]]. Config file: `~/.tmux.conf` > [!info] Architecture Mental Model > - A **server** runs in the background and holds all state > - **Sessions** are independent workspaces (e.g., "project-A", "notes") > - Each session has **windows** (like browser tabs) > - Each window has **panes** (split views within a tab) > - You **detach** from a session (it keeps running) and **attach** later ## Key Settings | Setting | Value | Why | |---------|-------|-----| | Prefix | `Ctrl+Space` | Easy to press, no finger stretch | | Mouse | Enabled | Click panes, scroll, drag to resize | | Copy mode | Vi keys | Natural for Neovim users | | Escape time | 10ms | Default 500ms causes Neovim input lag | | History | 50,000 lines | Default 2,000 is too small | | Base index | 1 | Window/pane numbering starts at 1 | | True color | `tmux-256color` + `:RGB` | Full color support in Ghostty | | Clipboard | OSC 52 + pbcopy fallback | Ghostty supports OSC 52 natively | | Scrollbars | Enabled | tmux 3.6 visual scroll indicator | ## Cheat Sheet ### Session Management | Keys | Action | |------|--------| | `tmux` | Start a new session | | `tmux new -s name` | Start a named session | | `tmux ls` | List sessions | | `tmux attach -t name` | Attach to a session | | `prefix d` | Detach from current session | | `prefix | Rename session | | `prefix s` | Switch between sessions | ### Windows (tabs) | Keys | Action | |------|--------| | `prefix c` | New window (in current path) | | `prefix 1-9` | Switch to window by number | | `prefix n` / `prefix p` | Next / previous window | | `prefix ,` | Rename window | | `prefix &` | Close window | | `prefix w` | Window overview (picker) | ### Panes (splits) | Keys | Action | |------|--------| | `prefix \|` | Split vertically (side by side) | | `prefix -` | Split horizontally (top/bottom) | | `prefix h/j/k/l` | Navigate panes (vim-style) | | `Ctrl+h/j/k/l` | Navigate panes (works across Neovim too) | | `prefix H/J/K/L` | Resize panes (repeatable) | | `prefix x` | Close pane | | `prefix z` | Toggle pane zoom (fullscreen) | | Mouse drag border | Resize pane | ### Copy Mode (scrollback) | Keys | Action | |------|--------| | `prefix [` | Enter copy mode | | `v` | Begin selection | | `Ctrl+v` | Rectangle selection | | `y` | Yank to clipboard | | `q` | Exit copy mode | | Mouse scroll | Scroll (auto-enters copy mode) | | `/` | Search forward (in copy mode) | | `?` | Search backward (in copy mode) | ### Plugins | Keys | Action | |------|--------| | `prefix I` | Install new plugins | | `prefix U` | Update plugins | | `prefix Ctrl+s` | Save session (tmux-resurrect) | | `prefix Ctrl+r` | Restore session (tmux-resurrect) | ### Config | Keys | Action | |------|--------| | `prefix r` | Reload `~/.tmux.conf` | ## Installed Plugins Managed via ==TPM== (Tmux Plugin Manager) at `~/.tmux/plugins/tpm`. | Plugin | Purpose | |--------|---------| | `tmux-yank` | System clipboard integration | | `tmux-resurrect` | Save/restore sessions across restarts | | `tmux-continuum` | Auto-save sessions every 15 min, auto-restore on start | | `vim-tmux-navigator` | Seamless `Ctrl+h/j/k/l` across Neovim and tmux panes | | `catppuccin/tmux` | Catppuccin Mocha theme | > [!tip] Session Persistence > `tmux-resurrect` + `tmux-continuum` make sessions survive reboots. > Sessions auto-save every 15 minutes. On tmux start, the last session auto-restores. > Manual save: `prefix Ctrl+s`. Manual restore: `prefix Ctrl+r`. ## macOS Prerequisite Disable the `Ctrl+Space` system shortcut: **System Settings > Keyboard > Keyboard Shortcuts > Input Sources** — uncheck "Select the previous input source". Only needed if you use `Ctrl+Space` as prefix. No functionality lost if you use a single keyboard layout. ## Neovim Integration The `vim-tmux-navigator` plugin is installed on the tmux side. To complete the setup, install the corresponding Neovim plugin: ```lua -- lazy.nvim { "christoomey/vim-tmux-navigator" } ``` This enables `Ctrl+h/j/k/l` to move seamlessly between Neovim splits and tmux panes without thinking about which one you are in. ## Common Workflows ### Start a new project workspace ```bash tmux new -s myproject ``` ### Detach and come back later ``` prefix d # detach tmux attach -t myproject # reattach later (even after closing terminal) ``` ### Split into editor + terminal layout ``` prefix | # vertical split (editor left, terminal right) prefix - # horizontal split on right pane (terminal top, logs bottom) prefix h # go back to left pane ``` ### Scroll through output ``` prefix [ # enter copy mode k/j or PgUp/PgDn # scroll v # select text y # copy to clipboard prefix ] # paste ``` ## Verification Commands ```bash # Check true color support (should show smooth gradient) printf "\x1b[38;2;255;100;0mTRUECOLOR\x1b[0m\n" # Check tmux version tmux -V # List active sessions tmux ls # Check loaded plugins ls ~/.tmux/plugins/ ```