Field Notes

Field Notes

2026-04-03: Build Notes

  • Built from scratch, not migrated — every line intentionally placed

  • Dropped tmux-sensible (all defaults explicit in core.conf)

  • Dropped tmux-copycat (replaced by tmux-thumbs in predecessor CR)

  • Conflict checker rewritten to be table-aware — tracks {table}:{key} tuples (prefix, root, copy-mode-vi, off). Same key in different tables is valid tmux behavior, not a conflict. The original naive checker reported 21 false positives.

  • Theme variable system (@theme-*) enables theme switching by changing one line in tmux.conf — all colors propagate automatically

2026-04-04: Post-Audit Fixes

  • C-l prefix-table self-conflict resolved (clear-screen kept, dead window-nav binding removed)

  • C-s conflict between popup session picker and tmux-resurrect resolved (picker moved to C-f)

  • Hardcoded hex colors in nested-tmux F12 toggle replaced with @theme-* variables

  • Version guard added for popups.conf (requires 3.2+)

  • theme-switcher.sh path references updated from 02_THEMES/ to themes/ (missed during initial copy from tmux-config)

  • Claude Code project tooling added: rule, validator agent, /tmux-qa and /session skills

2026-04-04: Validation & Deployment

  • Deployed on Hyprland/Arch — all 7 validation steps passed

  • F12 → F10: Hyprland intercepts F12 (brightness toggle). Changed nested tmux key to F10.

  • Theme switcher fix: comment/uncomment strategy assumed multiple theme lines in tmux.conf. tmux-quantum has a single line. Replaced with direct sed substitution.

  • ~/.config/tmux was a directory (tmux-config repo), not a symlink. ln -sf created a link inside the directory. Required rm -rf + fresh symlink. Deployment docs updated with Path A/B detection and validation gates.

  • Preferred theme: solar-flare

2026-04-05: Open-Source Refinement

  • Clipboard fix: gopass show -c failed inside tmux — wl-copy couldn’t find the Wayland socket because XDG_RUNTIME_DIR was missing from update-environment in core.conf. Also added DBUS_SESSION_BUS_ADDRESS for D-Bus-dependent tools. Verified by injecting vars into running session without killing server. Deep dive into the kernel primitives behind these variables: Kernel IPC Mastery.

  • OSS preparation: Added LICENSE (MIT), CONTRIBUTING.adoc, local.conf.example. Extracted 6 personal ~/atelier navigation bindings from sessions.conf to local.conf (gitignored). Updated install docs to generic git clone.

  • Doc fixes: F12 → F10 in quickstart.adoc (was already correct everywhere else). Binding count updated from 150+ to 360+.

  • Related CR: CR-2026-04-05

Lessons Learned

Date Lesson Prevention

2026-04-04

ln -sf on an existing directory creates a symlink inside the directory instead of replacing it. First deployment attempt left tmux-config active with a tmux-quantum symlink buried inside it. Both ~/.config/tmux and ~/.config/tmuxinator were affected.

Always run file <path> before ln -sf to determine if the target is a directory or symlink. If directory: rm -rf first, then ln -sf. Documented in Deployment with explicit Path A / Path B instructions.

2026-04-04

F12 nested tmux toggle was intercepted by Hyprland before reaching tmux. Status bar went dark (Hyprland’s response) but no OFF badge appeared and input was blocked. Misdiagnosed as a tmux format string issue until testing confirmed the key never arrived.

Test keybindings that use function keys on the target window manager BEFORE documenting them. Changed to F10. If another WM claims F10, the key is configurable in lib/sessions.conf.

2026-04-04

02_THEMES path in theme-switcher.sh survived the copy from tmux-config because scripts were batch-copied without auditing internal path references. The script was completely non-functional.

After copying scripts between projects, grep for predecessor path patterns (02_THEMES, 05_SNIPPETS, numbered directory prefixes) before committing.

2026-04-04

C-s popup session picker was silently overwritten by tmux-resurrect’s C-s save binding. TPM loads last, so plugin bindings win. The dead binding went unnoticed because help.sh documented both without flagging the conflict.

When binding a key in lib/ modules, grep plugins/tpm.conf comments for the same key. Plugin defaults occupy the prefix table and load after all lib/ modules.

2026-04-05

update-environment only propagates variables to new sessions. Fixing core.conf and sourcing the config does nothing for the running server’s environment. tmux kill-server would work but destroys all active sessions. The correct live workaround is tmux set-environment VAR "$VAR" for each missing variable — new panes inherit immediately, no restart required.

When adding variables to update-environment, always pair the config change with tmux set-environment commands for the running server. Document both the permanent fix and the live workaround.

Improvement Proposals

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

P1

Expand from 2 pages to 5+ with implementation phases

Currently the most nascent directory project (2 pages, 4 partials). The config is production-grade but the documentation doesn’t reflect the depth.

L

P1

Document decision log (why quantum over base tmux-config)

tmux-quantum was a ground-up rewrite, not an evolution. The rationale for rewriting vs iterating is not documented and will be questioned.

M

P2

Add troubleshooting guide for common issues

Nested tmux (F12 toggle), plugin conflicts, theme variable propagation, and session template issues all need documented resolution paths.

M

P2

VM validation checklist formalization

The current checklist in field-notes is good but should become a standalone partial reusable by tmux-config and dots-quantum.

S