Library Modules

Module Overview

9 composable modules in lib/, each owning a single domain. Sourced in dependency order by tmux.conf.

Sourcing Order

core → vim → mouse → theme → clipboard → panes → sessions →
popups (3.2+) → status → modern (3.2+) → plugins → local → TPM init

Theme loads before modules that reference @theme-* variables. Plugins load last so TPM can register keybindings. local.conf is optional (gitignored) for machine-specific overrides.

Module Reference

Module Domain What It Configures Bindings

core.conf

Terminal settings

Prefix (C-a), TERM, history (50000), base-index 1, escape-time 0, focus-events, shell

0

vim.conf

Navigation + copy mode

Pane nav (h/j/k/l, vim-aware C-h/j/k), window jump (M-1..9), copy mode (v/V/C-v/y), paste, clear screen

48

mouse.conf

Mouse events

Mouse on, scroll behavior, click-to-select pane, double/triple click word/line select, drag resize

8

clipboard.conf

Clipboard integration

Platform detection chain: wl-copy (Wayland) → xclip (X11) → pbcopy (macOS) → /dev/null fallback. Sets @clipboard-cmd for reuse.

0

panes.conf

Pane operations

Splits (|/-/\/_), resize (H/J/K/L fine, C-H/J/K/L coarse), zoom, mark/swap, layouts (M-1..5 + G/I/O), sync, border titles

40

sessions.conf

Session management

New/kill/find session, choose-tree, window rename, quick project nav (M-w/a/p), nested tmux F12 toggle, send-prefix

17

popups.conf

Popup workflows

Terminal (backtick), lazygit (g), yazi/lf (e), fzf session picker (C-f), scratchpad (n), help cheatsheet (/)

6

status.conf

Status bar

Status toggle (b), format strings, window status, activity indicators. Uses @theme- variables. Runs scripts/status-.sh on 5s interval.

1

modern.conf

tmux 3.2+ features

Extended keys, allow-passthrough (image protocol), popup border style, Wayland clipboard. Version-guarded in tmux.conf.

0

Domain Boundaries

Each module has a strict "does not touch" contract:

Module Does NOT Touch

vim.conf

Splits, resize, zoom, session management, popups

panes.conf

Navigation, copy mode, sessions, popups

sessions.conf

Pane operations, navigation, popups

popups.conf

Core navigation, pane operations, sessions

status.conf

Navigation, panes, sessions (only the b toggle)

Violations are caught by scripts/check-conflicts.sh which tracks {table}:{key} tuples and flags same-table duplicates.

Binding Table Context

A single key can appear in multiple modules without conflict when bound to different tables:

Table Syntax Meaning

prefix (default)

bind KEY

Requires C-a first, then KEY

root

bind -n KEY

No prefix needed, fires immediately

copy-mode-vi

bind -T copy-mode-vi KEY

Active only in vi copy mode

off

bind -T off KEY

Active when nested tmux is in OFF state (F12 toggle)

Example: r is bound as C-a r (reload config, prefix table) AND as r in copy-mode-vi (rectangle toggle). Different tables, no conflict.