CR: Tmux Configuration Remediation

Change Summary

Change ID

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

Type

Configuration Quality / Technical Debt

Priority

P2 - Medium

Status

In Progress (Implementation Complete)

Requested

2026-03-25

Owner

Evan Rosado

Risk Level

Low

Rollback Time

< 5 minutes (git revert)

Systems Affected

tmux-config (~/.config/tmux)

Background

Code review of the tmux-config repository revealed several issues affecting maintainability and functionality:

  • Critical: TPM plugin path mismatch between configuration files

  • High: Duplicate keybindings causing conflicts (last binding wins)

  • High: Stale paths referencing non-existent directories

  • Medium: Duplicate settings causing confusion

  • Low: Missing modern tmux 3.2+ features

Scope

Repository

/home/evanusmodestus/atelier/_projects/personal/tmux-config

Files Affected

File Changes Required

tmux.conf

Fix TPM path (line 46)

01_CORE/base.conf

Remove duplicate focus-events setting

01_CORE/keybindings.conf

Resolve N keybinding conflict

05_SNIPPETS/enhanced-keybindings.conf

Fix script path, update stale paths, remove duplicate clipboard

05_SNIPPETS/enhanced-statusline.conf

Increase status-interval for performance

Critical Findings (P0)

1. TPM Path Mismatch

Severity: PLUGIN LOADING FAILURE RISK

Issue: Configuration files reference two different TPM locations:

plugins.conf:5
set-environment -g TMUX_PLUGIN_MANAGER_PATH '~/.config/tmux/plugins'
tmux.conf:46
run '~/.tmux/plugins/tpm/tpm'  # WRONG - legacy location

Fix: Standardize on ~/.config/tmux/plugins/tpm/tpm

2. Duplicate Keybinding: N

Severity: KEYBINDING CONFLICT

File: 01_CORE/keybindings.conf

Issue: N is bound twice - last binding wins, first is silently overwritten:

bind N select-layout main-vertical  # line 97 - OVERWRITTEN
bind N new-session                   # line 100 - WINS

Fix: Change main-vertical to different key (suggest F for "Full vertical")

High Priority Findings (P1)

3. Wrong Script Path

File: 05_SNIPPETS/enhanced-keybindings.conf:106

Current (broken)
"~/.config/tmux/config/03_SCRIPTS/tmux-help.sh | less"
Correct
"~/.config/tmux/03_SCRIPTS/tmux-help.sh | less"

4. Stale Paths

File: 05_SNIPPETS/enhanced-keybindings.conf:9-16

Issue: References ~/opus-workspace which doesn’t exist. Current structure uses ~/atelier.

Current
bind-key -n M-w run-shell "tmux neww -c ~/opus-workspace"
bind-key -n M-a run-shell "tmux neww -c ~/opus-workspace/_apparatus"
bind-key -n M-p run-shell "tmux neww -c ~/opus-workspace/projecta"
bind-key C-d neww -c ~/opus-workspace/_apparatus/unix/dotfiles
bind-key C-n neww -c ~/opus-workspace/_apparatus/omnia/instrumentum-nvim
bind-key C-t neww -c ~/opus-workspace/_apparatus/unix/tmux-config
Fixed
bind-key -n M-w run-shell "tmux neww -c ~/atelier"
bind-key -n M-a run-shell "tmux neww -c ~/atelier/_projects"
bind-key -n M-p run-shell "tmux neww -c ~/atelier/_projects/personal"
bind-key C-d neww -c ~/atelier/_projects/personal/dotfiles
bind-key C-n neww -c ~/atelier/_projects/personal/domus-nvim
bind-key C-t neww -c ~/atelier/_projects/personal/tmux-config

5. Hardcoded Clipboard (Conflicts with clipboard.conf)

File: 05_SNIPPETS/enhanced-keybindings.conf:113-117

Issue: Hardcodes xclip, ignoring the cross-platform detection in clipboard.conf.

Current (hardcoded)
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
bind-key C-v run "tmux set-buffer \"$(xclip -out -selection clipboard)\"; tmux paste-buffer"

Fix: Remove entirely - tmux-yank plugin and clipboard.conf handle this correctly.

Medium Priority Findings (P2)

6. Duplicate Settings

Setting First Location Duplicate Location

focus-events on

base.conf:24

base.conf:64

display-time

base.conf:74

enhanced-statusline.conf:123

display-panes-time

base.conf:73

enhanced-statusline.conf:124

monitor-activity

base.conf:33

enhanced-statusline.conf:88

Fix: Remove duplicates from enhanced-statusline.conf (base.conf is authoritative).

7. Status Refresh Too Frequent

File: 05_SNIPPETS/enhanced-statusline.conf:14

Current
set -g status-interval 2  # Calls shell scripts every 2 seconds
Recommended
set -g status-interval 5  # Reduce CPU overhead

8. Additional Duplicate Keybindings

Key Location 1 Location 2

S

keybindings.conf:86 (sync-panes)

enhanced-keybindings.conf:137 (sync-panes)

|

keybindings.conf:8

enhanced-keybindings.conf:23

z

default tmux (zoom)

enhanced-keybindings.conf:38 (zoom + message)

Note: These are benign - later definitions simply override with enhanced behavior. Document for clarity.

Remediation Plan

Phase 1: Critical Fixes

# Task File

1.1

Change TPM path from ~/.tmux/plugins/tpm/tpm to ~/.config/tmux/plugins/tpm/tpm

tmux.conf:46

1.2

Change bind N select-layout main-vertical to bind F select-layout main-vertical

keybindings.conf:97

Phase 2: High Priority Fixes

# Task File

2.1

Remove /config/ from script path

enhanced-keybindings.conf:106

2.2

Update 6 stale opus-workspace paths to atelier

enhanced-keybindings.conf:9-16

2.3

Remove hardcoded clipboard bindings (lines 113-117)

enhanced-keybindings.conf

Phase 3: Medium Priority Fixes

# Task File

3.1

Remove duplicate set -g focus-events on at line 64

base.conf

3.2

Remove duplicate display-time, display-panes-time, monitor-activity

enhanced-statusline.conf

3.3

Change status-interval from 2 to 5

enhanced-statusline.conf:14

Pre-Change Checklist

  • Current tmux config working

  • Git status clean

  • No active sessions depend on specific keybindings

Current State Capture

# Verify current working state
tmux source-file ~/.config/tmux/tmux.conf
tmux list-keys | wc -l
tmux show-options -g | grep -E "status-interval|focus-events"

Post-Change Validation

Functionality Tests

  • tmux source-file ~/.config/tmux/tmux.conf - no errors

  • Prefix+F triggers main-vertical layout

  • Prefix+N creates new session

  • Prefix+/ opens help popup

  • Alt+w opens new window at ~/atelier

  • Copy/paste works (select text, y to yank, Prefix+P to paste)

Verification Commands

# Reload and check for errors
tmux source-file ~/.config/tmux/tmux.conf

# Verify N is now new-session only
tmux list-keys | grep "bind-key.*N"

# Verify F is main-vertical
tmux list-keys | grep "bind-key.*F"

# Check status interval
tmux show-options -g status-interval

Rollback Procedure

Trigger Conditions

Rollback if:

  • Tmux fails to start

  • Critical keybindings broken

  • Status bar not rendering

Rollback Steps

cd ~/.config/tmux
git checkout HEAD~1 -- .
tmux source-file ~/.config/tmux/tmux.conf

Optional Enhancements (Future)

Not in scope for this CR, but recommended for future:

Enhancement Description

Modern tmux 3.2+ features

Add extended-keys on, allow-passthrough on, popup-border-lines rounded

Replace tmux-copycat

Unmaintained - consider tmux-thumbs or tmux-fingers

Status script caching

Cache system metrics results to reduce subprocess overhead

Related Documentation

Changelog

Date Author Change

2026-03-25

Evan Rosado

Initial CR created from code review