CR: tmux-quantum Open-Source Refinement

1. Change Summary

Field Value

CR ID

CR-2026-04-05-tmux-quantum-oss-refinement

Date

2026-04-05

Priority

P1 - High

Type

Bug Fix / Open-Source Preparation

Status

Complete

Requestor

Evan Rosado

Implementor

Evan Rosado

Risk Level

Low (additive changes, no destructive modifications)

Systems Affected

~/.config/tmux (tmux-quantum)

Predecessor

CR-2026-04-03-tmux-quantum-creation

Related CR

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

2. Objective

Fix a Wayland clipboard bug preventing gopass show -c from working inside tmux, and prepare the repository for open-source release by adding missing standard files and extracting personal paths.

3. Background

After one day of production use (including a reboot), tmux-quantum was stable with one critical issue: gopass show -c reported "No clipboard available" inside tmux while working correctly in bare Kitty terminal. Investigation confirmed the root cause was missing environment variables in tmux’s update-environment directive.

Simultaneously, the repository lacked standard open-source files (LICENSE, CONTRIBUTING) and contained hardcoded personal paths that would confuse external users.

4. Changes

4.1. Bug Fix: Wayland Clipboard in tmux

Root Cause: lib/core.conf line 31 included WAYLAND_DISPLAY in update-environment but omitted XDG_RUNTIME_DIR. Without XDG_RUNTIME_DIR (which points to /run/user/$UID/), wl-copy and wl-paste cannot locate the Wayland compositor socket. Additionally, DBUS_SESSION_BUS_ADDRESS was missing, which gopass needs for keyring/D-Bus access.

Fix: Added XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS to the update-environment directive in lib/core.conf. Added explanatory comment in lib/clipboard.conf documenting the dependency.

Live Workaround (no server restart): update-environment only takes effect for new sessions. Killing the tmux server was not an option — critical sessions were running. Instead, injected the missing variables into the running server:

tmux set-environment WAYLAND_DISPLAY "$WAYLAND_DISPLAY"
tmux set-environment XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR"
tmux set-environment DBUS_SESSION_BUS_ADDRESS "$DBUS_SESSION_BUS_ADDRESS"

New panes created after this immediately inherited the variables. Existing panes retained their original (broken) environment — only new panes pick up set-environment changes. This is a reusable pattern for any update-environment fix applied to a live tmux server.

Verification: Confirmed all three variables present in new pane, then gopass show -c succeeded immediately.

4.2. Open-Source Readiness

Change Detail

LICENSE

Created MIT license file (README already declared MIT but had no file)

CONTRIBUTING.adoc

Distilled project rules into contributor guidelines: one domain per file, conflict checker, theme variables, doc sync, version guards

local.conf.example

Template for machine-specific bindings with generic project paths

local.conf

Created with actual ~/atelier paths (gitignored — personal use)

lib/sessions.conf

Extracted 6 personal ~/atelier navigation bindings to local.conf, replaced with comment pointing to local.conf.example

README.adoc

Updated install to git clone, added Session Templates and Local Overrides sections

docs/quickstart.adoc

Fixed F12 → F10 (Hyprland intercept), fixed binding count 150+ → 360+, updated install path

.gitignore

Added .claude/settings.local.json

5. Files Modified

File Change

lib/core.conf

Added XDG_RUNTIME_DIR + DBUS_SESSION_BUS_ADDRESS to update-environment

lib/clipboard.conf

Added comment documenting Wayland environment dependency

lib/sessions.conf

Removed 6 personal path bindings, replaced with comment

docs/quickstart.adoc

Fixed F12→F10, binding count, install path

README.adoc

Updated install, added session templates + local overrides sections

.gitignore

Added .claude/settings.local.json

6. Files Created

File Purpose

LICENSE

MIT license (standard open-source requirement)

CONTRIBUTING.adoc

Contributor guidelines

local.conf.example

Template for personal path bindings

local.conf

Personal overrides (gitignored)

7. Rollback

All changes are additive. To revert:

# Revert clipboard fix
git -C ~/atelier/_projects/personal/tmux-quantum checkout lib/core.conf lib/clipboard.conf

# Revert sessions.conf (restores inline personal bindings)
git -C ~/atelier/_projects/personal/tmux-quantum checkout lib/sessions.conf

# Remove new files
rm LICENSE CONTRIBUTING.adoc local.conf.example local.conf

8. Related

9. Changelog

Date Author Change

2026-04-05

Evan Rosado

Initial CR — clipboard bug fix + open-source preparation (10 files touched)