Deployment

Installation

Prerequisites

Requirement Purpose Check

tmux 3.2+

display-popup, extended-keys, allow-passthrough

tmux -V

fzf

Session picker popup, theme switcher interactive mode

command -v fzf

wl-copy

Wayland clipboard integration (primary clipboard tool)

command -v wl-copy

Nerd Font

Status bar icons and glyphs

Visual check in terminal

TPM

Plugin management (auto-cloned on first prefix + I)

ls ~/.config/tmux/plugins/tpm/

Symlink Setup

Step 1: Check what currently exists

file ~/.config/tmux

This tells you whether ~/.config/tmux is a symlink or a directory. The answer determines which path to follow.

Path A: It’s a symlink (or doesn’t exist)

If file reports symbolic link or the path doesn’t exist, a direct ln -sf works:

ln -sf ~/atelier/_projects/personal/tmux-quantum ~/.config/tmux

Path B: It’s a directory (tmux-config or similar)

If ~/.config/tmux is a directory, ln -sf creates a symlink inside the directory instead of replacing it. This is the most common deployment mistake. You end up with ~/.config/tmux/tmux-quantum (a link inside the old config) while the old config remains active.

B.1 — Check for broken links from a failed ln -sf attempt:

ls -la ~/.config/tmux/tmux-quantum 2>&1

If this shows a symlink (e.g., tmux-quantum → …​/tmux-quantum), a previous ln -sf misfired. Remove it:

rm ~/.config/tmux/tmux-quantum

If it reports No such file or directory, no cleanup needed — skip to B.2.

B.2 — Verify the directory is backed by a git repo (safe to remove):

git -C ~/.config/tmux remote -v

Confirm the remote points to tmux-config (or your expected repo). This proves the directory content is tracked in git and nothing is lost by removing it.

git -C ~/.config/tmux status --short

If there are uncommitted changes, commit or stash them in the source repo before removing. Do NOT remove a directory with uncommitted work.

B.3 — Remove and replace:

rm -rf ~/.config/tmux
ln -sf ~/atelier/_projects/personal/tmux-quantum ~/.config/tmux

B.4 — Verify:

file ~/.config/tmux

Expect: symbolic link to /home/evanusmodestus/atelier/_projects/personal/tmux-quantum

readlink -f ~/.config/tmux

Expect: /home/evanusmodestus/atelier/_projects/personal/tmux-quantum

Step 2: Tmuxinator sessions

The same directory-vs-symlink issue applies. Check first:

file ~/.config/tmuxinator

If it’s a symlink (e.g., stowed from dots-quantum):

ln -sf ~/.config/tmux/sessions ~/.config/tmuxinator

If it’s a directory, check for broken links from a failed attempt:

ls -la ~/.config/tmuxinator/sessions 2>&1

If a broken sessions symlink exists, remove it:

rm ~/.config/tmuxinator/sessions

Then check for uncommitted content in the directory before removing:

ls ~/.config/tmuxinator/ | head -5

If the directory only contains .yml files managed by dots-quantum (stowed), it is safe to replace:

rm -rf ~/.config/tmuxinator
ln -sf ~/.config/tmux/sessions ~/.config/tmuxinator

Verify:

file ~/.config/tmuxinator

Expect: symbolic link to …​

readlink -f ~/.config/tmuxinator

Expect: /home/evanusmodestus/atelier/_projects/personal/tmux-quantum/sessions

Step 3: Final verification

Both symlinks must resolve to tmux-quantum. Run both checks — if either fails, do not proceed to plugin installation.

readlink -f ~/.config/tmux && readlink -f ~/.config/tmuxinator

Expect:

/home/evanusmodestus/atelier/_projects/personal/tmux-quantum
/home/evanusmodestus/atelier/_projects/personal/tmux-quantum/sessions

Confirm the tmux-quantum file structure is visible:

ls ~/.config/tmux/lib/ | wc -l

Expect: 9 (the 9 lib modules). If you see numbered directories (01_CORE, 02_THEMES), the symlink still points to tmux-config.

Plugin Installation

Existing TPM plugins from tmux-config will not carry over (they were in the old directory). Install fresh:

Launch tmux, then press C-a I (capital I). TPM clones all plugins declared in plugins/tpm.conf. First run takes 10-20 seconds.

Validation Checklist

Step-by-Step

  1. Source config

    tmux source-file ~/.config/tmux/tmux.conf

    Expect: no errors. If errors appear, read the message — it will reference the exact file and line.

  2. Conflict checker

    ~/.config/tmux/scripts/check-conflicts.sh

    Expect: OK: No same-table keybinding conflicts across 9 modules

  3. Help popup — press C-a /

    Confirm: popup renders with box-drawing layout. C-f listed for session picker (not C-s). Press q to close.

  4. Nested tmux F10 toggle — press F10

    Confirm: status bar changes to show OFF badge using theme colors (red on surface). All local keys pass through to remote. Press F10 again to restore.

    F12 was the original key but is intercepted by Hyprland. If your window manager claims F10, change the key in lib/sessions.conf (both -T root and -T off bindings).

  5. Theme switcher

    ~/.config/tmux/scripts/theme-switcher.sh --list

    Expect: 3 themes listed (aethelred, solar-flare, tokyo-night). Test --fzf for interactive preview.

  6. Popups — test each:

    • C-a ` ` — popup terminal (75%, dismissible with Escape/C-d)

    • C-a g — popup lazygit (requires lazygit installed)

    • C-a e — popup yazi/lf file browser

    • C-a C-f — fzf session picker with preview pane

  7. Status bar — observe the right side of the status bar

    Confirm: git branch/status, system metrics, and project context render without errors or blank segments.

Known Non-Blockers

Issue Impact

status-git.sh locale dependency

Parses English ahead/behind from git status --porcelain --branch. Breaks on non-English LC_MESSAGES. Workaround: use LANG=C prefix or switch to git rev-list --count.

status-system.sh Linux-only

Reads /proc/stat, /proc/meminfo, /proc/loadavg. No macOS/BSD fallback. Outputs -- placeholders on unsupported platforms.

Rollback

Instant revert to tmux-config (predecessor):

ln -sf ~/atelier/_projects/personal/tmux-config ~/.config/tmux
tmux source-file ~/.config/tmux/tmux.conf

Risk assessment: user-space only. A tmux config cannot damage the system. Running sessions survive a bad source-file. If rendering breaks, tmux kill-server from a raw terminal + rollback symlink.

Plugin Reference

Plugin Purpose Key Config

tmux-resurrect

Save/restore sessions across restarts. C-s save, C-r restore.

Captures pane contents, nvim/vim sessions, shell history. Dir: ~/.config/tmux/resurrect/

tmux-continuum

Auto-save every 15 minutes, auto-restore on tmux start.

@continuum-save-interval 15, @continuum-restore on

tmux-yank

System clipboard integration for copy mode.

Primary selection on yank, clipboard on mouse. Uses @clipboard-cmd from clipboard.conf.

tmux-thumbs

Copy hints (like vimium). Space to activate, colemak-homerow alphabet.

Copies to wl-copy. Unique colors on.

tmux-open

Open URLs/files from copy mode. o to open, C-o with $EDITOR.

Uses system xdg-open or equivalent.

tmux-prefix-highlight

Status bar indicator for prefix/copy/sync modes.

WAIT/COPY/SYNC prompts. Uses @theme-* variables for colors.

tmux-sessionist

Session management extras. g switch by name, C create, X kill, @ promote pane.

Comments in tpm.conf document all bindings.

Session Templates

25 tmuxinator YAML templates in sessions/, organized by prefix:

Prefix Count Purpose

cfg-

6

Configuration editing (ansible, dotfiles, email, nvim-lsp, oci-vm, tmux)

proj-

7

Project work (aethelred, domus-captures, domus-digitalis, netapi-tui, ollama, tmux-config, work)

train-

6

Learning/practice (diffview, nvim, pyats-report-gen, python, ripgrep, sql-py-json)

test-

1

Testing workflows (nvim-plugins)

lab-

1

Lab experiments (vimdiff)

lrn-

1

Structured learning (spanish)

sec-

1

Security operations (secrets)

daily-

1

Daily routines (fleeting)

data-

1

Data work (analysis)

Launch with: tmuxinator start <name> (e.g., tmuxinator start proj-domus-captures)