CR: tmux-quantum Creation

1. Change Summary

Field Value

CR ID

CR-2026-04-03-tmux-quantum-creation

Date

2026-04-03

Priority

P1 - High

Type

New Project / Configuration Architecture

Status

Complete

Requestor

Evan Rosado

Implementor

Evan Rosado

Risk Level

Low (new project, no existing system modified)

Systems Affected

~/.config/tmux (replaces tmux-config symlink)

Predecessor

tmux-config (kept as archive)

Related CR

CR-2026-04-03-tmux-config-evolution

2. Objective

Create a from-scratch tmux configuration built on one rule: each keybinding exists in exactly one file, each file owns exactly one domain. The predecessor tmux-config had 6+ keybinding duplications across 3 files, a self-conflict (C-n), and plugin config scattered between 2 files. tmux-quantum eliminates all of this through library-style architecture.

3. Background

The tmux-config repo served well as a learning vehicle but accumulated architectural debt:

  • Keybindings duplicated across keybindings.conf, enhanced-keybindings.conf, and pane-management.conf (silent last-one-wins overrides)

  • C-n bound to two different actions within the same file

  • Plugin config split between plugins.conf and enhanced-statusline.conf

  • 05_SNIPPETS/ was a junk drawer mixing clipboard, nested tmux, statusline, keybindings, and pane ops

  • No conflict detection tooling

Rather than fix these in-place, a clean build was warranted.

4. Architecture

tmux-quantum/
├── tmux.conf              Entry point
├── lib/                   Composable modules (9 files)
│   ├── core.conf          Terminal, prefix, settings (NO keybindings)
│   ├── vim.conf           ALL navigation + copy mode
│   ├── mouse.conf         Mouse support
│   ├── clipboard.conf     Platform-detected clipboard
│   ├── panes.conf         Splits, resize, zoom, layouts
│   ├── sessions.conf      Session management, nested tmux
│   ├── popups.conf        Popup workflows (lazygit, yazi, fzf)
│   ├── status.conf        Status bar (uses @theme-* variables)
│   └── modern.conf        tmux 3.2+ features
├── themes/                Color schemes as @theme-* variable exports
├── plugins/tpm.conf       ALL plugin config in ONE file
├── scripts/               Status bar, help, conflict checker
├── sessions/              Tmuxinator YAML templates
└── docs/                  AsciiDoc documentation

5. Design Principles

Principle Implementation

One domain, one file

Each keybinding exists in exactly one lib/ module

No silent overrides

Verified by scripts/check-conflicts.sh

Theme as variables

Themes export @theme-* options; status bar references them

Plugin config consolidated

ALL plugin settings in plugins/tpm.conf

Quote special characters

Backtick and tilde quoted in bind-key directives

6. What Carries Over from tmux-config

  • All working keybindings (deduplicated, placed in correct module)

  • Theme color palettes (restructured as variable exports)

  • Status bar scripts (atelier paths)

  • Plugin list (minus tmux-sensible and tmux-copycat)

  • Tmuxinator sessions (26 YAML files)

  • Modern features (extended-keys, passthrough, popups)

7. What Gets Dropped

  • All keybinding duplication (6+ overlaps eliminated)

  • The C-n self-conflict

  • Scattered plugin config

  • Numbered directory prefixes (replaced by semantic names)

  • The "snippets" abstraction

  • tmux-sensible plugin (defaults set explicitly in core.conf)

8. File Inventory

Category Count Details

Entry point

1

tmux.conf

Library modules

9

lib/*.conf

Themes

3

themes/*.conf

Plugins

1

plugins/tpm.conf

Scripts

6

scripts/*.sh

Sessions

26

sessions/*.yml

Docs

4

docs/*.adoc

Meta

3

CLAUDE.md, README.adoc, .gitignore

Total

52

9. Deployment

rm -f ~/.config/tmux
ln -sf ~/atelier/_projects/personal/tmux-quantum ~/.config/tmux
ln -sf ~/.config/tmux/sessions ~/.config/tmuxinator
tmux source-file ~/.config/tmux/tmux.conf
# prefix + I to install plugins

10. Rollback

Re-symlink to tmux-config:

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

11. Related

12. Changelog

Date Author Change

2026-04-03

Evan Rosado

Initial CR — 52-file library-style tmux config built from scratch