Decision Log

Keybinding duplication

6+ bindings duplicated across 3 files in tmux-config. Fixing one required auditing all three. The file boundaries didn’t align with functional domains.

File organization

tmux-config used numbered directories (01_CORE, 02_THEMES, 05_SNIPPETS). The numbering implied sourcing order but wasn’t enforced. 05_SNIPPETS was a junk drawer.

Plugin sprawl

Plugin config split between plugins.conf and statusline.conf. No single source of truth for what plugins were loaded or how they were configured.

No conflict detection

No tooling to catch keybinding collisions. The C-n self-conflict (same key bound twice in the same file) went unnoticed until manual audit.

Iteration cost

Fixing the structure incrementally would require renaming every file, rewriting every path reference, splitting monolithic configs, and adding new infrastructure — essentially a rewrite with extra steps.

File organization

Numbered directories (01_CORE/, 02_THEMES/, 05_SNIPPETS/)

Semantic directories (lib/, themes/, plugins/, scripts/)

Keybinding ownership

Distributed across files by convenience

One domain per file, strict boundary contracts

Conflict detection

None

check-conflicts.sh — table-aware, parses all binding tables

Plugin management

Split across 2 files

Consolidated in plugins/tpm.conf

Theme system

Hardcoded colors in multiple files

@theme-* variable exports, themes are pure data

Version guards

None

if-shell checks for 3.2+ features (popups, modern)

Status scripts

Embedded in config

Standalone scripts in scripts/ with caching

Session templates

Mixed with config

Dedicated sessions/ directory with naming conventions

Quality tooling

None

Claude Code rule, validator agent, /tmux-qa skill

Flat lib/ directory (no subdirectories)

9 files is manageable. Subdirectories add navigation overhead without benefit at this scale.

lib/navigation/, lib/ui/, etc.

Theme before modules in sourcing order

Modules reference @theme-* variables. Theme must be set before any module reads them.

Theme after all modules (would require lazy evaluation)

Popups version-guarded, sessions not

display-popup is 3.2+ only. Session management works on all versions.

Guard everything 3.0+

C-f for session picker (not C-s)

C-s is the community convention for tmux-resurrect save. Fighting it creates friction.

Keep C-s for picker, move resurrect to M-s

Clear-screen on C-l instead of window-next

C-l is the standard terminal clear key. Vim-aware navigation steals it, so C-a C-l restores it. Window navigation has M-1..9 (direct jump, no prefix).

Keep C-h/C-l pair for prev/next window

Status scripts skip set -e

A crashing status script breaks the status bar for every window. Silent failure is better than visible breakage on a 5-second interval.

set -e with trap (complex, still risky)