shipwright-cli 2.0.0 → 2.1.0

package/docs/tmux-research/TMUX-ARCHITECTURE.md

@@ -0,0 +1,567 @@
+# tmux Architecture & Integration Patterns for 2025-2026
+
+## 1. Core tmux Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     tmux Server (daemon)                         │
+│                                                                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  Session 1 (development)                                 │   │
+│  │  ┌──────────────┬──────────────┬──────────────┐          │   │
+│  │  │  Window 1    │  Window 2    │  Window 3    │          │   │
+│  │  │  (editor)    │  (tests)     │  (logs)      │          │   │
+│  │  │ ┌──┬──┐      │ ┌────────┐   │ ┌────────┐   │          │   │
+│  │  │ │P1│P2│      │ │  P3    │   │ │  P4    │   │          │   │
+│  │  │ └──┴──┘      │ └────────┘   │ └────────┘   │          │   │
+│  │  └──────────────┴──────────────┴──────────────┘          │   │
+│  │                                                            │   │
+│  │  Status Line: [session_name] [1:editor] [2:tests] [3:logs] │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  Session 2 (agents)                                      │   │
+│  │  ┌──────────────┬──────────────┬──────────────┐          │   │
+│  │  │ Orchestrator │ Agent (API)  │ Agent (UI)   │          │   │
+│  │  │ ┌────────┐   │ ┌────────┐   │ ┌────────┐   │          │   │
+│  │  │ │Status  │   │ │Claude  │   │ │Claude  │   │          │   │
+│  │  │ └────────┘   │ └────────┘   │ └────────┘   │          │   │
+│  │  └──────────────┴──────────────┴──────────────┘          │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+         │              │                │
+         ├─ $TMUX socket (localhost)
+         ├─ Events (hooks, resize, key bindings)
+         └─ Clipboard (OSC 52, system integration)
+```
+
+---
+
+## 2. Modern tmux + Neovim + AI Integration
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        Developer Workstation                              │
+│                                                                            │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                    tmux Session: multi-agent-dev                 │   │
+│  │                                                                   │   │
+│  │  Window 1: editor-vim              Window 2: claude-agent-1     │   │
+│  │  ┌────────────────────────────┐   ┌────────────────────────┐   │   │
+│  │  │ Neovim (Main Workspace)    │   │ Claude Code REPL       │   │   │
+│  │  │                            │   │                        │   │   │
+│  │  │ Plugins:                   │   │ ~/worktree-1/backend   │   │   │
+│  │  │ - sidekick.nvim ───────────┼──>│ $ claude code          │   │   │
+│  │  │ - claude-code.nvim         │   │ > (AI session)         │   │   │
+│  │  │ - vim-tmux-navigator ──────┼──>│ Connected via:         │   │   │
+│  │  │ - avante.nvim              │   │ - Tmux pane ID         │   │   │
+│  │  │ - treesitter               │   │ - OSC 8 links          │   │   │
+│  │  │                            │   │ - Copy/paste (OSC 52)  │   │   │
+│  │  └────────────────────────────┘   └────────────────────────┘   │   │
+│  │                                                                   │   │
+│  │  Window 3: claude-agent-2         Window 4: monitor            │   │
+│  │  ┌────────────────────────────┐   ┌────────────────────────┐   │   │
+│  │  │ Claude Code REPL           │   │ Shipwright Vitals      │   │   │
+│  │  │ ~/worktree-2/frontend      │   │ $ shipwright vitals    │   │   │
+│  │  │ $ claude code              │   │                        │   │   │
+│  │  └────────────────────────────┘   │ [████████░░] 85%       │   │   │
+│  │                                    │ Tests: 42/45 passing   │   │   │
+│  │                                    │ Cost: $12.50 / $100    │   │   │
+│  │                                    └────────────────────────┘   │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                            │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                  tmux Status Line                                │    │
+│  │  [multi-agent-dev] 1:editor 2:claude-1 3:claude-2 4:monitor    │    │
+│  │                                              18:30  (Sat)       │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────────────────────┘
+
+Key Interactions:
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                   │
+│  Ctrl-h/j/k/l  →  vim-tmux-navigator  →  Select panes/windows   │
+│  Cmd+F         →  sidekick.nvim        →  Query Claude from Vim  │
+│  Space+cf      →  claude-code.nvim     →  Send file to Claude    │
+│  Ctrl+P        →  display-popup        →  fzf file search        │
+│  Ctrl+A,r      →  Reload config        →  Hot-reload settings    │
+│  Cmd+M         →  Toggle mouse         →  Enable for pair prog   │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Shipwright + Daemon Pipeline in tmux
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                  shipwright daemon [running 4 workers]               │
+│                                                                       │
+│  Issue Queue:  [#42 bug] [#43 feat] [#44 refactor] [#45 docs]       │
+│       ↓                                                               │
+│  ┌─────────────────────────────────────────────────────────────┐   │
+│  │  tmux Session: shipwright-daemon                            │   │
+│  │                                                              │   │
+│  │ Window 1: pipeline-42             Window 2: pipeline-43    │   │
+│  │ Status: [████████░░░] 75%         Status: [████░░░░░░] 40% │   │
+│  │ Stage: build → test               Stage: intake            │   │
+│  │ ┌──────────────────────┐          ┌──────────────────────┐ │   │
+│  │ │ git worktree: wt-42  │          │ git worktree: wt-43  │ │   │
+│  │ │ $ cd /tmp/wt-42      │          │ $ cd /tmp/wt-43      │ │   │
+│  │ │ $ npm test           │          │ $ shipwright plan    │ │   │
+│  │ │                      │          │                      │ │   │
+│  │ │ ✓ Build (2m 15s)     │          │ → Planning...        │ │   │
+│  │ │ ✓ Tests (1m 40s)     │          │                      │ │   │
+│  │ │ → Review (pending)   │          │                      │ │   │
+│  │ └──────────────────────┘          └──────────────────────┘ │   │
+│  │                                                              │   │
+│  │ Window 3: cost-monitor             Window 4: memory-system │   │
+│  │ Daily Budget: $100 / $100          ┌──────────────────────┐ │   │
+│  │ Used This Run:                     │ Remembered patterns: │   │
+│  │  - Pipeline 42: $8.50              │ • Timeout in Jest    │   │
+│  │  - Pipeline 43: $2.10              │ • DB migration issue │   │
+│  │  - Pipeline 44: $1.80              │ • Auth handler fix   │   │
+│  │ Remaining: $87.60                  └──────────────────────┘ │   │
+│  └─────────────────────────────────────────────────────────────┘   │
+│                                                                       │
+│  Heartbeats:                                                         │
+│  42 ───╯╰─╱╲╱╲╱╲  (active, 4 pings)                                │
+│  43 ───╯╰─╱╲ ♥     (idle, waiting for approval)                   │
+│  44 ───╳  (error, max retries exceeded)                            │
+│  45 ───◇  (queued, waiting for worker slot)                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Plugin Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   tmux Core (3.2+)                              │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │   Sessions   │  │   Windows    │  │    Panes     │          │
+│  │              │  │              │  │              │          │
+│  │ [attach]     │  │ [new-window] │  │ [split]      │          │
+│  │ [kill]       │  │ [kill]       │  │ [capture]    │          │
+│  │ [rename]     │  │ [rename]     │  │ [send-keys]  │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│         ↑                  ↑                  ↑                  │
+└─────────┼──────────────────┼──────────────────┼────────────────┘
+          │                  │                  │
+      ┌───┴──────────────────┴──────────────────┴─────┐
+      │                                                 │
+      │   ┌─────────────────────────────────────────┐  │
+      │   │         TPM (Plugin Manager)            │  │
+      │   │   ~/.tmux/plugins/tpm/tpm              │  │
+      │   │   Ctrl-I: install | Ctrl-U: update     │  │
+      │   └─────────────────────────────────────────┘  │
+      │                      │                         │
+      └──────────────────────┼─────────────────────────┘
+             ┌────────────────┼────────────────┐
+             │                │                │
+        ┌────▼─────┐    ┌─────▼─────┐   ┌────▼──────┐
+        │ Essential │    │ Optional  │   │ Custom    │
+        │ Plugins   │    │ Plugins   │   │ Plugins   │
+        │           │    │           │   │           │
+        │ • sensible│    │ • resurrect   │ • shipwright
+        │ • yank    │    │ • continuum   │ • custom hooks
+        │ • nav-vim │    │ • statusline  │ • theme
+        │ • prefix- │    │ • copycat     │ • bindings
+        │   highlight   │ • which-key    │           │
+        │           │    │           │   │           │
+        └───────────┘    └───────────┘   └───────────┘
+```
+
+---
+
+## 5. Configuration Override Hierarchy
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│               tmux Config Loading Order                         │
+│                                                                 │
+│  1. Server defaults                                            │
+│     (hardcoded, immutable)                                     │
+│              ↓                                                  │
+│  2. System config (/etc/tmux.conf)                            │
+│     (rare, admin-managed)                                      │
+│              ↓                                                  │
+│  3. User config (~/.tmux.conf)                                │
+│     (core configuration, rarely edited)                        │
+│              ↓                                                  │
+│  4. Local config (~/.tmux.conf.local) ← START HERE           │
+│     (customizations, project-specific settings)                │
+│              ↓                                                  │
+│  5. Runtime commands (from REPL or shell)                     │
+│     (tmux set-option, tmux bind-key)                          │
+│                                                                 │
+│  ⚠️  IMPORTANT: Never edit #3 if using Oh My Tmux!            │
+│      Put all customizations in #4 (.tmux.conf.local)          │
+│      This allows upgrading core config without conflicts      │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Hooks & Lifecycle Events
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       Session Lifecycle                           │
+│                                                                   │
+│  tmux new-session                                                │
+│         ↓                                                         │
+│         └─→ after-new-session hook                              │
+│                 (run custom setup: mkdir, git clone)            │
+│         ↓                                                         │
+│  Session active (user working)                                  │
+│         ↓                                                         │
+│  Window created                                                  │
+│         └─→ after-new-window hook                               │
+│                 (rename based on directory)                     │
+│         ↓                                                         │
+│  User types commands in panes                                   │
+│         ├─ session-renamed hook (triggered if user renames)    │
+│         ├─ window-linked hook (pane changes windows)           │
+│         └─ pane-mode-changed hook (enter copy-mode)            │
+│         ↓                                                         │
+│  Process exits in pane                                          │
+│         └─→ pane-exited hook                                    │
+│                 (auto-cleanup, capture output)                  │
+│         ↓                                                         │
+│  tmux kill-session                                              │
+│         ↓                                                         │
+│         └─→ session-closed hook                                 │
+│                 (save state, cleanup worktrees)                 │
+│                                                                   │
+└──────────────────────────────────────────────────────────────────┘
+
+Example hook chain for Shipwright:
+
+  after-new-session  →  Create git worktree
+                     →  Initialize .claude/CLAUDE.md
+                     →  Start memory system
+                     →  Display pipeline state
+
+  window-linked      →  Rename window to match branch
+                     →  Auto-run tests in background
+                     →  Update status line
+
+  pane-exited        →  Capture pane output to log
+                     →  Check exit code (0 = success, else fail)
+                     →  Post event to heartbeat system
+                     →  Trigger next pipeline stage (if gated)
+```
+
+---
+
+## 7. Mouse Mode Conflict Resolution
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│            Mouse Mode Trade-offs (2025)                         │
+│                                                                 │
+│  MOUSE OFF (Default for AI work)                              │
+│  ┌──────────────────────────────────┐                         │
+│  │ ✓ Text selection bypasses tmux   │                         │
+│  │ ✓ Vim/Neovim visual mode works   │                         │
+│  │ ✓ Claude Code REPL capture clear │                         │
+│  │ ✗ No point-and-click window nav  │                         │
+│  │ ✗ Can't drag pane dividers       │                         │
+│  │ ✗ Must use keyboard for resizing │                         │
+│  └──────────────────────────────────┘                         │
+│                                                                 │
+│  MOUSE ON (Good for pair programming)                         │
+│  ┌──────────────────────────────────┐                         │
+│  │ ✓ Click to switch panes/windows  │                         │
+│  │ ✓ Drag to resize pane dividers   │                         │
+│  │ ✓ Scroll wheel works in panes    │                         │
+│  │ ✗ Shift+click needed to select   │                         │
+│  │   text across pane boundaries    │                         │
+│  │ ✗ System clipboard needs xclip  │                         │
+│  │ ✗ TUI apps (Vim) get mouse events│                         │
+│  └──────────────────────────────────┘                         │
+│                                                                 │
+│  SOLUTION: Toggle mouse with key binding                      │
+│  bind m set -g mouse \; display "Mouse: #{?mouse,ON,OFF}"    │
+│                                                                 │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 8. Copy Mode Data Flow
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                  Copy Mode Workflow                             │
+│                                                                 │
+│  Pane Output                                                    │
+│  ┌──────────────────────────────────────────────────────┐     │
+│  │  $ npm test                                          │     │
+│  │  PASS  src/utils.test.js                            │     │
+│  │  FAIL  src/auth.test.js (line 42)                   │     │
+│  │  ──────────────────────────────────────────────────  │     │
+│  │  Tests:  45 passed, 1 failed                        │     │
+│  └──────────────────────────────────────────────────────┘     │
+│         ↑                                                       │
+│         │  User: tmux prefix + [  (enter copy-mode)           │
+│         │                                                      │
+│  ┌──────▼──────────────────────────────────────────────┐     │
+│  │  Copy Mode (vi-style)                               │     │
+│  │                                                      │     │
+│  │  v        = begin selection                         │     │
+│  │  y        = copy selection to tmux buffer           │     │
+│  │  Y        = copy entire line                        │     │
+│  │  H/L      = start/end of line                       │     │
+│  │  j/k      = move down/up                            │     │
+│  │  / or ?   = search forward/backward                 │     │
+│  │  Enter    = exit copy-mode                          │     │
+│  └──────────────────────────────────────────────────────┘     │
+│         │                                                       │
+│         ↓                                                       │
+│  Selection: "Tests:  45 passed, 1 failed"                     │
+│         │                                                       │
+│         │  User presses: y                                    │
+│         │                                                      │
+│         ├─→ copy-pipe: if-shell "%if platform=darwin"       │
+│         │   ├─→ macOS: copy-pipe-and-cancel "pbcopy"        │
+│         │   └─→ Linux: copy-pipe-and-cancel "xclip ..."     │
+│         │                                                      │
+│         ├─→ tmux buffer (internal clipboard)                 │
+│         │                                                      │
+│         └─→ System clipboard (Cmd+V / Ctrl+V)               │
+│                                                                 │
+│  Usage: Paste into Slack, Github issue, etc.                 │
+│                                                                 │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 9. Floating Popup Windows (tmux 3.2+)
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│  Main tmux Session (full terminal)                              │
+│                                                                 │
+│  ┌──────────────────────────────────────────────────────────┐ │
+│  │  Neovim (editor pane)                                    │ │
+│  │  1 set tabstop=2                                         │ │
+│  │  2 set expandtab                                         │ │
+│  │  3 let g:copilot_enabled = v:true                       │ │
+│  │  4                                                       │ │
+│  │  ┌─────────────────────────────────────────────────┐   │ │
+│  │  │  FZF Popup (Ctrl+G, display-popup)              │   │ │
+│  │  │                                                   │   │ │
+│  │  │  Find file:                                      │   │ │
+│  │  │  >                                               │   │ │
+│  │  │   bundle.json                                    │   │ │
+│  │  │   config/auth.js        ← preview right         │   │ │
+│  │  │   config/db.js                                   │   │ │
+│  │  │   package.json                                   │   │ │
+│  │  │                                                   │   │ │
+│  │  │  Selected file:                                  │   │ │
+│  │  │  config/auth.js                                  │   │ │
+│  │  │                                                   │   │ │
+│  │  │  [Enter to open]                                │   │ │
+│  │  └─────────────────────────────────────────────────┘   │ │
+│  │  (User presses Enter)                                   │ │
+│  │  ↓ Popup closes, file opened in Neovim                │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐  │
+│  │  Git Status Popup (C-j)                                 │  │
+│  │                                                           │  │
+│  │   $ git status -sb                                       │  │
+│  │   ## main...upstream/main                               │  │
+│  │   M  config/auth.js                                     │  │
+│  │   ?? node_modules/.tsconfig                             │  │
+│  │                                                           │  │
+│  │  [q to close]                                           │  │
+│  └─────────────────────────────────────────────────────────┘  │
+│                                                                 │
+│  Popup Features:                                               │
+│  • Floats above existing layout (doesn't reshape panes)       │
+│  • Customizable size & position: -h 50% -w 80% -x C -y S    │
+│  • Closable with Escape or q                                  │
+│  • Can run any shell command                                  │
+│  • Perfect for quick tools (fzf, git, docs)                  │
+│                                                                 │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 10. Integration Points Summary
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│                     Ecosystem Integration                          │
+│                                                                    │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
+│  │  Shipwright │  │  Claude Code │  │  Neovim      │             │
+│  │             │  │              │  │              │             │
+│  │ • Daemon    │  │ • REPL       │  │ • LSP        │             │
+│  │ • Pipeline  │  │ • Agent      │  │ • Plugins    │             │
+│  │ • Vitals    │  │ • Memory     │  │ • Keymaps    │             │
+│  │ • Cost      │  │ • MCP        │  │ • Snippets   │             │
+│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
+│         │                │                 │                     │
+│         └────────────────┼─────────────────┘                     │
+│                          │                                        │
+│                   ┌──────▼────────┐                              │
+│                   │    tmux       │                              │
+│                   │               │                              │
+│                   │ • Sessions    │                              │
+│                   │ • Windows     │                              │
+│                   │ • Panes       │                              │
+│                   │ • Hooks       │                              │
+│                   │ • Plugins     │                              │
+│                   │ • Clipboard   │                              │
+│                   └───────────────┘                              │
+│                          │                                        │
+│         ┌────────────────┼────────────────┐                      │
+│         │                │                │                      │
+│    ┌────▼────┐    ┌─────▼──────┐   ┌────▼──────┐               │
+│    │ Terminal │    │   Git      │   │  System   │               │
+│    │          │    │            │   │           │               │
+│    │ • Colors │    │ • Worktrees│   │ • Clipboard
+│    │ • Keys   │    │ • Branches │   │ • Signals │               │
+│    │ • Output │    │ • Status   │   │ • Timing  │               │
+│    └──────────┘    └────────────┘   └───────────┘               │
+│                                                                    │
+│  Data Flow Example:                                              │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │ 1. User types in Neovim: ":ClaudeAsk What does this do?"    │
+│  │ 2. Neovim plugin captures context (file, cursor, diagnostics) │
+│  │ 3. Plugin sends to Claude pane via tmux send-keys            │
+│  │ 4. Claude Code processes & responds                          │
+│  │ 5. Neovim reads Claude's output from tmux pane buffer       │
+│  │ 6. Response appears in Neovim floating window               │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                    │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 11. Performance Characteristics
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│        tmux Performance in 2025 (with Claude Code)                │
+│                                                                   │
+│  Memory Usage (typical):                                         │
+│  ├─ Empty session              ~2 MB                            │
+│  ├─ + 4 panes (Vim, tests, logs, agent)  ~8 MB                 │
+│  ├─ + 250K scrollback history   ~45 MB                          │
+│  ├─ + Resurrection (saved state) ~2 MB                          │
+│  └─ Total for multi-agent setup         ~60 MB                  │
+│                                                                   │
+│  CPU Usage:                                                      │
+│  ├─ Idle session               <0.1% CPU                        │
+│  ├─ Active with status updates   ~0.5% CPU (5s intervals)      │
+│  ├─ High-throughput (Claude out) ~2-3% CPU (during output)     │
+│  ├─ Resizing panes              <0.1% CPU (instant)            │
+│  └─ Note: Mostly spent in terminal rendering, not tmux logic   │
+│                                                                   │
+│  Latency (keyboard to screen):                                  │
+│  ├─ Normal key input            <5ms (escape-time: 0)          │
+│  ├─ Copy-mode navigation         <2ms (vi bindings optimized)  │
+│  ├─ Pane switching (C-a,h)       <2ms                          │
+│  ├─ Status bar updates           <10ms                          │
+│  └─ Claude output streaming      ~50ms per line (terminal I/O) │
+│                                                                   │
+│  Optimization Tuples:                                            │
+│  ┌────────────────────────────────────────────────────────┐    │
+│  │ Feature       │ Default │ Tuned for Claude          │    │
+│  │───────────────┼─────────┼──────────────────────────   │    │
+│  │ escape-time   │ 500ms   │ 0ms (critical)            │    │
+│  │ history-limit │ 2000    │ 250000 (high output)      │    │
+│  │ status-interval│ 15s    │ 10s (reduce CPU)          │    │
+│  │ buffer-limit  │ 20      │ 20 (keep as-is)           │    │
+│  │ mouse         │ off     │ off (AI workflows)        │    │
+│  │ allow-passthrough│off   │ on (TUI compat)           │    │
+│  └────────────────────────────────────────────────────────┘    │
+│                                                                   │
+│  Bottlenecks:                                                    │
+│  1. Terminal rendering (xterm protocol) — not tmux              │
+│  2. Pane scrollback search — use ↑/↓ not /search               │
+│  3. Large copy operations — tmux buffer is in-memory            │
+│  4. Many panes (>10) — CPU increases linearly                   │
+│                                                                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 12. Decision Tree: Which Feature to Use
+
+```
+                    ┌─────────────────────────┐
+                    │ I need to accomplish... │
+                    └───────────┬─────────────┘
+                                │
+                ┌───────────────┼───────────────┐
+                │               │               │
+         ┌──────▼─────┐  ┌─────▼──────┐  ┌────▼────────┐
+         │Quick        │  │Organize    │  │Automate     │
+         │navigation   │  │large tasks │  │repetitive   │
+         │             │  │            │  │tasks        │
+         └──────┬──────┘  └─────┬──────┘  └────┬────────┘
+                │               │               │
+      ┌─────────┼─────────┐    │             │
+      │         │         │    │             │
+   ┌──▼──┐  ┌──▼──┐  ┌───▼─┐  │             │
+   │fzf  │  │session
+   │     │  │switcher
+   │popup│  │     │
+   │(C-p)│  └─────┘
+   └─────┘
+
+      │
+      │         ┌──────────────────────┐
+      │         │ Organization Tool    │
+      └────────▶│                      │
+                │ • One session per    │
+                │   project (tmuxinator)
+                │ • One window per     │
+                │   agent (git worktree)
+                │ • One pane per task  │
+                │   (side-by-side)     │
+                └──────────────────────┘
+
+      │
+      │         ┌──────────────────────┐
+      │         │ Automation Method    │
+      │         │                      │
+      │         │ • Hooks: after-new-
+      │         │   session, pane-exited
+      └────────▶│ • Scripts: setup-
+                │   dev-session.sh
+                │ • send-keys: CI/CD
+                │   runner
+                │ • Keybindings: tmux
+                │   aliases
+                └──────────────────────┘
+```
+
+---
+
+## Summary: Best-in-Class Integration (2025-2026)
+
+1. **Foundation**: tmux 3.2+ with Oh My Tmux! configuration
+2. **Plugins**: vim-tmux-navigator + tmux-resurrect + tmux-continuum
+3. **Editor**: Neovim with sidekick.nvim and claude-code.nvim
+4. **AI Workflow**: git worktrees + multi-agent tmux windows
+5. **Automation**: Hooks for lifecycle events + scripts for setup
+6. **Performance**: escape-time=0, history=250K, status-interval=10s
+7. **Floating Tools**: fzf popups for quick access (no pane reshaping)
+8. **Integration**: OSC 52 clipboard + focus-events + allow-passthrough
+
+This stack enables **persistent, multi-agent development environments** with seamless Neovim + Claude Code integration, optimized for high-throughput AI-assisted workflows.