tmux-quantum

Project Summary

Field Value

PRJ ID

PRJ-2026-04-tmux-quantum

Owner

Evan Rosado

Priority

P1

Category

Developer Tooling

Status

Validated — 53 files, deployed on Hyprland/Arch

Repository

~/atelier/_projects/personal/tmux-quantum

tmux Version

3.6a

Architecture

Library-style: 9 lib/ modules, each owns one domain

Predecessor

tmux-config (kept as archive)

Related CR

CR-2026-04-03

Architecture

Design Rules

Rule 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; modules reference #{@theme-accent} not #8b5cf6

Plugin config consolidated

ALL plugin declarations and config in plugins/tpm.conf

Module Ownership

Module Owns Does Not Touch

core.conf

Terminal, prefix, indexes, history, shell

No keybindings

vim.conf

Pane/window navigation, copy mode, paste

No splits, resize, sessions

mouse.conf

Mouse events, scroll, click selection

No keyboard bindings

clipboard.conf

Platform detection, clipboard command

No copy mode keys

panes.conf

Splits, resize, zoom, mark, layouts

No navigation

sessions.conf

Session create/kill/find, nested tmux

No pane operations

popups.conf

All display-popup bindings

No core navigation

status.conf

Status bar format, window format

No keybindings (except toggle)

modern.conf

Extended keys, passthrough, popup style

No keybindings

Sourcing Order

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

Predecessor Pain Points Resolved

Problem in tmux-config Resolution in tmux-quantum

6+ keybindings duplicated across 3 files

Each key bound in exactly one module

C-n self-conflict (same file, two bindings)

Eliminated — C-n bound once in sessions.conf

Plugin config in plugins.conf AND statusline.conf

All plugin config in plugins/tpm.conf

"05_SNIPPETS" junk drawer

Replaced by semantic lib/ modules

No conflict detection

scripts/check-conflicts.sh — table-aware, catches same-table duplicates

Subsystems

  • Library Modules — 9 composable modules with strict domain boundaries

  • Keybindings — 121 bindings organized by domain and binding table

  • Themes — 3 variable-based themes with 15-variable contract

  • Scripts & Tooling — status bar scripts, conflict checker, Claude Code configurations

  • Deployment — installation, validation checklist, rollback, plugin reference

  • Decision Log — why rewrite instead of iterate

Metadata

Field Value

PRJ ID

PRJ-2026-04-tmux-quantum

Author

Evan Rosado

Created

2026-04-03

Last Updated

2026-04-04

Status

Validated — deployed on Hyprland/Arch

Files

53 (9 lib modules, 3 themes, 1 plugin config, 6 scripts, 25 sessions, 4 docs, 3 meta)

Related