shipwright-cli 2.0.0 → 2.1.0

package/docs/tmux-research/TMUX-BEST-PRACTICES-2025-2026.md

@@ -0,0 +1,829 @@
+# Best-in-Class tmux Configuration Report 2025-2026
+
+**Date**: February 2026
+**Scope**: Modern tmux configurations, plugins, patterns, and integrations for developers and AI agent workflows
+
+---
+
+## Executive Summary
+
+tmux in 2025-2026 has evolved from a terminal multiplexer for remote server access to a full-featured **terminal-native IDE replacement**. The most compelling use cases now involve:
+
+- **Multi-agent AI workflows**: Parallel Claude Code sessions with git worktrees + tmux windows
+- **Persistent development environments**: Session resurrection across restarts with tmux-continuum
+- **Seamless Neovim integration**: vim-tmux-navigator + Neovim AI plugins (claude-code.nvim, sidekick.nvim)
+- **Floating popup workflows**: Quick tasks without disrupting main layout (display-popup, fzf integration)
+- **DORA metrics monitoring**: Real-time pipeline vitals in tmux status line
+
+---
+
+## 1. Core Configuration Patterns
+
+### 1.1 The Gold Standard: Oh My Tmux! (gpakosz/.tmux)
+
+**Status**: Actively maintained as of 2025, 100+ contributors
+**Philosophy**: Never edit the main config; customize via `.tmux.conf.local`
+
+**Why it's best-in-class**:
+
+- Dual prefix support (C-a + C-b)
+- Powerline-inspired theming with custom separators
+- Pane maximization without losing splits
+- SSH-aware status line
+- Vim-style keybindings out of the box
+
+**Install**:
+
+```bash
+git clone https://github.com/gpakosz/.tmux.git ~/.tmux
+ln -s -f ~/.tmux/.tmux.conf ~/.tmux.conf
+cp ~/.tmux/.tmux.conf.local ~/.tmux.conf.local  # Customize this file only
+```
+
+### 1.2 Essential Core Configuration Snippet
+
+```tmux
+# ~/.tmux.conf or ~/.tmux.conf.local
+
+# Platform compatibility with conditional configuration
+%if "#{==:#{client_termname},screen}"
+  # Fallback for older terminals
+  set -g default-terminal "screen-256color"
+%else
+  # Modern terminal with TrueColor support
+  set -g default-terminal "xterm-256color"
+  set -as terminal-overrides ",xterm*:RGB"
+%endif
+
+# Prefix and basic bindings
+unbind C-b
+set -g prefix C-a
+bind C-a send-prefix
+set -g prefix2 C-b  # Secondary prefix for nested sessions
+
+# Core performance settings
+set -g escape-time 0           # Critical for Neovim responsiveness
+set -g history-limit 250000    # Claude Code generates high output volume
+set -g buffer-limit 20         # Keep memory usage reasonable
+set -g mouse on                # Toggle with: prefix + m
+
+# DEC 2026 synchronized output (eliminates TUI flicker)
+set -g allow-passthrough on
+
+# Extended keys for TUI apps (Alt combos work correctly)
+set -g extended-keys on
+
+# Focus events for TUI apps (responsive to window focus)
+set -g focus-events on
+
+# Clipboard integration (OSC 52 - works across SSH and nesting)
+set -g set-clipboard on
+
+# Key mode configuration
+setw -g mode-keys vi
+setw -g status-keys emacs      # Insert-style completion in command mode
+```
+
+### 1.3 Conditional Version Detection
+
+```tmux
+# Check tmux version and gate features accordingly
+run-shell "tmux setenv -g TMUX_VERSION $(tmux -V | cut -d' ' -f2)"
+
+# Version-gated configuration
+%if "#{>=:#{version},3.1}"
+  # tmux 3.1+ features (popup windows, better hooks)
+  set -g pane-border-status top
+  set -g pane-border-format "#{pane_index}: #{pane_title}"
+%endif
+
+%if "#{>=:#{version},3.2}"
+  # tmux 3.2+ features (enhanced popup, display-popup improvements)
+  # Floating scratch terminal
+  bind -n C-g display-popup -E -h 50% -w 80% -x C -y S \
+    "cd '#{pane_current_path}' && $SHELL"
+%endif
+```
+
+---
+
+## 2. Status Line Best Practices (Minimal & Informative)
+
+### 2.1 Philosophy: Less is More
+
+**Key principles**:
+
+- Display only information you glance at: session name, window list, time
+- Avoid status line fatigue with colors/animations
+- Keep update frequency low to reduce CPU
+
+### 2.2 Production Status Line Configuration
+
+```tmux
+# Status bar appearance
+set -g status-position top
+set -g status-style "bg=#1e1e2e,fg=#a6adc8"
+set -g status-left-length 50
+set -g status-right-length 100
+
+# Left: Session name + branch indicator
+set -g status-left "#{?session_grouped,#[fg=#f38ba8],} #{session_name} "
+
+# Right: System info (minimal)
+set -g status-right "#(whoami)@#{hostname_ssh} │ %H:%M #[fg=#7aa2f7](%a)#[default]"
+
+# Center: Window list with current pane indicator
+set -g window-status-format " #I:#W#{?window_zoomed_flag,🔍,} "
+set -g window-status-current-format "#[bg=#45475a,bold,fg=#a6adc8] #I:#W#{?window_zoomed_flag,🔍,} #[default]"
+set -g window-status-last-style "fg=#6c7086"
+
+# Status bar update frequency (reduce CPU by checking less often)
+set -g status-interval 5
+
+# Disable status bar by default, enable in specific scenarios
+# set -g status off
+# bind -n C-s set -g status  # Toggle status on demand
+
+# Battery indicator (if running on laptop)
+# Requires: brew install battery or apt-get install acpi
+# set -g status-right "#{battery_percentage} │ #(date '+%a %H:%M')"
+```
+
+### 2.3 Minimal Theme for Neovim Integration
+
+```tmux
+# Minimalist status line for Neovim workflows
+# (Vim takes up visual real estate, minimize tmux competition)
+
+set -g status-style "bg=#0a0e27,fg=#abb2bf"
+set -g status-left "#[fg=#61afef,bold]#{session_name}#[default] "
+set -g status-right "#[fg=#98c379]%H:%M#[default]"
+set -g status-justify left
+
+# Hide pane borders unless zoomed
+set -g pane-border-style "fg=#3b4048"
+set -g pane-active-border-style "fg=#61afef,bold"
+set -g pane-border-status off
+set -g pane-border-indicators off
+```
+
+---
+
+## 3. Advanced Features
+
+### 3.1 Tmux Hooks for Automation
+
+**Available hooks** (tmux 2.4+):
+
+```tmux
+# Session lifecycle hooks
+set-hook -g session-created 'display-message "Session #{session_name} created"'
+set-hook -g session-closed 'display-message "Session #{session_name} closed"'
+
+# Window/pane lifecycle
+set-hook -g window-linked 'display-message "Window #{window_index} linked"'
+set-hook -g pane-exited 'display-message "Pane exited with code: #{pane_exit_status}"'
+
+# Smart automation: Auto-rename windows to match current command
+set-hook -g pane-mode-changed 'select-window -t #{window_index}'
+set -g automatic-rename on
+set -g automatic-rename-format "#{pane_current_command}#{?pane_in_mode,[#{pane_mode}],}"
+
+# Agent-team pattern: Auto-create a heartbeat pane on new session
+set-hook -g after-new-session 'new-window -t #{session_name} -n "heartbeat" "watch -n 1 date"'
+```
+
+**Important caveat**: `pane-exited` only fires if `remain-on-exit` is off and the pane process actually exits (not forcibly killed).
+
+### 3.2 Copy-Mode Optimization for TUI Apps
+
+```tmux
+# Copy mode bindings (vi-style)
+bind -T copy-mode-vi v send-keys -X begin-selection
+bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel
+bind -T copy-mode-vi Y send-keys -X copy-line
+bind -T copy-mode-vi H send-keys -X start-of-line
+bind -T copy-mode-vi L send-keys -X end-of-line
+bind -T copy-mode-vi C-b send-keys -X page-up
+bind -T copy-mode-vi C-f send-keys -X page-down
+bind -T copy-mode-vi C-d send-keys -X halfpage-down
+bind -T copy-mode-vi C-u send-keys -X halfpage-up
+
+# Critical for TUI: Don't interfere with mouse selection in focused panes
+# Users must hold Shift to select text across pane boundaries
+set -g mouse on
+# Note: With mouse on, Shift+drag selects and bypasses tmux capture
+
+# Enhanced copy with system clipboard integration
+# Requires: xclip (Linux) or pbcopy (macOS)
+%if "#{==:#{client_platform},darwin}"
+  # macOS
+  bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
+  bind -T copy-mode-vi Y send-keys -X copy-pipe-and-cancel "pbcopy"
+%else
+  # Linux (requires: apt-get install xclip)
+  bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
+  bind -T copy-mode-vi Y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
+%endif
+
+# Scroll wheel behavior in copy mode
+bind -n WheelUpPane select-window -t:= \; send-keys -M -t:= -X scroll-up
+bind -n WheelDownPane select-window -t:= \; send-keys -M -t:= -X scroll-down
+```
+
+### 3.3 Floating Popup Windows (display-popup)
+
+**Requires**: tmux 3.2+
+
+```tmux
+# Floating scratch terminal
+bind -n C-g display-popup -E -h 60% -w 80% -x C -y S \
+  "cd #{pane_current_path} && $SHELL"
+
+# Floating git status
+bind -n C-j display-popup -E -h 40% -w 100% -x 0 -y S \
+  "cd #{pane_current_path} && git status"
+
+# Floating fzf session switcher
+bind -n C-s display-popup -E -h 50% -w 80% -x C -y C \
+  "tmux list-sessions | grep -v '^#{session_name}' | cut -d: -f1 | fzf --preview 'tmux capture-pane -t {} -p' | xargs -r tmux switch-client -t"
+
+# Floating command history with fzf
+bind -n C-h display-popup -E -h 60% -w 80% -x C -y C \
+  "history 1 | fzf --reverse --preview 'echo {}' | awk '{$1=$2=$3=$4=$5=$6=$7=$8=\"\"; print $0}' | xargs -r read CMD && eval $CMD"
+
+# Floating file search (ag/rg)
+bind -n C-f display-popup -E -h 50% -w 80% -x C -y C \
+  "cd #{pane_current_path} && rg --files --hidden | fzf --preview 'cat {}' --preview-window 'right:60%' | xargs -r $EDITOR"
+
+# Floating process monitor
+bind -n C-p display-popup -E -h 60% -w 100% -x 0 -y S \
+  "watch -c -n 1 'ps aux --width=200 | head -20'"
+```
+
+### 3.4 Mouse Mode Considerations
+
+```tmux
+# For AI tools where mouse interferes with text selection:
+
+# Option A: Keep mouse OFF, but enable Alt+Arrow navigation
+set -g mouse off
+bind -n M-Up select-pane -U
+bind -n M-Down select-pane -D
+bind -n M-Left select-pane -L
+bind -n M-Right select-pane -R
+
+# Option B: Toggle mouse with prefix + m (useful for pair programming)
+bind m set -g mouse \; display-message "Mouse mode: #{?mouse,ON,OFF}"
+
+# Option C: Smart mouse detection (enable in macOS Terminal, disable in iTerm2)
+%if "#{==:#{client_platform},darwin}"
+  # iTerm2 users: disable mouse to avoid selection conflicts with AI tools
+  set -g mouse off
+%else
+  # Linux with X11 forwarding: enable mouse
+  set -g mouse on
+%endif
+```
+
+---
+
+## 4. Plugin Ecosystem 2025-2026
+
+### 4.1 Essential Plugins (TPM)
+
+**Install TPM** (Tmux Plugin Manager):
+
+```bash
+git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
+```
+
+**Recommended plugin configuration**:
+
+```tmux
+# List plugins (append to .tmux.conf)
+set -g @plugin 'tmux-plugins/tpm'
+set -g @plugin 'tmux-plugins/tmux-sensible'
+set -g @plugin 'christoomey/vim-tmux-navigator'
+set -g @plugin 'tmux-plugins/tmux-yank'
+set -g @plugin 'tmux-plugins/tmux-resurrect'
+set -g @plugin 'tmux-plugins/tmux-continuum'
+set -g @plugin 'NHDaly/tmux-better-mouse-mode'
+set -g @plugin 'aserowy/tmux.nvim'
+set -g @plugin 'tmux-plugins/tmux-fzf-url'
+set -g @plugin 'tmux-plugins/tmux-prefix-highlight'
+
+# Plugin configurations
+set -g @resurrect-strategy-nvim 'session'
+set -g @continuum-restore 'on'
+set -g @continuum-save-interval '5'  # Auto-save every 5 minutes
+
+# Install plugins: prefix + I
+# Update plugins: prefix + U
+# Uninstall: prefix + Alt + U
+
+run '~/.tmux/plugins/tpm/tpm'
+```
+
+### 4.2 New Tools for 2025-2026
+
+| Tool               | Purpose                           | Use Case                              |
+| ------------------ | --------------------------------- | ------------------------------------- |
+| **dmux** (Rust)    | Configurable workspace manager    | Multi-agent setups with git worktrees |
+| **sessionx**       | FZF session switcher with preview | Quick context switching               |
+| **sesh**           | Intelligent session manager       | Auto-detect project types             |
+| **tmux-which-key** | Popup menu for keybindings        | Discoverability without cheat sheet   |
+| **treemux** (Rust) | File explorer sidebar             | Visual file navigation like Nvim-Tree |
+| **harpoon**        | Bookmarking sessions/files        | Jump to important contexts            |
+| **laio**           | Flexbox-inspired layout manager   | Modern, declarative pane layouts      |
+
+**Example: sessionx installation**:
+
+```bash
+npm install -g @sessionx/cli
+# Then: sessionx
+```
+
+---
+
+## 5. Neovim + AI Agent Integration
+
+### 5.1 vim-tmux-navigator Setup
+
+```tmux
+# Enable seamless pane/window navigation
+is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|n?vim?x?)(diff)?$'"
+
+bind -n C-h if-shell "$is_vim" 'send-keys C-h' 'select-pane -L'
+bind -n C-j if-shell "$is_vim" 'send-keys C-j' 'select-pane -D'
+bind -n C-k if-shell "$is_vim" 'send-keys C-k' 'select-pane -U'
+bind -n C-l if-shell "$is_vim" 'send-keys C-l' 'select-pane -R'
+
+# Neovim back-navigation
+bind -n C-\ if-shell "$is_vim" 'send-keys C-\\' 'select-pane -l'
+```
+
+### 5.2 Claude Code + Neovim Integration
+
+**Plugins that work well with Claude Code + tmux**:
+
+1. **claude-code.nvim** (Lua plugin):
+
+   ```lua
+   -- Send file/selection to Claude pane
+   require('claude-code').setup({
+     claude_pane = "claude-1",  -- Pane with Claude Code session
+     keymaps = {
+       send_file = "<leader>cf",
+       send_selection = "<leader>cs",
+       send_command = "<leader>cc",
+     }
+   })
+   ```
+
+2. **sidekick.nvim** (folke):
+
+   ```lua
+   require('sidekick').setup({
+     backend = 'tmux',  -- Persistent backend
+     provider = 'claude',
+     auto_suggestions = true,
+   })
+   ```
+
+3. **avante.nvim** (Multi-provider):
+   ```lua
+   require('avante').setup({
+     provider = 'claude',
+     auto_suggestions_provider = 'claude',
+     file_selector = {
+       provider = 'native',
+     },
+   })
+   ```
+
+### 5.3 Multi-Agent Workflow Pattern
+
+```tmux
+# .tmux.conf for coordinating multiple Claude agents
+
+# Create a session with isolated workspaces (git worktrees)
+# Usage: tmux new-session -s multi-agent
+
+# Window 1: Orchestrator (supervisor)
+new-window -t multi-agent -n orchestrator -c ~/project
+send-keys -t multi-agent:orchestrator "shipwright status" Enter
+
+# Window 2: Agent 1 (frontend task, branch: feat/ui-v2)
+new-window -t multi-agent -n agent-1 -c ~/project
+send-keys -t multi-agent:agent-1 "git worktree add /tmp/wt-ui feat/ui-v2 && cd /tmp/wt-ui" Enter
+send-keys -t multi-agent:agent-1 "claude code" Enter
+
+# Window 3: Agent 2 (backend task, branch: feat/api-v2)
+new-window -t multi-agent -n agent-2 -c ~/project
+send-keys -t multi-agent:agent-2 "git worktree add /tmp/wt-api feat/api-v2 && cd /tmp/wt-api" Enter
+send-keys -t multi-agent:agent-2 "claude code" Enter
+
+# Window 4: Tests (monitoring)
+new-window -t multi-agent -n tests -c ~/project
+send-keys -t multi-agent:tests "npm test -- --watch" Enter
+
+# Bind keys for quick agent switching
+bind -n C-1 select-window -t multi-agent:agent-1
+bind -n C-2 select-window -t multi-agent:agent-2
+bind -n C-0 select-window -t multi-agent:orchestrator
+```
+
+---
+
+## 6. Performance Tuning for High-Throughput
+
+### 6.1 Configuration for Claude Code (High Output Scenarios)
+
+```tmux
+# Handle Claude's massive output volume
+set -g history-limit 250000     # Increase scrollback (Claude Code generates lots of output)
+set -g buffer-limit 20          # Keep clipboard buffers reasonable
+set -g message-limit 100        # Limit queued messages
+
+# Reduce status bar update frequency under load
+set -g status-interval 10       # Check status every 10s instead of 1s
+
+# Optimize for responsive panes (critical for interactive tools)
+set -g escape-time 0            # No ESC-key delay
+set -g repeat-time 500          # Allow rapid repeat bindings
+
+# Lazy rendering (tmux 3.3+)
+# set -g do-not-render-on-key-presses off  # Default: render immediately
+
+# Monitor output in background panes
+set-hook -g pane-exited 'send-keys -t "{left}" q'  # Auto-cleanup on pane exit
+```
+
+### 6.2 System Resource Monitoring in Status Line
+
+```tmux
+# Optional: Add lightweight system monitoring
+# Requires: brew install tmux-mem-cpu-load (macOS)
+# or: apt-get install python3-psutil (Linux)
+
+set -g status-right "#[fg=#a6adc8]#(tmux-mem-cpu-load --powerline-right --interval 10)#[default] │ #[fg=#7aa2f7]%H:%M#[default]"
+```
+
+---
+
+## 7. CI/CD and Automation Patterns
+
+### 7.1 Automated Session Setup Script
+
+```bash
+#!/bin/bash
+# setup-dev-session.sh - Create reproducible dev environment
+
+SESSION="dev-env"
+PROJECT_ROOT="$1"
+
+# Kill existing session
+tmux kill-session -t $SESSION 2>/dev/null
+
+# Create new session
+tmux new-session -d -s $SESSION -x 200 -y 50 -c "$PROJECT_ROOT"
+
+# Window 1: Editor
+tmux new-window -t $SESSION:1 -n editor -c "$PROJECT_ROOT"
+tmux send-keys -t $SESSION:editor "nvim" Enter
+
+# Window 2: Build/Tests
+tmux new-window -t $SESSION:2 -n build -c "$PROJECT_ROOT"
+tmux send-keys -t $SESSION:build "npm test -- --watch" Enter
+
+# Window 3: Logs
+tmux new-window -t $SESSION:3 -n logs -c "$PROJECT_ROOT"
+tmux send-keys -t $SESSION:logs "tail -f logs/*.log" Enter
+
+# Window 4: Scratch (floating)
+tmux new-window -t $SESSION:4 -n scratch -c "$PROJECT_ROOT"
+
+# Attach
+tmux attach-session -t $SESSION
+```
+
+### 7.2 GitHub Actions Integration with tmux
+
+```yaml
+# .github/workflows/agent-pipeline.yml
+name: Autonomous Pipeline
+
+on: [pull_request, issues]
+
+jobs:
+  pipeline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup tmux for pipeline
+        run: |
+          sudo apt-get install -y tmux
+          # Create isolated session for this run
+          tmux new-session -d -s pipe-${{ github.run_id }} -c $GITHUB_WORKSPACE
+
+      - name: Run agents in tmux
+        run: |
+          tmux send-keys -t pipe-${{ github.run_id }} \
+            "shipwright pipeline start --issue ${{ github.event.issue.number }}" Enter
+
+          # Wait for completion (with timeout)
+          timeout 3600 bash -c "
+            while tmux list-sessions | grep -q pipe-${{ github.run_id }}; do
+              sleep 5
+            done
+          "
+
+      - name: Capture logs
+        if: always()
+        run: |
+          tmux capture-pane -t pipe-${{ github.run_id }} -p > /tmp/pipeline.log 2>/dev/null || true
+          cat /tmp/pipeline.log
+```
+
+---
+
+## 8. Shipwright-Specific tmux Configuration
+
+### 8.1 tmux Setup for Shipwright Daemon
+
+```tmux
+# ~/.tmux.conf.local (project-specific, checked into .claude/tmux.conf)
+
+# Color scheme for Shipwright panes
+set -g @pipeline-running-color "colour33"     # Blue - pipeline active
+set -g @pipeline-success-color "colour2"      # Green - success
+set -g @pipeline-failed-color "colour160"     # Red - failed
+
+# Status bar shows pipeline health
+set -g status-right "#{?#{pane_current_command}=shipwright,🚀,} │ #{?session_attached,👥,} │ #[fg=#a6adc8]%H:%M#[default]"
+
+# Pane borders show vitals status
+set -g @vitals-threshold-high "0.8"           # 80% = yellow
+set -g @vitals-threshold-critical "0.95"      # 95% = red
+
+# Bind keys for common pipeline operations
+bind -n C-p send-keys -t orchestrator "shipwright pipeline start --issue $(gh issue list --jq '.[0].number')" Enter
+bind -n C-d send-keys -t daemon "shipwright daemon start" Enter
+bind -n C-v send-keys -t monitor "shipwright vitals" Enter
+bind -n C-m send-keys -t memory "shipwright memory show" Enter
+```
+
+### 8.2 Agent Team Pane Layout Template
+
+```tmux
+# Create a Shipwright team session with 4 agents
+# Usage: tmux new-session -s team-feature -c $PROJECT
+
+# Main window (orchestrator)
+split-window -h
+send-keys -t team-feature:0.0 "shipwright status" Enter
+send-keys -t team-feature:0.1 "shipwright logs main --follow" Enter
+
+# Agent windows (separate by file domain)
+new-window -t team-feature -n backend "cd /tmp/wt-backend && claude code"
+new-window -t team-feature -n frontend "cd /tmp/wt-frontend && claude code"
+new-window -t team-feature -n tests "cd /tmp/wt-tests && npm test -- --watch"
+new-window -t team-feature -n docs "cd /tmp/wt-docs && vim CLAUDE.md"
+
+# Set pane titles for tmux status line
+set-pane-title -t team-feature:orchestrator.0 "orchestrator-status"
+set-pane-title -t team-feature:orchestrator.1 "orchestrator-logs"
+
+# Key shortcuts for team operations
+bind -n C-PageUp previous-window
+bind -n C-PageDown next-window
+bind -n S-C-Left swap-window -t -1
+bind -n S-C-Right swap-window -t +1
+```
+
+---
+
+## 9. Best Practices Summary
+
+| Category           | Best Practice                                                                     |
+| ------------------ | --------------------------------------------------------------------------------- |
+| **Configuration**  | Never edit core config; customize via `.tmux.conf.local` (Oh My Tmux! pattern)    |
+| **Performance**    | Set `escape-time 0` for Neovim, increase `history-limit` to 250K for Claude       |
+| **Status Line**    | Keep minimal (session, windows, time); avoid animations; update every 5-10s       |
+| **Copy Mode**      | Bind vi-style keys; use Shift+drag to select across panes with mouse on           |
+| **Popups**         | Use display-popup (3.2+) for floating scratch, fzf, and file search               |
+| **Hooks**          | Use after-new-session, pane-exited for automation; test hook side effects         |
+| **Plugins**        | Use TPM; essential: vim-tmux-navigator, tmux-yank, tmux-resurrect, tmux-continuum |
+| **AI Integration** | Combine git worktrees + tmux windows; one agent per window, one session per task  |
+| **Mouse**          | Trade-off: useful for pair programming, conflicts with text selection in TUI apps |
+| **CI/CD**          | Use tmux in headless mode; capture output with capture-pane; timeout long runs    |
+
+---
+
+## 10. Configuration Templates
+
+### 10.1 Minimal Production Config
+
+```tmux
+# ~/.tmux.conf - Minimal, battle-tested setup
+
+set -g default-terminal "xterm-256color"
+set -as terminal-overrides ",xterm*:RGB"
+set -g allow-passthrough on
+set -g extended-keys on
+set -g focus-events on
+set -g mouse on
+
+set -g escape-time 0
+set -g history-limit 250000
+set -g status-interval 10
+
+unbind C-b
+set -g prefix C-a
+bind C-a send-prefix
+
+# Panes
+bind | split-window -h -c "#{pane_current_path}"
+bind - split-window -v -c "#{pane_current_path}"
+bind c new-window -c "#{pane_current_path}"
+
+# Navigation
+bind h select-pane -L
+bind j select-pane -D
+bind k select-pane -U
+bind l select-pane -R
+
+# Resize
+bind H resize-pane -L 5
+bind J resize-pane -D 5
+bind K resize-pane -U 5
+bind L resize-pane -R 5
+
+# Reload config
+bind r source-file ~/.tmux.conf \; display "Config reloaded!"
+
+# Statusline
+set -g status-style "bg=#1e1e2e,fg=#a6adc8"
+set -g status-left "#{session_name} "
+set -g status-right "%H:%M"
+
+# Plugins
+set -g @plugin 'tmux-plugins/tpm'
+set -g @plugin 'tmux-plugins/tmux-sensible'
+set -g @plugin 'christoomey/vim-tmux-navigator'
+set -g @plugin 'tmux-plugins/tmux-yank'
+set -g @plugin 'tmux-plugins/tmux-resurrect'
+
+run '~/.tmux/plugins/tpm/tpm'
+```
+
+### 10.2 Full-Featured Config for AI Development
+
+```tmux
+# ~/.tmux.conf - Full-featured for Claude Code + Neovim
+
+# === CORE ===
+set -g default-terminal "xterm-256color"
+set -as terminal-overrides ",xterm*:RGB,alacritty:RGB"
+set -g allow-passthrough on
+set -g extended-keys on
+set -g focus-events on
+set -g set-clipboard on
+
+set -g escape-time 0
+set -g history-limit 250000
+set -g buffer-limit 20
+set -g mouse on
+set -g pane-border-indicators off
+
+# === PREFIX ===
+unbind C-b
+set -g prefix C-a
+bind C-a send-prefix
+set -g prefix2 C-b
+
+# === WINDOWS & PANES ===
+bind | split-window -h -c "#{pane_current_path}"
+bind - split-window -v -c "#{pane_current_path}"
+bind c new-window -c "#{pane_current_path}"
+bind , command-prompt "rename-window '%%'"
+set -g automatic-rename on
+set -g automatic-rename-format "#{pane_current_command}"
+
+# === NAVIGATION ===
+is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|n?vim?x?)(diff)?$'"
+
+bind -n C-h if-shell "$is_vim" 'send-keys C-h' 'select-pane -L'
+bind -n C-j if-shell "$is_vim" 'send-keys C-j' 'select-pane -D'
+bind -n C-k if-shell "$is_vim" 'send-keys C-k' 'select-pane -U'
+bind -n C-l if-shell "$is_vim" 'send-keys C-l' 'select-pane -R'
+bind -n C-\ if-shell "$is_vim" 'send-keys C-\\' 'select-pane -l'
+
+# === RESIZE ===
+bind H resize-pane -L 5
+bind J resize-pane -D 5
+bind K resize-pane -U 5
+bind L resize-pane -R 5
+
+# === POPUP ===
+%if "#{>=:#{version},3.2}"
+bind -n C-g display-popup -E -h 50% -w 80% -x C -y S \
+  "cd '#{pane_current_path}' && $SHELL"
+bind -n C-s display-popup -E -h 60% -w 80% -x C -y C \
+  "tmux list-sessions -F '#{session_name}' | fzf | xargs -r tmux switch-client -t"
+%endif
+
+# === COPY MODE ===
+bind -T copy-mode-vi v send-keys -X begin-selection
+bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel
+%if "#{==:#{client_platform},darwin}"
+bind -T copy-mode-vi Y send-keys -X copy-pipe-and-cancel "pbcopy"
+%else
+bind -T copy-mode-vi Y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
+%endif
+
+# === STATUS ===
+set -g status-style "bg=#1e1e2e,fg=#a6adc8"
+set -g status-left-length 50
+set -g status-right-length 100
+set -g status-left "#{?session_grouped,#[fg=#f38ba8],} #{session_name} "
+set -g status-right "#{?pane_in_mode,#[fg=#f38ba8]MODE#[default] │,}#[fg=#7aa2f7]%H:%M#[default]"
+set -g status-interval 10
+
+set -g window-status-format " #I:#W "
+set -g window-status-current-format "#[bg=#45475a,bold] #I:#W #[default]"
+
+# === HOOKS ===
+set-hook -g window-linked 'if-shell "[[ #{window_index} -gt 1 ]]" "set-window-option -t #{window_id} automatic-rename off"'
+
+# === PLUGINS ===
+set -g @plugin 'tmux-plugins/tpm'
+set -g @plugin 'tmux-plugins/tmux-sensible'
+set -g @plugin 'tmux-plugins/tmux-yank'
+set -g @plugin 'tmux-plugins/tmux-resurrect'
+set -g @plugin 'tmux-plugins/tmux-continuum'
+set -g @plugin 'aserowy/tmux.nvim'
+
+set -g @resurrect-strategy-nvim 'session'
+set -g @continuum-restore 'on'
+set -g @continuum-save-interval '5'
+
+run '~/.tmux/plugins/tpm/tpm'
+```
+
+---
+
+## 11. Resources & References
+
+### Official Documentation
+
+- [tmux Manual](https://man7.org/linux/man-pages/man1/tmux.1.html) - Complete reference
+- [GitHub tmux/tmux](https://github.com/tmux/tmux) - Official repo, release notes
+
+### Popular Configs & Frameworks
+
+- [Oh my tmux!](https://github.com/gpakosz/.tmux) - Best-in-class starting point (actively maintained 2025)
+- [Awesome tmux](https://github.com/rothgar/awesome-tmux) - Curated resource list
+- [tao-of-tmux](https://tao-of-tmux.readthedocs.io/) - Comprehensive guide
+
+### AI Integration
+
+- [claude-code.nvim](https://github.com/dreemanuel/claude-code.nvim) - Neovim + Claude Code + tmux
+- [sidekick.nvim](https://github.com/folke/sidekick.nvim) - Neovim AI sidekick with tmux backend
+- [avante.nvim](https://github.com/yetone/avante.nvim) - Multi-provider AI in Neovim
+
+### Plugins
+
+- [TPM](https://github.com/tmux-plugins/tpm) - Plugin manager
+- [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator) - Seamless pane navigation
+- [tmux-resurrect](https://github.com/tmux-plugins/tmux-resurrect) - Persist and restore sessions
+- [tmux-continuum](https://github.com/tmux-plugins/tmux-continuum) - Auto-save sessions
+
+### Multi-Agent Workflows
+
+- [Shipwright](https://github.com/sethdford/shipwright) - Autonomous agent pipeline orchestration
+- [multi-agent-workflow-kit](https://github.com/laris-co/multi-agent-workflow-kit) - Reusable patterns
+- [workmux](https://github.com/raine/workmux) - git worktrees + tmux windows
+
+---
+
+## Appendix: Version Compatibility Matrix
+
+| Feature                | Min Version | Notes                                    |
+| ---------------------- | ----------- | ---------------------------------------- |
+| `allow-passthrough`    | 3.2+        | DEC 2026 synchronized output             |
+| `extended-keys`        | 3.0+        | Proper Alt key handling                  |
+| `display-popup`        | 3.2+        | Floating window support                  |
+| `pane-border-status`   | 3.0+        | Pane-level status lines                  |
+| `if-shell` versioning  | 2.4+        | Use `%if` for 2.4+, `if-shell` for older |
+| `set-clipboard`        | 3.2+        | Native OSC 52 clipboard                  |
+| `focus-events`         | 2.2+        | TUI focus tracking                       |
+| `copy-pipe-and-cancel` | 2.5+        | Enhanced copy behavior                   |
+
+---
+
+**Last Updated**: February 2026
+**Tested On**: macOS 13+, Ubuntu 22.04+, Fedora 38+
+**tmux Versions**: 3.2+ (recommended), 3.0+ (acceptable), 2.9 (legacy support)