Multiplexer

tmux: one terminal, many panes, work that can survive the window.

tmux splits a single terminal window into panes and tabs, keeps work running after you close the window, and gives agents a visible workspace beside your editor, tests, logs, and Git. Learn three ideas and a dozen keystrokes and you can supervise more work with less window juggling.

#Why bother

Without tmux, one terminal window is one shell. With it, you get an editor, a running server, logs, and Git side by side — and if you close the laptop or the connection drops, that whole layout is still there when you come back. That last part, persistent sessions, is the feature people fall in love with.

#The three ideas

Everything in tmux is one of three things, nested inside each other.

• Session — a whole workspace for a project. You can have several and jump between them.
• Window — like a browser tab inside a session. Each fills the screen; you switch between them.
• Pane — a split within a window. This is where the actual shells and terminal apps live.

#The prefix — the one habit

Almost every tmux command starts with the prefix: press Ctrla, let go, then tap the next key. It's how tmux knows you're talking to it and not to the program in the pane.

So "split the pane" is really: Ctrla then |. Throughout this page, that pattern means prefix, then the key.

#Best-practice shape in this setup

The modern, low-friction pattern is one tmux session per project, a few clearly named windows inside it, and panes only where seeing two things at once helps. This repo now uses that pattern directly:

A good default shape for a project session is four named windows: edit for the editor or coding agent, shell for general commands, run for the dev server or test watcher, and git for lazygit and review. Create a window with Ctrla then c and name it with Ctrla then ,; resurrect snapshots keep the layout across restarts. Skip the permanent file-tree pane: lt shows a repo's shape on demand, and the fzf pickers (CtrlT files, AltC folders) pop up, do their job, and get out of the way.

That keeps the daily workflow simple: use sesh to move around, let continuum snapshot your state, and reach for tmuxp only when a project has a layout worth sharing or recreating from scratch.

#The essential moves

This is the custom keymap on this setup. You don't need all of it on day one — the panes and sessions rows are what matter first.

Panes

Windows

Best names are short nouns: edit, agent, server, logs, db, git. Window names show in the status bar; pane names show in the pane border.

Naming is hybrid, on purpose. A window you haven't named renames itself after whatever is running in it (zsh, nvim, claude); the moment you name one with Ctrla , your name sticks — auto-renaming turns off for that window only, and programs are never allowed to rename windows out from under you (they can only set the pane title in the border, which is the right place for an agent's task chatter). Renames are also saved into the restore state immediately, so a name you set survives a reboot instead of depending on the last 15-minute autosave. One habit that makes names largely unnecessary: keep one session per project (the session switcher, Ctrla T, names sessions after their folder), and let windows within it be task lanes.

Sessions — the persistent part

Extras

#Selecting and copying: one owner per place

Selection lives in layers, and knowing which one you're in is the whole trick. Outside tmux, Ghostty owns the scrollback and the selection. Inside a tmux pane, tmux owns the history, search, and selection — that's why a terminal's "select last output" can't reach into a pane, and why Ctrla then [ is the way in. Inside a pane running a mouse-aware app (Neovim, lazygit), that app owns the mouse. The mouse is a convenience; the keyboard copy is the skill that travels — over SSH, on any terminal, from a trackpad or a keyboard.

The keyboard copy

Ctrl+a [        enter copy mode
/error          search backward for a string  (n / N repeat)
v               start selecting              (Ctrl+v = block)
y               copy — to the tmux buffer and the system clipboard
q               leave

With the mouse you can still place a selection by dragging — but it now stays put when you release instead of vanishing, so you can adjust it or keep paging, then press y. Two shortcuts skip copy mode entirely: Ctrla then ShiftY grabs the last command and its output, and Ctrla then Ctrly grabs the current directory.

Right-click, and the macOS copy feel

Right-click does the sensible thing per layer: in an ordinary shell pane it shows a one-line copy hint (tmux's split/kill menu now lives on Option+right-click); in Neovim or lazygit it's handed straight to the app. On macOS, Ghostty uses an explicit copy — selecting text no longer auto-copies; press CmdC and the selection clears, matching every other Mac app. On Linux, Ghostty keeps the usual copy-on-select and middle-click-paste convention.

#Project layouts as code

Two layers, one rule: the repo owns the commands (its package scripts and CLI), and your own config owns the arrangement. Personal session recipes live in ~/.config/sesh/sesh.toml — a name, a folder, and a startup command per project, so the prefix T switcher opens a project already doing something useful. Groundwork seeds that file with examples to copy.

When a project always wants the same multi-window arrangement — editor, agent, server, tests, logs — store that as .tmuxp.yaml in the project. That is the shareable version for teams and students. Resurrect restores whatever you personally had open; tmuxp starts a known layout from a file.

session_name: my-app
start_directory: ~/code/my-app
windows:
  - window_name: edit
    layout: main-vertical
    panes:
      - nvim .
      - claude
  - window_name: run
    layout: even-horizontal
    panes:
      - pnpm dev
      - pnpm test -- --watch
  - window_name: git
    panes:
      - lazygit

#The plugins

Most of what makes this tmux pleasant isn't tmux itself — it's a handful of plugins, managed by TPM (the Tmux Plugin Manager). You rarely touch them after install, but knowing what each one does explains where the magic comes from.

Managing them — TPM

Plugins are declared in the config (the set -g @plugin '…' lines). Groundwork runs TPM's command-line installer during chezmoi apply, so a fresh machine should not need a manual plugin install. These keys are still useful for repair and maintenance:

For fully visible output, run the same update from a shell instead of TPM's tmux pane: ~/.config/tmux/plugins/tpm/bin/update_plugins all.

The quiet helpers

Three plugins you'll never think about — they just make the defaults sane and the clipboard work:

The status line — useful, not noisy

Full-screen terminal work hides the macOS menu bar, so the tmux status line carries the few machine signals worth seeing while you supervise an editor, tests, logs, or an agent: current app, CPU, RAM, host, battery when the machine has one, and time. It refreshes every 10 seconds, so it stays glanceable without becoming a tiny dashboard that constantly wakes the machine. Window and session renames repaint immediately; the 10-second pace applies only to the system modules.

Restore from snapshots — resurrect & continuum

This is the pair worth understanding, because together they let a tmux workspace come back after a reboot or fresh server start. They split the job in two:

• tmux-resurrect is the save/restore engine. It writes a snapshot of every session, window, and pane — their exact layout, each pane's working directory, and the programs running in them — to a file on disk, and can rebuild it later. This setup also turns on pane-contents capture, so your scrollback comes back too.
• tmux-continuum automates resurrect: it saves a fresh snapshot every 15 minutes. On a normal desktop profile this config sets @continuum-restore 'on', so a new tmux server restores the last saved layout. The CI and agent container profile renders it off, because surprise restore is wrong for disposable automation. Either way, it restores the latest snapshot, not whatever happened to be on screen at the instant you killed tmux.

You can also drive resurrect by hand whenever you want a checkpoint or an immediate restore:

Seamless Vim ⇄ tmux movement — vim-tmux-navigator

Normally moving between tmux panes needs the prefix, and moving between Neovim splits is a separate set of keys. This plugin erases the seam: the same Alth/j/k/l moves you in a direction regardless of whether the neighbor is a tmux pane or a Neovim window — no prefix, no thinking about which is which.

It's a two-sided plugin: there's the tmux half (here) and a matching Neovim half managed in this Groundwork repo. The trick under the hood: when the key would leave a Neovim split at its edge, Neovim hands control to tmux, which moves to the adjacent pane — and vice versa. Plain CtrlL still reaches the shell, so clear-screen stays where terminal users expect it.

The look — Catppuccin

The rounded, pastel status bar is the Catppuccin theme (the mocha flavor — the same palette as this guide, Ghostty, and your editor). The status line is built from composable modules: session name on the left, app/host/clock on the right. It's purely cosmetic; nothing breaks if you change or remove it. To try another flavor, set @catppuccin_flavor in the config to latte (light), frappe, or macchiato, then reload.

#Going deeper

When the basics feel automatic, these run from a gentle intro to the full reference:

• Official tmux wiki: Getting Started — the canonical intro to sessions, windows, and panes.
• Ham Vocke: A quick and easy guide to tmux — a clean ~10-minute hands-on starter.
• DreamsOfCode: tmux walkthrough (video) — the popular modern tour of a stack much like this one.
• DreamsOfCode: the Zen tmux configuration — nine concrete config improvements, explained.
• Smart tmux sessions with sesh — get the most out of the prefix T session switcher.
• The Tao of tmux — a full, free online book for going deep.
• awesome-tmux — the hub for plugins, themes, and tools.