tmux

Catalog v8.

Adds terminal windows and split panes, mouse support, vi copy mode, OSC 52 clipboard support, and saved sessions through tmux-resurrect and tmux-continuum.

Select

The terminal shell preset includes tmux, and multiplexer chooses it in either preset:

[shell]
multiplexer = "tmux" # or "none"

Apply the change after editing limanix.toml.

Versions

tmux and its plugins come from the catalog's base Nixpkgs revision. This module has no version lines. Inside the VM, tmux -V shows the installed version.

Use

Inside the VM, create or attach to a named session:

tmux new-session -A -s work

The platform's limanix-session work command opens the same named session.

The module provides the guest session interface used by limanix shell --session. Create or attach to that session directly from the Mac:

limanix shell <name> --session work

The tmux provider rejects names containing . or : with status 64 because tmux normalizes those characters. Use names such as work or project-api to keep session identity unambiguous. Other accepted names are passed literally.

tmux starts only when you run it. The prefix is Ctrl-B: press it, release it, then press the second key.

Keys	Action
Ctrl-B, c	New window
Ctrl-B, % / "	Split left/right or top/bottom
Ctrl-B, w	Choose a window
Ctrl-B, d	Detach from the session
Ctrl-B, [	Enter copy mode; v selects and y copies
Ctrl-H/J/K/L	Move left/down/up/right between panes
Ctrl-B, Ctrl-H/J/K/L	Send the original control key to the application
Alt-H/J/K/L	Resize a pane
Ctrl-B, Ctrl-S	Save the current layout
Ctrl-B, Ctrl-R	Restore the last saved layout
Ctrl-B, ?	Show tmux bindings

With AstroNvim, movement and resize keys also navigate editor splits through smart-splits.nvim. In tmux these keys replace their usual shell actions, including Ctrl-L to clear the screen. The Mac terminal must send Option as Alt for the resize bindings. Use Ctrl-B, Ctrl-L to clear the screen, Ctrl-B, Ctrl-K to delete to the end of the line, or Ctrl-B, Ctrl-H to delete a character in shells with those bindings.

To retain the shell's Ctrl/Alt-H/J/K/L bindings, disable the pane navigation bindings in a custom NixOS module:

{
  lmx.tmux.navigation.enable = false;
}

This also disables the prefix forwarding bindings. Mouse support, clipboard, copy mode, and session saving remain enabled. The defaults for programs.tmux.keyMode, programs.tmux.terminal, and programs.tmux.escapeTime can also be overridden by ordinary assignments in a custom module.

Appearance

The colors come from the guest's theme. With the default system flavor they are the terminal's own colors, and the status line has no background of its own: the terminal's shows through. A Catppuccin flavor in [theme] of limanix.toml uses its palette instead. The styles load before the restoration plugins, which preserve continuum's status-line hook.

The right side of the status line starts with the words of lmx status --short that need attention, such as restart or disk-low; it is empty when all is well, and tmux refreshes it once per status interval. Set individual styles through a custom NixOS module:

{
  programs.tmux.extraConfig = ''
    set -g status-style 'bg=black,fg=white'
    set -g pane-active-border-style 'fg=blue'
  '';
}

Replace status-right before the plugins load instead: continuum appends its save hook to it, and a later setting removes that hook and stops the automatic saves.

{ lib, ... }:
{
  programs.tmux.extraConfigBeforePlugins = lib.mkAfter ''
    set -g status-right '%H:%M '
  '';
}

Clipboard and color

Use a terminal on the Mac with truecolor and OSC 52 clipboard support. The VM's platform base supplies Ghostty's terminal description for TERM=xterm-ghostty. The module enables these capabilities for xterm* terminals; other terminal types use tmux's capability detection. Copying a selection sends it through the terminal connection to the Mac clipboard. Paste from the Mac with the terminal's normal paste shortcut.

The platform's pbcopy and pbpaste work inside tmux too: they go through the attached client's terminal. Terminal and clipboard explains the required terminal permissions; see tmux's clipboard guide for others.

Resume after a VM restart

Continuum saves every 15 minutes while tmux's status line is active. Before limanix update, save with Ctrl-B, Ctrl-S and wait for the save to finish. Files are stored in ~/.tmux/resurrect/ inside the VM. Start tmux after reconnecting; continuum restores the latest snapshot when the tmux server starts.

The snapshot includes sessions, windows, pane layout, and working directories. Resurrect restarts its upstream default list of programs, such as editors, pagers, and terminal monitors. It does not preserve running processes or unsaved editor buffers. Development servers and test commands need to be started again. See the supported program list.

Personal overrides belong in ~/.tmux.conf inside the VM. Keep the status line enabled and preserve continuum's status-right hook if you customize it.

Configuration and integration

Boundary	Contract
Public option	lmx.tmux.navigation.enable, Boolean default true
Standard settings	programs.tmux.*, including key mode, terminal, escape delay and extra configuration
Personal state	~/.tmux.conf and snapshots under ~/.tmux/resurrect/
Integration	Supplies limanix.session.command; AstroNvim uses smart-splits pane markers
Services	tmux starts on demand; selecting the module does not attach ordinary shells

Corner cases

Case	Behavior or next step
Session name contains . or :	The tmux provider rejects it rather than attaching a normalized name
Host clipboard does not work	Check OSC 52 support and terminal permission on the Mac
Navigation replaces shell keys	Use prefix forwarding or disable lmx.tmux.navigation.enable
VM restart	Restore the saved layout; interrupted processes and unsaved buffers are not restored
Custom status line	Keep continuum's status hook when changing it