CR: Tmux Configuration Evolution

1. Change Summary

Field Value

CR ID

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

Date

2026-04-03

Priority

P2 - Medium

Type

Configuration Evolution / Documentation

Status

Approved

Requestor

Evan Rosado

Implementor

Evan Rosado

Risk Level

Low

Rollback Time

< 5 minutes (git revert per phase)

Systems Affected

tmux-config (~/.config/tmux)

Related CR

CR-2026-03-25-tmux-config-remediation

2. Objective

Evolve the tmux-config repository to match advanced vim+tmux proficiency gained over the past month. Close out the predecessor CR-2026-03-25-tmux-config-remediation, modernize the plugin stack, enable tmux 3.2+ features, add advanced keybinding workflows, and create parallel AsciiDoc documentation alongside the existing markdown.

3. Background

CR-2026-03-25-tmux-config-remediation addressed critical and high-priority issues (TPM path, keybinding conflicts, stale paths in enhanced-keybindings.conf, duplicate settings). Most fixes were applied, but several items remain:

  • tmux-status-project.sh still maps the old opus-workspace directory structure

  • tmux-help.sh references stale area names and paths

  • nested-tmux.conf sources files from ~/.tmux/ that do not exist

  • README.md in 05_SNIPPETS/ references old structure throughout

  • The "Optional Enhancements (Future)" section of the predecessor CR was never executed

The user has progressed from beginner to advanced vim+tmux user and the configuration should reflect that growth. The documentation ecosystem has also shifted from markdown to AsciiDoc (Antora).

4. Scope

4.1. In Scope

  • Phase 0: AsciiDoc documentation bootstrap (parallel to markdown)

  • Phase 1: Remediation closeout (CR-2026-03-25 remaining items)

  • Phase 2: Plugin modernization (replace unmaintained tmux-copycat)

  • Phase 3: tmux 3.2+ features (extended-keys, passthrough, popup styling)

  • Phase 4: Keybinding evolution (advanced popup workflows)

4.2. Out of Scope

  • Full markdown-to-AsciiDoc migration (user-initiated, future)

  • Tmuxinator session config changes

  • dots-quantum tmux package changes (separate CR if needed)

  • Successor tmux project (separate initiative)

5. Current State vs Target State

Area Current State Target State

Documentation

16 markdown files in 00_META/

AsciiDoc docs in 00_META/adoc/ alongside markdown

Plugins

tmux-copycat (unmaintained since 2020)

tmux-thumbs (Rust, actively maintained)

tmux Features

No 3.2+ features enabled

extended-keys, allow-passthrough, popup styling

Keybindings

Basic workflows, no popup integration

Advanced popups (lazygit, yazi, fzf session picker)

Script References

Stale opus-workspace paths in scripts and help

Updated to atelier directory structure

Project Metadata

No CLAUDE.md

CLAUDE.md at repo root

6. Implementation Plan

6.1. Phase 0: AsciiDoc Bootstrap

# Task File

0.1

Create lean AsciiDoc docs (index, quickstart, keybinding-reference, architecture, plugin-guide)

00_META/adoc/

0.2

Create CLAUDE.md with repo structure and conventions

CLAUDE.md

6.2. Phase 1: Remediation Closeout

# Task File

1.1

Fix config reload path (~/.tmux.conf → ~/.config/tmux/tmux.conf)

keybindings.conf:5

1.2

Rewrite opus-workspace area mappings to atelier

tmux-status-project.sh

1.3

Update stale references in help text

tmux-help.sh

1.4

Comment out broken source-file lines

nested-tmux.conf:5-7

1.5

Replace opus-workspace references throughout

05_SNIPPETS/README.md

6.3. Phase 2: Plugin Modernization

# Task File

2.1

Remove tmux-copycat plugin and config block

plugins.conf

2.2

Add tmux-thumbs with Wayland clipboard integration

plugins.conf

6.4. Phase 3: Modern Features (tmux 3.6a)

# Task File

3.1

Create modern-features.conf (extended-keys, passthrough, popup styling)

05_SNIPPETS/modern-features.conf

3.2

Add version-conditional source line

tmux.conf

6.5. Phase 4: Keybinding Evolution

# Task File

4.1

Resolve keybinding conflicts (backtick, g)

pane-management.conf

4.2

Add popup workflows (lazygit, yazi, fzf session picker, scratchpad)

enhanced-keybindings.conf

4.3

Replace old notes binding with popup version

keybindings.conf:124

7. Risk Assessment

Risk Likelihood Impact Mitigation

Breaking existing keybindings

Medium

Medium

Test each change in isolation, per-phase commits enable surgical rollback

Plugin removal causing workflow regression

Low

Medium

Install tmux-thumbs before removing tmux-copycat in same commit

AsciiDoc docs diverging from markdown

Low

Low

Parallel only — markdown stays until user explicitly deprecates

tmux-thumbs Rust compilation failure

Low

Low

Fallback to tmux-fingers (Python) or skip replacement

8. Rollback Procedure

8.1. Trigger Conditions

Rollback if:

  • tmux fails to start or source config

  • Critical keybindings broken

  • Status bar not rendering

8.2. Rollback Steps

Each phase is an independent commit. Rollback any phase without affecting others:

# Revert specific phase commit
git -C ~/.config/tmux log --oneline -5
git -C ~/.config/tmux revert <commit-hash>

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

9. Related

10. Changelog

Date Author Change

2026-04-03

Evan Rosado

Initial CR created — supersedes Optional Enhancements from CR-2026-03-25

2026-04-03

Evan Rosado

All phases (0-4) implemented. Deployment scope creep: discovered dots-quantum stowed a separate monolithic config to ~/.config/tmux/tmux.conf, blocking the modular repo. Resolved by symlinking entire repo. Tilde expansion bug in bind-key ~ fixed (must quote as '~'). TPM + tmux-thumbs installed via precompiled binary.