CR: Tmux Configuration Evolution

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

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.

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).

Scope

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)

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)

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

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.