Skip to content

012. Tmux UX and Clipboard Integration Strategy

Date: 2026-02-15

Status

Accepted

Context

Tmux behavior and clipboard handling were split across multiple locations with duplicated backend detection logic. This led to:

  1. Inconsistent copy/paste behavior between shell and tmux plugin flows.
  2. Keybinding conflicts that made tmux copy/yank behavior less intuitive.
  3. Higher maintenance cost due to drift between alias logic and tmux plugin commands.
  4. Weak diagnostics for clipboard failures during setup/doctor runs.

At the same time, default auto-attach behavior in shell startup would risk disrupting IDE terminals, CI, and non-interactive workflows.

Decision

We standardize tmux UX and clipboard integration with these rules:

  1. Unified Clipboard Backend
  2. Introduce one helper script: ~/.local/bin/clipboard (managed from dot_local/bin/executable_clipboard).

  3. Route both shell aliases (copy, cbpaste) and tmux thumbs copy commands through this helper.

  4. Intuitive Tmux Copy/Paste

  5. Keep copy-mode vi flow (v, y, Enter) and mouse-copy behavior.
  6. Reserve Prefix + y for yank semantics and move synchronize panes to Prefix + Y.

  7. Add explicit paste shortcuts: Prefix + p (paste latest), Prefix + P (choose buffer).

  8. Operational Diagnostics

  9. Add clipboard helper/backend checks to mise run doctor.

  10. Report detected backend (xclip, wayland, macos, wsl, win32yank) with actionable warnings.

  11. Auto-Attach Policy

  12. Keep tmux auto-attach as opt-in only.
  13. Do not auto-attach by default in shell startup.

Consequences

Positive

  • Copy/paste behavior is consistent across shell and tmux.
  • Tmux interaction is more predictable for daily usage.
  • Clipboard troubleshooting is faster with explicit doctor diagnostics.
  • Reduced duplication and lower long-term maintenance burden.
  • Avoids accidental shell/session hijacking from default auto-attach.

Negative

  • Adds one managed helper script to maintain.
  • Slightly more indirection for clipboard commands.

Compliance

  • Idempotent with chezmoi-managed files.
  • Cross-platform backend handling (Linux/Wayland/macOS/WSL/win32yank).
  • Doctor diagnostics added.
  • Test coverage added for tmux and alias integration.