shipwright-cli 1.7.0

package/completions/_shipwright

@@ -0,0 +1,140 @@
+#compdef shipwright sw cct
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  Shipwright — Zsh tab completions                                       ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+# Place in a directory in your $fpath (e.g. ~/.zfunc/) and run: compinit
+
+_shipwright() {
+    local -a commands
+    commands=(
+        'session:Create a new tmux window for a Claude team'
+        'status:Show dashboard of running teams and agents'
+        'ps:Show running agent processes and status'
+        'logs:View and search agent pane logs'
+        'templates:Manage team composition templates'
+        'doctor:Validate your setup and check for issues'
+        'cleanup:Clean up orphaned team sessions'
+        'reaper:Automatic pane cleanup when agents exit'
+        'upgrade:Check for updates from the repo'
+        'loop:Continuous agent loop — run until goal is achieved'
+        'pipeline:Full delivery pipeline — idea to production'
+        'worktree:Manage git worktrees for agent isolation'
+        'prep:Repo preparation — generate .claude/ configs'
+        'daemon:Issue watcher — auto-process GitHub issues'
+        'memory:Persistent memory — learn from every pipeline run'
+        'cost:Cost intelligence — track tokens, budgets, model routing'
+        'init:Quick tmux setup — one command, no prompts'
+        'help:Show help message'
+        'version:Show version'
+    )
+
+    local -a pipeline_cmds daemon_cmds templates_cmds
+    pipeline_cmds=(
+        'start:Start a new pipeline run'
+        'resume:Resume from last stage'
+        'status:Show pipeline progress dashboard'
+        'abort:Cancel the running pipeline'
+        'list:Browse available pipeline templates'
+        'show:Show details of a pipeline template'
+        'test:Run pipeline test suite'
+    )
+    daemon_cmds=(
+        'start:Start issue watcher'
+        'stop:Graceful shutdown'
+        'status:Show active pipelines and queue'
+        'metrics:DORA/DX metrics dashboard'
+        'triage:Show issue triage scores'
+        'patrol:Run proactive codebase patrol'
+        'test:Run daemon test suite'
+        'logs:View daemon logs'
+        'init:Initialize daemon configuration'
+    )
+    local -a memory_cmds cost_cmds
+    memory_cmds=(
+        'show:Show learned patterns for this repo'
+        'search:Search across all memories'
+        'forget:Remove a memory entry'
+        'export:Export memories to file'
+        'import:Import memories from file'
+        'stats:Memory usage and coverage'
+        'test:Run memory test suite'
+    )
+    cost_cmds=(
+        'show:Show cost summary for current period'
+        'budget:Manage daily budget'
+        'record:Record token usage'
+        'calculate:Calculate cost estimate'
+        'check-budget:Check budget before starting'
+    )
+    templates_cmds=(
+        'list:Browse team templates'
+        'show:Show template details'
+    )
+
+    _arguments -C \
+        '1:command:->command' \
+        '*::arg:->args'
+
+    case "$state" in
+        command)
+            _describe -t commands 'shipwright command' commands
+            ;;
+        args)
+            case "${words[1]}" in
+                pipeline)
+                    _describe -t pipeline-cmds 'pipeline command' pipeline_cmds
+                    ;;
+                daemon)
+                    _describe -t daemon-cmds 'daemon command' daemon_cmds
+                    ;;
+                memory)
+                    _describe -t memory-cmds 'memory command' memory_cmds
+                    ;;
+                cost)
+                    _describe -t cost-cmds 'cost command' cost_cmds
+                    ;;
+                templates)
+                    _describe -t templates-cmds 'templates command' templates_cmds
+                    ;;
+                prep)
+                    _arguments \
+                        '--check[Audit existing prep quality]' \
+                        '--with-claude[Deep analysis using Claude Code]' \
+                        '--verbose[Verbose output]'
+                    ;;
+                loop)
+                    _arguments \
+                        '--test-cmd[Test command to verify each iteration]:command:' \
+                        '--max-iterations[Maximum loop iterations]:count:' \
+                        '--model[Claude model to use]:model:(opus sonnet haiku)' \
+                        '--agents[Number of agents]:count:' \
+                        '--audit[Enable self-reflection each iteration]' \
+                        '--audit-agent[Use separate auditor agent]' \
+                        '--quality-gates[Enable automated quality checks]' \
+                        '--definition-of-done[Custom completion checklist]:file:_files' \
+                        '--resume[Resume interrupted loop]' \
+                        '--skip-permissions[Skip permission prompts]'
+                    ;;
+                logs)
+                    _arguments \
+                        '--follow[Tail logs in real time]' \
+                        '--lines[Number of lines to show]:count:'
+                    ;;
+                cleanup)
+                    _arguments \
+                        '--force[Actually kill orphaned sessions]'
+                    ;;
+                upgrade)
+                    _arguments \
+                        '--apply[Apply available updates]'
+                    ;;
+                reaper)
+                    _arguments \
+                        '--watch[Continuous watch mode]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_shipwright "$@"

package/completions/shipwright.bash

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  Shipwright — Bash tab completions                                      ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+# Source this file or place it in /usr/local/etc/bash_completion.d/
+
+_shipwright_completions() {
+    local cur prev
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    # Top-level commands
+    local commands="session status ps logs templates doctor cleanup reaper upgrade loop pipeline worktree prep daemon memory cost init help version"
+
+    case "$prev" in
+        shipwright|sw|cct)
+            COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+            return 0
+            ;;
+        pipeline)
+            COMPREPLY=( $(compgen -W "start resume status abort list show test" -- "$cur") )
+            return 0
+            ;;
+        daemon)
+            COMPREPLY=( $(compgen -W "start stop status metrics triage patrol test logs init" -- "$cur") )
+            return 0
+            ;;
+        memory)
+            COMPREPLY=( $(compgen -W "show search forget export import stats test" -- "$cur") )
+            return 0
+            ;;
+        cost)
+            COMPREPLY=( $(compgen -W "show budget record calculate check-budget" -- "$cur") )
+            return 0
+            ;;
+        templates)
+            COMPREPLY=( $(compgen -W "list show" -- "$cur") )
+            return 0
+            ;;
+        prep)
+            COMPREPLY=( $(compgen -W "--check --with-claude --verbose" -- "$cur") )
+            return 0
+            ;;
+        loop)
+            COMPREPLY=( $(compgen -W "--test-cmd --max-iterations --model --agents --audit --audit-agent --quality-gates --definition-of-done --resume --skip-permissions" -- "$cur") )
+            return 0
+            ;;
+        logs)
+            COMPREPLY=( $(compgen -W "--follow --lines" -- "$cur") )
+            return 0
+            ;;
+        cleanup)
+            COMPREPLY=( $(compgen -W "--force" -- "$cur") )
+            return 0
+            ;;
+        upgrade)
+            COMPREPLY=( $(compgen -W "--apply" -- "$cur") )
+            return 0
+            ;;
+        reaper)
+            COMPREPLY=( $(compgen -W "--watch" -- "$cur") )
+            return 0
+            ;;
+        budget)
+            COMPREPLY=( $(compgen -W "set show" -- "$cur") )
+            return 0
+            ;;
+    esac
+
+    # Flags for subcommands already handled above; fall back to commands
+    if [[ "$cur" == -* ]]; then
+        case "${COMP_WORDS[1]}" in
+            prep)    COMPREPLY=( $(compgen -W "--check --with-claude --verbose" -- "$cur") ) ;;
+            loop)    COMPREPLY=( $(compgen -W "--test-cmd --max-iterations --model --agents --audit --audit-agent --quality-gates --definition-of-done --resume --skip-permissions" -- "$cur") ) ;;
+            logs)    COMPREPLY=( $(compgen -W "--follow --lines" -- "$cur") ) ;;
+            cleanup) COMPREPLY=( $(compgen -W "--force" -- "$cur") ) ;;
+            upgrade) COMPREPLY=( $(compgen -W "--apply" -- "$cur") ) ;;
+            reaper)  COMPREPLY=( $(compgen -W "--watch" -- "$cur") ) ;;
+            cost)    COMPREPLY=( $(compgen -W "--period --json --by-stage --by-issue" -- "$cur") ) ;;
+        esac
+        return 0
+    fi
+
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+}
+
+complete -F _shipwright_completions shipwright
+complete -F _shipwright_completions sw
+complete -F _shipwright_completions cct

package/completions/shipwright.fish

@@ -0,0 +1,107 @@
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  Shipwright — Fish tab completions                                      ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+# Place in ~/.config/fish/completions/
+
+# Disable file completions by default
+for cmd in shipwright sw cct
+    complete -c $cmd -f
+
+    # Top-level commands
+    set -l all_cmds session status ps logs templates doctor cleanup reaper upgrade loop pipeline worktree prep daemon memory cost init help version
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "session" -d "Create a new tmux window for a Claude team"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "status" -d "Show dashboard of running teams and agents"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "ps" -d "Show running agent processes and status"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "logs" -d "View and search agent pane logs"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "templates" -d "Manage team composition templates"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "doctor" -d "Validate your setup and check for issues"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "cleanup" -d "Clean up orphaned team sessions"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "reaper" -d "Automatic pane cleanup when agents exit"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "upgrade" -d "Check for updates from the repo"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "loop" -d "Continuous agent loop"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "pipeline" -d "Full delivery pipeline"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "worktree" -d "Manage git worktrees"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "prep" -d "Repo preparation"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "daemon" -d "Issue watcher daemon"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "memory" -d "Persistent memory system"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "cost" -d "Cost intelligence"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "init" -d "Quick tmux setup"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "help" -d "Show help message"
+    complete -c $cmd -n "not __fish_seen_subcommand_from $all_cmds" -a "version" -d "Show version"
+
+    # pipeline subcommands
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "start" -d "Start a new pipeline run"
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "resume" -d "Resume from last stage"
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "status" -d "Show pipeline progress"
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "abort" -d "Cancel the running pipeline"
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "list" -d "Browse pipeline templates"
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "show" -d "Show pipeline template details"
+    complete -c $cmd -n "__fish_seen_subcommand_from pipeline" -a "test" -d "Run pipeline test suite"
+
+    # daemon subcommands
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "start" -d "Start issue watcher"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "stop" -d "Graceful shutdown"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "status" -d "Show active pipelines"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "metrics" -d "DORA/DX metrics dashboard"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "triage" -d "Show issue triage scores"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "patrol" -d "Run proactive codebase patrol"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "test" -d "Run daemon test suite"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "logs" -d "View daemon logs"
+    complete -c $cmd -n "__fish_seen_subcommand_from daemon" -a "init" -d "Initialize daemon config"
+
+    # memory subcommands
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "show" -d "Show learned patterns"
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "search" -d "Search across memories"
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "forget" -d "Remove a memory entry"
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "export" -d "Export memories to file"
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "import" -d "Import memories from file"
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "stats" -d "Memory usage and coverage"
+    complete -c $cmd -n "__fish_seen_subcommand_from memory" -a "test" -d "Run memory test suite"
+
+    # cost subcommands
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -a "show" -d "Show cost summary"
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -a "budget" -d "Manage daily budget"
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -a "record" -d "Record token usage"
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -a "calculate" -d "Calculate cost estimate"
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -a "check-budget" -d "Check budget before starting"
+
+    # cost show flags
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -l period -d "Number of days to report" -r
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -l json -d "JSON output"
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -l by-stage -d "Breakdown by pipeline stage"
+    complete -c $cmd -n "__fish_seen_subcommand_from cost" -l by-issue -d "Breakdown by issue"
+
+    # templates subcommands
+    complete -c $cmd -n "__fish_seen_subcommand_from templates" -a "list" -d "Browse team templates"
+    complete -c $cmd -n "__fish_seen_subcommand_from templates" -a "show" -d "Show template details"
+
+    # prep flags
+    complete -c $cmd -n "__fish_seen_subcommand_from prep" -l check -d "Audit existing prep quality"
+    complete -c $cmd -n "__fish_seen_subcommand_from prep" -l with-claude -d "Deep analysis using Claude Code"
+    complete -c $cmd -n "__fish_seen_subcommand_from prep" -l verbose -d "Verbose output"
+
+    # loop flags
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l test-cmd -d "Test command to verify each iteration" -r
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l max-iterations -d "Maximum loop iterations" -r
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l model -d "Claude model to use" -ra "opus sonnet haiku"
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l agents -d "Number of agents" -r
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l audit -d "Enable self-reflection each iteration"
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l audit-agent -d "Use separate auditor agent"
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l quality-gates -d "Enable automated quality checks"
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l definition-of-done -d "Custom completion checklist" -rF
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l resume -d "Resume interrupted loop"
+    complete -c $cmd -n "__fish_seen_subcommand_from loop" -l skip-permissions -d "Skip permission prompts"
+
+    # logs flags
+    complete -c $cmd -n "__fish_seen_subcommand_from logs" -l follow -d "Tail logs in real time"
+    complete -c $cmd -n "__fish_seen_subcommand_from logs" -l lines -d "Number of lines to show" -r
+
+    # cleanup flags
+    complete -c $cmd -n "__fish_seen_subcommand_from cleanup" -l force -d "Actually kill orphaned sessions"
+
+    # upgrade flags
+    complete -c $cmd -n "__fish_seen_subcommand_from upgrade" -l apply -d "Apply available updates"
+
+    # reaper flags
+    complete -c $cmd -n "__fish_seen_subcommand_from reaper" -l watch -d "Continuous watch mode"
+end

package/docs/KNOWN-ISSUES.md

@@ -0,0 +1,199 @@
+# Known Issues
+
+Tracked bugs and limitations in Claude Code Agent Teams + tmux integration, with workarounds.
+
+---
+
+## #23615: tmux `send-keys` race condition
+
+**Severity:** Medium — affects sessions with 4+ agents
+
+**Problem:** When Claude Code spawns 4+ agent panes simultaneously using `split-window` + `send-keys`, tmux can deliver keystrokes to the wrong pane. This happens because tmux processes `split-window` and `send-keys` asynchronously — the new pane may not be the active pane by the time `send-keys` fires.
+
+**Symptoms:**
+- Agent commands appear in the wrong pane
+- Panes start with garbled or partial commands
+- Some panes sit empty while others received duplicate input
+
+**Workaround:** The `shipwright` CLI uses `new-window` instead of `split-window` for spawning agent panes, then arranges them with `select-layout tiled` after all panes are created. This avoids the race because each `new-window` creates an isolated context.
+
+If spawning panes manually, add a small delay between operations:
+
+```bash
+tmux split-window -t "$session" -h
+sleep 0.1
+tmux send-keys -t "$session" "claude" Enter
+```
+
+**Root cause:** This is a fundamental tmux limitation, not a Claude Code bug. tmux's command queue doesn't guarantee ordering between window operations and key delivery.
+
+**Status:** Open — no upstream fix expected. The `shipwright` workaround is reliable.
+
+---
+
+## #23572: Silent fallback to in-process mode
+
+**Severity:** Low — cosmetic, but confusing
+
+**Problem:** Agent teams can silently fall back to in-process mode if tmux isn't detected properly. No error is shown — agents just spawn in the same process instead of separate panes.
+
+**Symptoms:**
+- You're inside tmux but agents don't get their own panes
+- All agent output appears in a single terminal
+- No tmux split-windows are created
+
+**Workaround:** Make sure you're inside a real tmux session (not a nested one) and that `$TMUX` is set:
+
+```bash
+echo $TMUX  # Should show the tmux socket path
+tmux new -s dev  # Start a session if not in one
+```
+
+Claude Code auto-detects tmux and uses split panes when available.
+
+**How to verify:** After launching a team, check for multiple tmux panes:
+
+```bash
+tmux list-panes
+```
+
+If only one pane is listed while agents are active, the fallback occurred.
+
+**Status:** Open — tracked in Claude Code issue tracker.
+
+---
+
+## No VS Code / Ghostty terminal support
+
+**Severity:** Medium — affects users of these terminals
+
+**Problem:** Claude Code's tmux-based agent pane spawning does not work in:
+- **VS Code's integrated terminal** — VS Code's terminal emulator doesn't support the tmux control mode and pane management that Claude Code uses for agent teams.
+- **Ghostty** — As of current versions, Ghostty lacks the tmux integration hooks needed for split-pane agent spawning.
+
+**Symptoms:**
+- Agent teams silently fall back to in-process mode
+- No tmux split panes are created
+- Everything works, but you lose the visual multi-pane experience
+
+**Workaround:** Use a supported terminal emulator:
+
+| Terminal | Status | Notes |
+|----------|--------|-------|
+| **iTerm2** (macOS) | Supported | Recommended for macOS |
+| **Alacritty** | Supported | Fast, cross-platform |
+| **Kitty** | Supported | Feature-rich, cross-platform |
+| **WezTerm** | Supported | Cross-platform, GPU-accelerated |
+| **macOS Terminal.app** | Supported | Built-in, basic but works |
+| VS Code terminal | Not supported | Use an external terminal |
+| Ghostty | Not supported | May be supported in future versions |
+
+**Tip:** You can run tmux in an external terminal while keeping VS Code open for editing. Claude Code doesn't need to run inside VS Code to work with your project.
+
+**Status:** Unlikely to change — this is a terminal emulator limitation, not a Claude Code bug.
+
+---
+
+## Context window pressure with large teams
+
+**Severity:** Low — manageable with good practices
+
+**Problem:** Each agent in a team uses its own context window. With 3+ agents running complex tasks, individual agents can hit context limits faster than expected, especially if tasks are too broad.
+
+**Symptoms:**
+- Agent output becomes less coherent toward the end of long tasks
+- Agents start losing track of earlier context
+- Auto-compact kicks in frequently
+
+**Workaround:**
+
+1. **Limit teams to 2-3 agents.** More agents means more total context usage and more coordination overhead.
+
+2. **Keep tasks focused.** 5-6 specific tasks per agent is the sweet spot. Avoid vague tasks like "improve the codebase."
+
+3. **Set aggressive auto-compact:**
+   ```json
+   {
+     "env": {
+       "CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE": "70"
+     }
+   }
+   ```
+
+4. **Use haiku for subagent lookups** to save context budget for the main agent:
+   ```json
+   {
+     "env": {
+       "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
+     }
+   }
+   ```
+
+5. **Assign different files** to each agent to reduce cross-referencing needs.
+
+**Status:** By design — context windows are finite. The workarounds above mitigate the issue effectively.
+
+---
+
+## White/Bright Pane Backgrounds on Agent Spawn
+
+**Severity:** Medium — cosmetic but distracting
+
+**Problem:** When Claude Code spawns agent panes via tmux, new panes sometimes inherit the terminal's default background (often white/bright) instead of the tmux dark theme.
+
+**Root Cause:** tmux's `window-style` applies at the window level but newly spawned panes from external processes (like Claude Code) don't always inherit it.
+
+**Fix:** As of v1.3.0, `claude-teams-overlay.conf` uses `set-hook` to force the dark theme on every new pane:
+
+```conf
+set-hook -g after-split-window "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
+set-hook -g after-new-window   "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
+set-hook -g after-new-session  "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
+```
+
+Run `shipwright init` or `shipwright upgrade --apply` to get the updated overlay with these hooks.
+
+**Status:** ✅ Resolved in v1.3.0
+
+---
+
+## TPM plugins not loading
+
+**Severity:** Low — cosmetic
+
+**Problem:** After installation, tmux plugins (resurrect, continuum) don't load until TPM is initialized.
+
+**Workaround:** Press `prefix + I` (capital I) after starting tmux to install plugins. This only needs to be done once.
+
+If TPM itself isn't installed, the installer will offer to install it, or you can install manually:
+
+```bash
+git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
+```
+
+**Status:** Expected behavior — TPM requires a one-time plugin install step.
+
+---
+
+## Orphaned tmux panes after teammate shutdown
+
+**Severity:** Medium — cosmetic but annoying
+
+**Problem:** When Claude Code teammates shut down (via `shutdown_request` → `shutdown_response`), the Claude process exits but the tmux pane remains open with an idle shell. There is no Claude Code hook event for teammate shutdown — the available hooks (`TeammateIdle`, `TaskCompleted`, `Notification`, `Stop`, etc.) do not fire on agent exit.
+
+**Symptoms:**
+- After a team finishes work, panes remain with idle shell prompts
+- `shipwright ps` shows panes as "idle" with increasing idle time
+- `~/.claude/teams/` and `~/.claude/tasks/` directories accumulate
+
+**Fix:** Use the pane reaper:
+
+```bash
+shipwright reaper              # One-shot: clean dead panes now
+shipwright reaper --watch      # Background: auto-clean every 5s
+shipwright reaper --dry-run    # Preview what would be reaped
+```
+
+Or use the tmux keybinding: `prefix + R` for a quick one-shot cleanup.
+
+**Status:** Resolved in v1.6.0