CR: dots-quantum tmux Package

Change Request Summary

CR Number

CR-2026-03-25-tmux-package

Priority

P2

Type

New Package

Repository

dots-quantum

Status

COMPLETED

Commits

da7e029, d0ddc1d

Background

Current tmux configuration lives in a separate tmux-config repository with over-engineered structure:

tmux-config/                 # 10 numbered directories
├── 00_META/
├── 01_CORE/
├── 02_THEMES/
├── 03_SCRIPTS/
├── 04_PLUGINS/
├── 05_SNIPPETS/
├── 06_RESURRECT/
├── 07_TMUXINATOR/          # 40+ YAML session files
├── 99_ARCHIVE/
└── tmux.conf               # Sources all the numbered directories

This structure is overly complex for dotfiles. The numbered prefixes and deep nesting add cognitive overhead without benefit.

Proposed Change

Create a clean tmux package in dots-quantum with consolidated configuration:

dots-quantum/tmux/
└── .config/
    ├── tmux/
    │   ├── tmux.conf       # ONE consolidated config (~250 lines)
    │   └── plugins/        # TPM plugins (gitignored)
    └── tmuxinator/         # Clean YAML names (no 07_ prefix)
        ├── daily-fleeting.yml
        ├── infra-home-lab.yml
        ├── proj-domus-captures.yml
        └── ... (40+ session files)

Configuration Design

Core Features (from base.conf + keybindings.conf)

  • Prefix: C-a (easier than default C-b)

  • Base index: 1 (windows/panes start at 1)

  • History limit: 50000 lines

  • Escape time: 0 (no delay)

  • vim mode-keys for copy mode

  • Default shell: /usr/bin/zsh

Navigation Keybindings

Key Action

|

Split horizontal (preserves path)

-

Split vertical (preserves path)

h/j/k/l

Navigate panes (prefix+key)

M-h/j/k/l

Navigate panes (no prefix)

M-1..9

Switch to window 1-9

H/J/K/L

Resize panes (5 cells)

< / >

Swap windows left/right

Copy Mode (vim-style)

Key Action

Enter

Enter copy mode

v

Begin selection

V

Select line

C-v or r

Toggle rectangle mode

y

Yank selection

P

Paste buffer

M-v

Paste (no prefix)

Mouse Support

  • Full mouse mode enabled

  • Scroll in copy mode

  • Double-click: select word

  • Triple-click: select line

  • Drag borders to resize panes

Theme: Aethelred (Catppuccin-compatible)

Background: #0d0e1c
Foreground: #e4e4e7
Accent:     #8b5cf6 (purple)
Green:      #10b981
Yellow:     #f59e0b
Red:        #ef4444

Plugins (TPM)

Plugin Purpose

tpm

Plugin manager

tmux-sensible

Sensible defaults

tmux-resurrect

Session persistence

tmux-continuum

Auto-save sessions

tmux-yank

System clipboard

tmux-copycat

Enhanced search

tmux-open

Open selections

tmux-prefix-highlight

Prefix indicator

tmux-sessionist

Session management

Advanced Features

  • vim-tmux-navigator integration (C-h/j/k pane switching aware of nvim)

  • Fuzzy session switcher (prefix + C-j with fzf)

  • Grid layouts (prefix + g for 2x2, prefix + I for IDE layout)

  • Pane synchronization toggle (prefix + S)

  • Pane titles toggle (prefix + T)

Files to Create

dots-quantum/tmux/.config/tmux/tmux.conf    # Consolidated config
dots-quantum/tmux/.config/tmuxinator/*.yml  # 40+ session files
dots-quantum/tmux/.gitignore                # Exclude plugins/ and resurrect/

Installation

# Stow the package
stow -d ~/atelier/_projects/personal/dots-quantum -t ~ tmux

# Install TPM (first time only)
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm

# Install plugins
# Launch tmux, then press: prefix + I

Migration Path

  1. Build new package in dots-quantum

  2. Test in parallel with existing tmux-config

  3. Cutover by updating stow links

  4. Archive tmux-config repo

Success Criteria

  • Single consolidated tmux.conf (no numbered directories) - 350 lines

  • All essential keybindings preserved

  • Aethelred theme with Catppuccin colors

  • vim-tmux-navigator working with nvim

  • Mouse support functional

  • Clipboard integration working (Wayland/X11/macOS/WSL)

  • Session restore working (resurrect + continuum)

  • All tmuxinator sessions copied with clean names - 39 files

Stow Compatibility Audit

Comprehensive audit completed 2026-03-25.

Audit Results

Metric Result

Packages Ready

21 (all structurally correct)

Internal Conflicts

0

Conflicts with Optimus

0

Quantum Targets

135 unique files

Optimus Targets

244 unique files

Overlap

0 files

Safe Migration Path

Phase 1: Pre-Migration

# Remove optimus symlinks that will be replaced
rm ~/.gitconfig ~/.zshrc ~/.zshenv ~/.zprofile

# For tmux (choose ONE):
# Option A: Keep tmux-config repo (skip quantum tmux)
# Option B: Migrate to quantum:
rm ~/.tmux.conf ~/.config/tmux ~/.config/tmuxinator

Phase 2: Deploy Quantum Packages

# Reload shell for new aliases
source ~/.zshrc

# List available packages
dq-list

# Deploy all safe packages (test with -n first)
dq-stow -n bash zsh git vim bin
dq-stow bash zsh git vim bin

# Deploy tmux (if migrating from tmux-config)
dq-stow tmux

# Install TPM plugins
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
# Then in tmux: prefix + I

Phase 3: Verify

# Check symlinks
ls -la ~/.[a-z]* | grep -E "->|^l"
ls -la ~/.config/ | grep quantum

Risk Assessment

Risk Severity Mitigation

Tmux symlink collision

HIGH

Choose single source before stowing

Shell config overwrite

MEDIUM

Back up ~/.zshrc first

Host-specific loss

LOW

Deploy hosts/ only to intended machines

Implementation Steps

Complete runbook for migrating from dotfiles-optimus to dots-quantum.

Pre-Implementation Checklist

# 1. Verify dots-quantum is up to date
cd ~/atelier/_projects/personal/dots-quantum
git pull

# 2. Verify dq-stow function exists
source ~/.zshrc
type dq-stow

# 3. List available packages
dq-list

# 4. Create backup directory
mkdir -p ~/dotfiles-backup-$(date +%Y%m%d)
BACKUP_DIR=~/dotfiles-backup-$(date +%Y%m%d)

Step 1: Backup Current State

# Save current symlink targets
ls -la ~/.config/ > $BACKUP_DIR/config-symlinks.txt
ls -la ~/.[a-z]* > $BACKUP_DIR/home-symlinks.txt 2>/dev/null

# Copy actual config files (not symlinks)
cp -L ~/.zshrc $BACKUP_DIR/zshrc.backup 2>/dev/null
cp -L ~/.bashrc $BACKUP_DIR/bashrc.backup 2>/dev/null
cp -L ~/.gitconfig $BACKUP_DIR/gitconfig.backup 2>/dev/null

Step 2: Remove Optimus Symlinks

# Shell configs
rm -f ~/.zshrc ~/.zshenv ~/.zprofile
rm -f ~/.bashrc ~/.bash_profile

# Git config
rm -f ~/.gitconfig

# Application configs (currently symlinked to optimus)
rm -f ~/.config/aerc
rm -f ~/.config/cava
rm -f ~/.config/chromium-flags.conf
rm -f ~/.config/eww
rm -f ~/.config/hypr
rm -f ~/.config/mimeapps.list
rm -f ~/.config/omp-theme.toml
rm -f ~/.config/powershell
rm -f ~/.config/zathura

# tmux (if migrating from tmux-config)
rm -f ~/.tmux.conf
rm -rf ~/.config/tmux
rm -rf ~/.config/tmuxinator

Step 3: Deploy dots-quantum Packages

# Dry-run first (verify no conflicts)
dq-stow -n bash zsh git

# Deploy shell & core
dq-stow bash zsh git vim bin

# Deploy terminal tools
dq-stow ghostty kitty btop fastfetch fd fzf ripgrep lazygit

# Deploy tmux
dq-stow tmux

# Deploy Hyprland desktop
dq-stow hyprland waybar wofi mako

# Deploy applications
dq-stow aerc zathura mimeapps cava eww chromium powershell

# Deploy theming
dq-stow oh-my-posh

# Deploy AI tools
dq-stow claude

Step 4: Post-Deployment Setup

# Install TPM for tmux (first time only)
if [[ ! -d ~/.config/tmux/plugins/tpm ]]; then
    git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
fi

# Reload shell
exec zsh

# Verify symlinks point to quantum
ls -la ~/.zshrc
# Should show: .zshrc -> atelier/_projects/personal/dots-quantum/zsh/.zshrc

ls -la ~/.config/aerc
# Should show: aerc -> ../atelier/_projects/personal/dots-quantum/aerc/.config/aerc

Step 5: Verification

# Count quantum symlinks in .config
ls -la ~/.config/ | grep -c dots-quantum

# Test critical apps
aerc --help         # Email client
zathura --help      # PDF viewer
tmux -V             # Terminal multiplexer

# Test shell
echo $SHELL
which nvim

# In tmux: Install plugins
# prefix + I

Backout Procedure

If migration fails, restore optimus configuration.

Emergency Shell Recovery

If shell won’t start:

# Use bash as fallback
/bin/bash

# Remove broken quantum symlinks
rm ~/.zshrc ~/.bashrc

# Restore optimus symlinks
cd ~/atelier/_projects/personal/dotfiles-optimus
stow -t ~ base/zsh
stow -t ~ base/bash

Full Rollback

# 1. Unstow all quantum packages
cd ~/atelier/_projects/personal/dots-quantum
for pkg in bash zsh git vim bin tmux hyprland waybar wofi mako \
           aerc zathura mimeapps cava eww chromium powershell \
           oh-my-posh claude ghostty kitty btop fastfetch fd fzf \
           ripgrep lazygit fish; do
    stow -D $pkg 2>/dev/null
done

# 2. Restore optimus shell configs
cd ~/atelier/_projects/personal/dotfiles-optimus
stow -t ~ base/zsh
stow -t ~ base/bash
stow -t ~ base/git

# 3. Restore optimus app configs
stow -t ~ apps/aerc
stow -t ~ apps/zathura
stow -t ~ apps/mimeapps
stow -t ~ apps/cava
stow -t ~ apps/eww
stow -t ~ apps/chromium
stow -t ~ wm/hyprland
stow -t ~ apps/oh-my-posh

# 4. Restore tmux-config (if was using it)
ln -sf ~/atelier/_projects/personal/tmux-config ~/.config/tmux
ln -sf ~/atelier/_projects/personal/tmux-config/07_TMUXINATOR ~/.config/tmuxinator

# 5. Reload shell
exec zsh

Partial Rollback (Single Package)

# Example: Roll back just aerc to optimus
dq-stow -D aerc
cd ~/atelier/_projects/personal/dotfiles-optimus
stow -t ~ apps/aerc

Restore from Backup

# If all else fails, restore from backup
BACKUP_DIR=~/dotfiles-backup-YYYYMMDD
cp $BACKUP_DIR/zshrc.backup ~/.zshrc
cp $BACKUP_DIR/bashrc.backup ~/.bashrc
cp $BACKUP_DIR/gitconfig.backup ~/.gitconfig
exec zsh

Post-Change Validation

Run this comprehensive verification after migration:

echo "=== FULL VERIFICATION ==="

# Shell & Core
echo -e "\n--- Shell & Core ---"
ls -la ~/.zshrc ~/.bashrc ~/.gitconfig ~/.vimrc 2>&1 | grep -E "->|No such"

# Terminal tools
echo -e "\n--- Terminal Tools ---"
ghostty --version 2>/dev/null | head -1 || echo "ghostty: not in PATH"
kitty --version 2>/dev/null | head -1
btop --version 2>/dev/null | head -1
fastfetch --version 2>/dev/null | head -1
fd --version
fzf --version
rg --version | head -1
lazygit --version | head -1

# Hyprland desktop
echo -e "\n--- Hyprland Desktop ---"
ls ~/.config/hypr/hyprland.conf ~/.config/waybar/config \
   ~/.config/wofi/config ~/.config/mako/config 2>&1

# Applications
echo -e "\n--- Applications ---"
aerc --version | head -1
zathura --version | head -1
ls -la ~/.config/mimeapps.list ~/.config/cava/config \
   ~/.config/eww/eww.yuck ~/.config/chromium-flags.conf 2>&1
pwsh --version 2>/dev/null || echo "pwsh: not installed"

# Theming & AI
echo -e "\n--- Theming & AI ---"
oh-my-posh --version 2>/dev/null || echo "oh-my-posh: check shell prompt"
ls -la ~/.claude/CLAUDE.md ~/.claude/settings.json 2>&1

# tmux
echo -e "\n--- tmux ---"
tmux -V
ls ~/.config/tmux/tmux.conf 2>&1
ls ~/.config/tmuxinator/*.yml 2>/dev/null | wc -l | xargs -I{} echo "tmuxinator sessions: {}"

echo -e "\n=== QUANTUM SYMLINK COUNT ==="
echo "In ~/.config/: $(ls -la ~/.config/ | grep -c dots-quantum)"
echo "In ~/: $(ls -la ~/ | grep -c dots-quantum)"

Expected Results

Check Expected

Shell symlinks

4 (zshrc, bashrc, gitconfig, vimrc) → dots-quantum

~/.config symlinks

20+ → dots-quantum

~/ symlinks

15+ → dots-quantum

tmuxinator sessions

39-40 YAML files

All apps respond

Version output (no errors)

Functional Tests

# Test tmux launches
tmux new-session -d -s test && tmux kill-session -t test && echo "tmux: OK"

# Test PDF opens (requires PDF file)
# zathura /path/to/test.pdf

# Test email client config
aerc --help | head -1

# Test file associations
xdg-mime query default application/pdf  # Should show zathura

# Test Hyprland reload (if in Hyprland session)
# hyprctl reload

Related Documents