Field Notes

Field Notes

2026-04-03: Deployment Discovery (Scope Creep)

The Onion

The CR assumed tmux-config repo was the live config. Implementation revealed multiple layers of mismatch:

Layer Discovery

1: TPM missing

tpm returned exit code 127 — TPM was never cloned into ~/.config/tmux/plugins/tpm/

2: TPM ignores new plugin

After installing TPM, prefix + I installed old plugin list (tmux-copycat still present, tmux-thumbs absent)

3: Wrong config deployed

~/.config/tmux/tmux.conf was a 21KB monolithic file from dots-quantum (stowed), not the modular repo. All edits to the tmux-config repo were invisible to the running tmux server.

4: Repo design assumption

The tmux-config repo was designed to BE ~/.config/tmux/ (clone directly to that path). Required symlinking the entire repo directory, not just tmux.conf.

5: Tilde expansion bug

bind-key ~ in pane-management.conf expanded ~ to /home/evanusmodestus during config parsing. tmux error: unknown key: /home/evanusmodestus. Fix: quote the tilde as bind-key '~'.

Root Cause

dots-quantum owns ~/.config/tmux/tmux.conf via stow. The tmux-config repo is a separate project that was never deployed. The CR’s scope did not include deployment verification — it assumed the repo files were the live config.

Resolution

# Remove dots-quantum's stowed config
rm -rf ~/.config/tmux

# Symlink entire repo as ~/.config/tmux
ln -sf ~/atelier/_projects/personal/tmux-config ~/.config/tmux

# Reload + install plugins
tmux source-file ~/.config/tmux/tmux.conf
~/.config/tmux/plugins/tpm/bin/install_plugins

Lessons Learned

  • Always verify deployment path first. Before editing config files, confirm which file the service actually loads. ls -la the deployed path.

  • dots-quantum and tmux-config are separate. dots-quantum stows a consolidated single-file config. tmux-config is the modular development repo. They are not the same and must not be conflated.

  • Quote special characters in tmux bindings. Tilde (~), backtick ( ` ), and other shell-expandable characters must be single-quoted in bind-key directives.

  • TPM reads config files, not tmux server state. Plugin list comes from grep-ing the config file hierarchy, not from show-options. If TPM reads the wrong tmux.conf, it installs the wrong plugin set.

  • Add deployment verification to all tmux CRs. Future change requests must include a pre-change step: ls -la ~/.config/tmux/tmux.conf to confirm which config is active.

Prevention: CR Pre-Change Checklist Addition

All future tmux-config CRs must include:

# Verify active config is the tmux-config repo (not dots-quantum)
readlink -f ~/.config/tmux
# Expected: /home/evanusmodestus/atelier/_projects/personal/tmux-config

Improvement Proposals

Proposals from ecosystem audit — 2026-04-04. For team review and prioritization.
Priority Proposal Rationale Effort

P1

Add keybinding reference matrix (current bindings vs defaults)

Custom bindings diverge significantly from tmux defaults. A side-by-side matrix enables quick lookup and onboarding.

M

P2

Plugin comparison table (what each plugin does, overlaps)

Multiple plugins provide similar functionality (e.g., tmux-fingers vs tmux-thumbs). A comparison table documents the selection rationale.

S

P2

Add architecture diagram (session/window/pane hierarchy)

The modular config structure (core.conf, pane-management.conf, themes/) is non-obvious. A visual showing how files compose into the running tmux environment aids understanding.

S

P3

Performance profiling (startup time, plugin load times)

Quantify the cost of each plugin and config module. Identify optimization opportunities for slow-starting sessions.

S