From 8ab2d56517282489f80e79571d1bd3b495cb087b Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 15:15:31 -0800
Subject: [PATCH 01/19] refactor: standardize AI and editor adapter
 initialization

Consolidate common logic for AI and editor adapters into reusable functions. Introduce _ai_define_standard and _editor_define_standard to streamline adapter setup, reducing redundancy across multiple adapter scripts. This refactor enhances maintainability and clarity in the codebase.
---
 adapters/ai/aider.sh        |  29 +----
 adapters/ai/auggie.sh       |  30 +----
 adapters/ai/codex.sh        |  33 ++----
 adapters/ai/continue.sh     |  29 +----
 adapters/ai/copilot.sh      |  35 ++----
 adapters/ai/gemini.sh       |  33 ++----
 adapters/ai/opencode.sh     |  30 +----
 adapters/editor/atom.sh     |  20 +---
 adapters/editor/cursor.sh   |  27 +----
 adapters/editor/idea.sh     |  20 +---
 adapters/editor/pycharm.sh  |  20 +---
 adapters/editor/sublime.sh  |  20 +---
 adapters/editor/vscode.sh   |  27 +----
 adapters/editor/webstorm.sh |  20 +---
 adapters/editor/zed.sh      |  20 +---
 bin/gtr                     | 202 +++++++++++++++++++-------------
 lib/config.sh               | 224 +++++++++++++++---------------------
 lib/copy.sh                 |  40 ++++---
 lib/core.sh                 |  30 +++--
 19 files changed, 326 insertions(+), 563 deletions(-)

diff --git a/adapters/ai/aider.sh b/adapters/ai/aider.sh
index 191c3d6..bff7290 100644
--- a/adapters/ai/aider.sh
+++ b/adapters/ai/aider.sh
@@ -1,28 +1,7 @@
 #!/usr/bin/env bash
 # Aider AI coding assistant adapter
 
-# Check if Aider is available
-ai_can_start() {
-  command -v aider >/dev/null 2>&1
-}
-
-# Start Aider in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "Aider not found. Install with: pip install aider-chat"
-    log_info "See https://aider.chat for more information"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run aider with any additional arguments
-  (cd "$path" && aider "$@")
-}
+_AI_CMD="aider"
+_AI_ERR_MSG="Aider not found. Install with: pip install aider-chat"
+_AI_INFO_LINES=("See https://aider.chat for more information")
+_ai_define_standard
diff --git a/adapters/ai/auggie.sh b/adapters/ai/auggie.sh
index 274a1f2..4f64093 100644
--- a/adapters/ai/auggie.sh
+++ b/adapters/ai/auggie.sh
@@ -1,29 +1,7 @@
 #!/usr/bin/env bash
 # Auggie CLI AI adapter
 
-# Check if Auggie is available
-ai_can_start() {
-  command -v auggie >/dev/null 2>&1
-}
-
-# Start Auggie in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "Auggie CLI not found. Install with: npm install -g @augmentcode/auggie"
-    log_info "See https://www.augmentcode.com/product/CLI for more information"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run auggie with any additional arguments
-  (cd "$path" && auggie "$@")
-}
-
+_AI_CMD="auggie"
+_AI_ERR_MSG="Auggie CLI not found. Install with: npm install -g @augmentcode/auggie"
+_AI_INFO_LINES=("See https://www.augmentcode.com/product/CLI for more information")
+_ai_define_standard
diff --git a/adapters/ai/codex.sh b/adapters/ai/codex.sh
index 582f8c3..2a3278f 100644
--- a/adapters/ai/codex.sh
+++ b/adapters/ai/codex.sh
@@ -1,29 +1,10 @@
 #!/usr/bin/env bash
 # OpenAI Codex CLI adapter
 
-# Check if Codex is available
-ai_can_start() {
-  command -v codex >/dev/null 2>&1
-}
-
-# Start Codex in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "Codex CLI not found. Install with: npm install -g @openai/codex"
-    log_info "Or: brew install codex"
-    log_info "See https://github.com/openai/codex for more info"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run codex with any additional arguments
-  (cd "$path" && codex "$@")
-}
+_AI_CMD="codex"
+_AI_ERR_MSG="Codex CLI not found. Install with: npm install -g @openai/codex"
+_AI_INFO_LINES=(
+  "Or: brew install codex"
+  "See https://github.com/openai/codex for more info"
+)
+_ai_define_standard
diff --git a/adapters/ai/continue.sh b/adapters/ai/continue.sh
index a4672c9..eef2a52 100644
--- a/adapters/ai/continue.sh
+++ b/adapters/ai/continue.sh
@@ -1,28 +1,7 @@
 #!/usr/bin/env bash
 # Continue CLI adapter
 
-# Check if Continue is available
-ai_can_start() {
-  command -v cn >/dev/null 2>&1
-}
-
-# Start Continue in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "Continue CLI not found. Install from https://continue.dev"
-    log_info "See https://docs.continue.dev/cli/install for installation"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run cn with any additional arguments
-  (cd "$path" && cn "$@")
-}
+_AI_CMD="cn"
+_AI_ERR_MSG="Continue CLI not found. Install from https://continue.dev"
+_AI_INFO_LINES=("See https://docs.continue.dev/cli/install for installation")
+_ai_define_standard
diff --git a/adapters/ai/copilot.sh b/adapters/ai/copilot.sh
index 16608af..e002742 100644
--- a/adapters/ai/copilot.sh
+++ b/adapters/ai/copilot.sh
@@ -1,30 +1,11 @@
 #!/usr/bin/env bash
 # GitHub Copilot CLI adapter
 
-# Check if GitHub Copilot CLI is available
-ai_can_start() {
-  command -v copilot >/dev/null 2>&1
-}
-
-# Start GitHub Copilot CLI in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "GitHub Copilot CLI not found."
-    log_info "Install with: npm install -g @github/copilot"
-    log_info "Or: brew install copilot-cli"
-    log_info "See https://github.com/github/copilot-cli for more information"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run copilot with any additional arguments
-  (cd "$path" && copilot "$@")
-}
+_AI_CMD="copilot"
+_AI_ERR_MSG="GitHub Copilot CLI not found."
+_AI_INFO_LINES=(
+  "Install with: npm install -g @github/copilot"
+  "Or: brew install copilot-cli"
+  "See https://github.com/github/copilot-cli for more information"
+)
+_ai_define_standard
diff --git a/adapters/ai/gemini.sh b/adapters/ai/gemini.sh
index 2a4d017..4c447ad 100644
--- a/adapters/ai/gemini.sh
+++ b/adapters/ai/gemini.sh
@@ -1,29 +1,10 @@
 #!/usr/bin/env bash
 # Gemini CLI adapter
 
-# Check if Gemini is available
-ai_can_start() {
-  command -v gemini >/dev/null 2>&1
-}
-
-# Start Gemini in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "Gemini CLI not found. Install with: npm install -g @google/gemini-cli"
-    log_info "Or: brew install gemini-cli"
-    log_info "See https://github.com/google-gemini/gemini-cli for more info"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run gemini with any additional arguments
-  (cd "$path" && gemini "$@")
-}
\ No newline at end of file
+_AI_CMD="gemini"
+_AI_ERR_MSG="Gemini CLI not found. Install with: npm install -g @google/gemini-cli"
+_AI_INFO_LINES=(
+  "Or: brew install gemini-cli"
+  "See https://github.com/google-gemini/gemini-cli for more info"
+)
+_ai_define_standard
diff --git a/adapters/ai/opencode.sh b/adapters/ai/opencode.sh
index e801f56..8c5782b 100644
--- a/adapters/ai/opencode.sh
+++ b/adapters/ai/opencode.sh
@@ -1,29 +1,7 @@
 #!/usr/bin/env bash
 # OpenCode adapter
 
-# Check if OpenCode is available
-ai_can_start() {
-  command -v opencode >/dev/null 2>&1
-}
-
-# Start OpenCode in a directory
-# Usage: ai_start path [args...]
-ai_start() {
-  local path="$1"
-  shift
-
-  if ! ai_can_start; then
-    log_error "OpenCode not found. Install from https://opencode.ai"
-    log_info "Make sure the 'opencode' CLI is available in your PATH"
-    return 1
-  fi
-
-  if [ ! -d "$path" ]; then
-    log_error "Directory not found: $path"
-    return 1
-  fi
-
-  # Change to the directory and run opencode with any additional arguments
-  (cd "$path" && opencode "$@")
-}
-
+_AI_CMD="opencode"
+_AI_ERR_MSG="OpenCode not found. Install from https://opencode.ai"
+_AI_INFO_LINES=("Make sure the 'opencode' CLI is available in your PATH")
+_ai_define_standard
diff --git a/adapters/editor/atom.sh b/adapters/editor/atom.sh
index 4e0acea..98fef7e 100755
--- a/adapters/editor/atom.sh
+++ b/adapters/editor/atom.sh
@@ -1,20 +1,6 @@
 #!/usr/bin/env bash
 # Atom editor adapter
 
-# Check if Atom is available
-editor_can_open() {
-  command -v atom >/dev/null 2>&1
-}
-
-# Open a directory in Atom
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "Atom not found. Install from https://atom.io"
-    return 1
-  fi
-
-  atom "$path"
-}
+_EDITOR_CMD="atom"
+_EDITOR_ERR_MSG="Atom not found. Install from https://atom.io"
+_editor_define_standard
diff --git a/adapters/editor/cursor.sh b/adapters/editor/cursor.sh
index 3c5712e..a6f20bd 100644
--- a/adapters/editor/cursor.sh
+++ b/adapters/editor/cursor.sh
@@ -1,26 +1,7 @@
 #!/usr/bin/env bash
 # Cursor editor adapter
 
-# Check if Cursor is available
-editor_can_open() {
-  command -v cursor >/dev/null 2>&1
-}
-
-# Open a directory or workspace file in Cursor
-# Usage: editor_open path [workspace_file]
-editor_open() {
-  local path="$1"
-  local workspace="${2:-}"
-
-  if ! editor_can_open; then
-    log_error "Cursor not found. Install from https://cursor.com or enable the shell command."
-    return 1
-  fi
-
-  # Open workspace file if provided, otherwise open directory
-  if [ -n "$workspace" ] && [ -f "$workspace" ]; then
-    cursor "$workspace"
-  else
-    cursor "$path"
-  fi
-}
+_EDITOR_CMD="cursor"
+_EDITOR_ERR_MSG="Cursor not found. Install from https://cursor.com or enable the shell command."
+_EDITOR_WORKSPACE=1
+_editor_define_standard
diff --git a/adapters/editor/idea.sh b/adapters/editor/idea.sh
index c6dc4d4..e5369fe 100755
--- a/adapters/editor/idea.sh
+++ b/adapters/editor/idea.sh
@@ -1,20 +1,6 @@
 #!/usr/bin/env bash
 # IntelliJ IDEA editor adapter
 
-# Check if IntelliJ IDEA is available
-editor_can_open() {
-  command -v idea >/dev/null 2>&1
-}
-
-# Open a directory in IntelliJ IDEA
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "IntelliJ IDEA 'idea' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
-    return 1
-  fi
-
-  idea "$path"
-}
+_EDITOR_CMD="idea"
+_EDITOR_ERR_MSG="IntelliJ IDEA 'idea' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
+_editor_define_standard
diff --git a/adapters/editor/pycharm.sh b/adapters/editor/pycharm.sh
index 74c5499..b10c7e5 100755
--- a/adapters/editor/pycharm.sh
+++ b/adapters/editor/pycharm.sh
@@ -1,20 +1,6 @@
 #!/usr/bin/env bash
 # PyCharm editor adapter
 
-# Check if PyCharm is available
-editor_can_open() {
-  command -v pycharm >/dev/null 2>&1
-}
-
-# Open a directory in PyCharm
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "PyCharm 'pycharm' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
-    return 1
-  fi
-
-  pycharm "$path"
-}
+_EDITOR_CMD="pycharm"
+_EDITOR_ERR_MSG="PyCharm 'pycharm' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
+_editor_define_standard
diff --git a/adapters/editor/sublime.sh b/adapters/editor/sublime.sh
index dff5c50..8a997b2 100755
--- a/adapters/editor/sublime.sh
+++ b/adapters/editor/sublime.sh
@@ -1,20 +1,6 @@
 #!/usr/bin/env bash
 # Sublime Text editor adapter
 
-# Check if Sublime Text is available
-editor_can_open() {
-  command -v subl >/dev/null 2>&1
-}
-
-# Open a directory in Sublime Text
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "Sublime Text 'subl' command not found. Install from https://www.sublimetext.com"
-    return 1
-  fi
-
-  subl "$path"
-}
+_EDITOR_CMD="subl"
+_EDITOR_ERR_MSG="Sublime Text 'subl' command not found. Install from https://www.sublimetext.com"
+_editor_define_standard
diff --git a/adapters/editor/vscode.sh b/adapters/editor/vscode.sh
index 5015ae1..aac5719 100644
--- a/adapters/editor/vscode.sh
+++ b/adapters/editor/vscode.sh
@@ -1,26 +1,7 @@
 #!/usr/bin/env bash
 # VS Code editor adapter
 
-# Check if VS Code is available
-editor_can_open() {
-  command -v code >/dev/null 2>&1
-}
-
-# Open a directory or workspace file in VS Code
-# Usage: editor_open path [workspace_file]
-editor_open() {
-  local path="$1"
-  local workspace="${2:-}"
-
-  if ! editor_can_open; then
-    log_error "VS Code 'code' command not found. Install from https://code.visualstudio.com"
-    return 1
-  fi
-
-  # Open workspace file if provided, otherwise open directory
-  if [ -n "$workspace" ] && [ -f "$workspace" ]; then
-    code "$workspace"
-  else
-    code "$path"
-  fi
-}
+_EDITOR_CMD="code"
+_EDITOR_ERR_MSG="VS Code 'code' command not found. Install from https://code.visualstudio.com"
+_EDITOR_WORKSPACE=1
+_editor_define_standard
diff --git a/adapters/editor/webstorm.sh b/adapters/editor/webstorm.sh
index ea55c5c..29ba7b9 100755
--- a/adapters/editor/webstorm.sh
+++ b/adapters/editor/webstorm.sh
@@ -1,20 +1,6 @@
 #!/usr/bin/env bash
 # WebStorm editor adapter
 
-# Check if WebStorm is available
-editor_can_open() {
-  command -v webstorm >/dev/null 2>&1
-}
-
-# Open a directory in WebStorm
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "WebStorm 'webstorm' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
-    return 1
-  fi
-
-  webstorm "$path"
-}
+_EDITOR_CMD="webstorm"
+_EDITOR_ERR_MSG="WebStorm 'webstorm' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
+_editor_define_standard
diff --git a/adapters/editor/zed.sh b/adapters/editor/zed.sh
index 8664e8b..983a8a7 100644
--- a/adapters/editor/zed.sh
+++ b/adapters/editor/zed.sh
@@ -1,20 +1,6 @@
 #!/usr/bin/env bash
 # Zed editor adapter
 
-# Check if Zed is available
-editor_can_open() {
-  command -v zed >/dev/null 2>&1
-}
-
-# Open a directory in Zed
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "Zed not found. Install from https://zed.dev"
-    return 1
-  fi
-
-  zed "$path"
-}
+_EDITOR_CMD="zed"
+_EDITOR_ERR_MSG="Zed not found. Install from https://zed.dev"
+_editor_define_standard
diff --git a/bin/gtr b/bin/gtr
index 57847a9..e830f7e 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -64,6 +64,53 @@ ai_start() {
   (cd "$path" && eval "$GTR_AI_CMD \"\$@\"")
 }
 
+# Standard AI adapter builder — used by adapter files that follow the common pattern
+# Sets globals then call this: _AI_CMD, _AI_ERR_MSG, _AI_INFO_LINES (array)
+_ai_define_standard() {
+  ai_can_start() {
+    command -v "$_AI_CMD" >/dev/null 2>&1
+  }
+
+  ai_start() {
+    local path="$1"; shift
+    if ! ai_can_start; then
+      log_error "$_AI_ERR_MSG"
+      local _line
+      for _line in "${_AI_INFO_LINES[@]}"; do
+        log_info "$_line"
+      done
+      return 1
+    fi
+    if [ ! -d "$path" ]; then
+      log_error "Directory not found: $path"
+      return 1
+    fi
+    (cd "$path" && "$_AI_CMD" "$@")
+  }
+}
+
+# Standard editor adapter builder — used by adapter files that follow the common pattern
+# Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_WORKSPACE (optional, 0 or 1)
+_editor_define_standard() {
+  editor_can_open() {
+    command -v "$_EDITOR_CMD" >/dev/null 2>&1
+  }
+
+  editor_open() {
+    local path="$1"
+    local workspace="${2:-}"
+    if ! editor_can_open; then
+      log_error "$_EDITOR_ERR_MSG"
+      return 1
+    fi
+    if [ "${_EDITOR_WORKSPACE:-0}" = "1" ] && [ -n "$workspace" ] && [ -f "$workspace" ]; then
+      "$_EDITOR_CMD" "$workspace"
+    else
+      "$_EDITOR_CMD" "$path"
+    fi
+  }
+}
+
 # Main dispatcher
 main() {
   local cmd="${1:-help}"
@@ -200,6 +247,60 @@ _post_create_next_steps() {
   echo "  cd \"\$(git gtr go $next_steps_id)\"  # Navigate to worktree"
 }
 
+# Determine the base ref for worktree creation
+# Usage: _create_resolve_from_ref <from_ref> <from_current> <repo_root>
+# Prints: resolved ref
+_create_resolve_from_ref() {
+  local from_ref="$1" from_current="$2" repo_root="$3"
+
+  if [ -z "$from_ref" ]; then
+    if [ "$from_current" -eq 1 ]; then
+      from_ref=$(get_current_branch)
+      if [ -z "$from_ref" ] || [ "$from_ref" = "HEAD" ]; then
+        log_warn "Currently in detached HEAD state - falling back to default branch"
+        from_ref=$(resolve_default_branch "$repo_root")
+      else
+        log_info "Creating from current branch: $from_ref"
+      fi
+    else
+      from_ref=$(resolve_default_branch "$repo_root")
+    fi
+  fi
+
+  printf "%s" "$from_ref"
+}
+
+# Auto-launch editor for a worktree
+_auto_launch_editor() {
+  local worktree_path="$1"
+  local editor
+  editor=$(cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor)
+  if [ "$editor" != "none" ]; then
+    load_editor_adapter "$editor"
+    local workspace_file
+    workspace_file=$(resolve_workspace_file "$worktree_path")
+    log_step "Opening in $editor..."
+    editor_open "$worktree_path" "$workspace_file"
+  else
+    open_in_gui "$worktree_path"
+    log_info "Opened in file browser (no editor configured)"
+  fi
+}
+
+# Auto-launch AI tool for a worktree
+_auto_launch_ai() {
+  local worktree_path="$1"
+  local ai_tool
+  ai_tool=$(cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai)
+  if [ "$ai_tool" = "none" ]; then
+    log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
+  else
+    load_ai_adapter "$ai_tool"
+    log_step "Starting $ai_tool..."
+    ai_start "$worktree_path"
+  fi
+}
+
 cmd_create() {
   local branch_name=""
   local from_ref=""
@@ -316,25 +417,7 @@ cmd_create() {
   fi
 
   # Determine from_ref with precedence: --from > --from-current > default
-  if [ -z "$from_ref" ]; then
-    if [ "$from_current" -eq 1 ]; then
-      # Get current branch (try modern git first, then fallback)
-      from_ref=$(git branch --show-current 2>/dev/null)
-      if [ -z "$from_ref" ]; then
-        from_ref=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
-      fi
-
-      # Handle detached HEAD state
-      if [ -z "$from_ref" ] || [ "$from_ref" = "HEAD" ]; then
-        log_warn "Currently in detached HEAD state - falling back to default branch"
-        from_ref=$(resolve_default_branch "$repo_root")
-      else
-        log_info "Creating from current branch: $from_ref"
-      fi
-    else
-      from_ref=$(resolve_default_branch "$repo_root")
-    fi
-  fi
+  from_ref=$(_create_resolve_from_ref "$from_ref" "$from_current" "$repo_root")
 
   # Construct folder name for display
   local folder_name
@@ -371,36 +454,9 @@ cmd_create() {
   echo ""
   log_info "Worktree created: $worktree_path"
 
-  # Auto-launch editor if requested
-  if [ "$open_editor" -eq 1 ]; then
-    local editor
-    editor=$(cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor)
-    if [ "$editor" != "none" ]; then
-      load_editor_adapter "$editor"
-      local workspace_file
-      workspace_file=$(resolve_workspace_file "$worktree_path")
-      log_step "Opening in $editor..."
-      editor_open "$worktree_path" "$workspace_file"
-    else
-      open_in_gui "$worktree_path"
-      log_info "Opened in file browser (no editor configured)"
-    fi
-  fi
-
-  # Auto-launch AI tool if requested
-  if [ "$start_ai" -eq 1 ]; then
-    local ai_tool
-    ai_tool=$(cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai)
-    if [ "$ai_tool" = "none" ]; then
-      log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
-    else
-      load_ai_adapter "$ai_tool"
-      log_step "Starting $ai_tool..."
-      ai_start "$worktree_path"
-    fi
-  fi
-
-  # Show next steps only if no auto-launch flags were used
+  # Auto-launch editor/AI or show next steps
+  [ "$open_editor" -eq 1 ] && _auto_launch_editor "$worktree_path"
+  [ "$start_ai" -eq 1 ] && _auto_launch_ai "$worktree_path"
   if [ "$open_editor" -eq 0 ] && [ "$start_ai" -eq 0 ]; then
     _post_create_next_steps "$branch_name" "$folder_name" "$folder_override" "$repo_root" "$base_dir" "$prefix"
   fi
@@ -449,9 +505,8 @@ cmd_remove() {
 
   for identifier in $identifiers; do
     # Resolve target branch
-    local target is_main worktree_path branch_name
-    target=$(resolve_target "$identifier" "$repo_root" "$base_dir" "$prefix") || continue
-    unpack_target "$target"
+    local is_main worktree_path branch_name
+    resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || continue
     is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch_name="$_ctx_branch"
 
     # Cannot remove main repository
@@ -544,9 +599,8 @@ cmd_rename() {
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve old worktree
-  local target is_main old_path old_branch
-  target=$(resolve_target "$old_identifier" "$repo_root" "$base_dir" "$prefix") || exit 1
-  unpack_target "$target"
+  local is_main old_path old_branch
+  resolve_worktree "$old_identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
   is_main="$_ctx_is_main" old_path="$_ctx_worktree_path" old_branch="$_ctx_branch"
 
   # Cannot rename main repository
@@ -629,9 +683,8 @@ cmd_go() {
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
-  local target is_main worktree_path branch
-  target=$(resolve_target "$identifier" "$repo_root" "$base_dir" "$prefix") || exit 1
-  unpack_target "$target"
+  local is_main worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
   is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   # Human messages to stderr so stdout can be used in command substitution
@@ -686,9 +739,8 @@ cmd_run() {
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
-  local target is_main worktree_path branch
-  target=$(resolve_target "$identifier" "$repo_root" "$base_dir" "$prefix") || exit 1
-  unpack_target "$target"
+  local is_main worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
   is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   # Human messages to stderr (like cmd_go)
@@ -762,9 +814,8 @@ cmd_copy() {
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve source path
-  local src_target src_path
-  src_target=$(resolve_target "$source" "$repo_root" "$base_dir" "$prefix") || exit 1
-  unpack_target "$src_target"
+  local src_path
+  resolve_worktree "$source" "$repo_root" "$base_dir" "$prefix" || exit 1
   src_path="$_ctx_worktree_path"
 
   # Get patterns (flag > config)
@@ -804,9 +855,8 @@ cmd_copy() {
   # Process each target
   local copied_any=0
   for target_id in $targets; do
-    local dst_target dst_path dst_branch
-    dst_target=$(resolve_target "$target_id" "$repo_root" "$base_dir" "$prefix") || continue
-    unpack_target "$dst_target"
+    local dst_path dst_branch
+    resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue
     dst_path="$_ctx_worktree_path" dst_branch="$_ctx_branch"
 
     # Skip if source == destination
@@ -866,9 +916,8 @@ cmd_editor() {
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
-  local target worktree_path branch
-  target=$(resolve_target "$identifier" "$repo_root" "$base_dir" "$prefix") || exit 1
-  unpack_target "$target"
+  local worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
   worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   if [ "$editor" = "none" ]; then
@@ -940,9 +989,8 @@ cmd_ai() {
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
-  local target worktree_path branch
-  target=$(resolve_target "$identifier" "$repo_root" "$base_dir" "$prefix") || exit 1
-  unpack_target "$target"
+  local worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
   worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   log_step "Starting $ai_tool for: $branch"
@@ -978,9 +1026,7 @@ cmd_list() {
   if [ "$porcelain" -eq 1 ]; then
     # Output: path<tab>branch<tab>status
     local branch status
-    # Try --show-current (Git 2.22+), fallback to rev-parse for older Git
-    branch=$(git -C "$repo_root" branch --show-current 2>/dev/null)
-    [ -z "$branch" ] && branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null)
+    branch=$(get_current_branch "$repo_root")
     [ -z "$branch" ] || [ "$branch" = "HEAD" ] && branch="(detached)"
     status=$(worktree_status "$repo_root")
     printf "%s\t%s\t%s\n" "$repo_root" "$branch" "$status"
@@ -1009,9 +1055,7 @@ cmd_list() {
 
   # Always show repo root first
   local branch
-  # Try --show-current (Git 2.22+), fallback to rev-parse for older Git
-  branch=$(git -C "$repo_root" branch --show-current 2>/dev/null)
-  [ -z "$branch" ] && branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  branch=$(get_current_branch "$repo_root")
   [ -z "$branch" ] || [ "$branch" = "HEAD" ] && branch="(detached)"
   printf "%-30s %s\n" "$branch [main repo]" "$repo_root"
 
diff --git a/lib/config.sh b/lib/config.sh
index d289704..d68bcfc 100644
--- a/lib/config.sh
+++ b/lib/config.sh
@@ -77,54 +77,52 @@ cfg_get() {
   git config $flag --get "$key" 2>/dev/null || true
 }
 
+# Single source of truth for gtr.* <-> .gtrconfig key mapping
+# Format: "gtr_key|file_key" — add new config keys here only
+_CFG_KEY_MAP=(
+  "gtr.copy.include|copy.include"
+  "gtr.copy.exclude|copy.exclude"
+  "gtr.copy.includeDirs|copy.includeDirs"
+  "gtr.copy.excludeDirs|copy.excludeDirs"
+  "gtr.hook.postCreate|hooks.postCreate"
+  "gtr.hook.preRemove|hooks.preRemove"
+  "gtr.hook.postRemove|hooks.postRemove"
+  "gtr.hook.postCd|hooks.postCd"
+  "gtr.editor.default|defaults.editor"
+  "gtr.editor.workspace|editor.workspace"
+  "gtr.ai.default|defaults.ai"
+  "gtr.worktrees.dir|worktrees.dir"
+  "gtr.worktrees.prefix|worktrees.prefix"
+  "gtr.defaultBranch|defaults.branch"
+  "gtr.provider|defaults.provider"
+)
+
 # Map a gtr.* config key to its .gtrconfig equivalent
 # Usage: cfg_map_to_file_key <key>
 # Returns: mapped key for .gtrconfig or empty if no mapping exists
 cfg_map_to_file_key() {
-  local key="$1"
-  case "$key" in
-    gtr.copy.include)     echo "copy.include" ;;
-    gtr.copy.exclude)     echo "copy.exclude" ;;
-    gtr.copy.includeDirs) echo "copy.includeDirs" ;;
-    gtr.copy.excludeDirs) echo "copy.excludeDirs" ;;
-    gtr.hook.postCreate)  echo "hooks.postCreate" ;;
-    gtr.hook.preRemove)   echo "hooks.preRemove" ;;
-    gtr.hook.postRemove)  echo "hooks.postRemove" ;;
-    gtr.hook.postCd)      echo "hooks.postCd" ;;
-    gtr.editor.default)   echo "defaults.editor" ;;
-    gtr.editor.workspace) echo "editor.workspace" ;;
-    gtr.ai.default)       echo "defaults.ai" ;;
-    gtr.worktrees.dir)    echo "worktrees.dir" ;;
-    gtr.worktrees.prefix) echo "worktrees.prefix" ;;
-    gtr.defaultBranch)    echo "defaults.branch" ;;
-    gtr.provider)         echo "defaults.provider" ;;
-    *)                    echo "" ;;
-  esac
+  local pair
+  for pair in "${_CFG_KEY_MAP[@]}"; do
+    if [ "${pair%%|*}" = "$1" ]; then
+      echo "${pair#*|}"
+      return
+    fi
+  done
 }
 
 # Map a .gtrconfig key to its gtr.* config equivalent (reverse of cfg_map_to_file_key)
 # Usage: cfg_map_from_file_key <file_key>
 # Returns: mapped gtr.* key, or empty if no mapping exists
 cfg_map_from_file_key() {
-  case "$1" in
-    copy.include)      echo "gtr.copy.include" ;;
-    copy.exclude)      echo "gtr.copy.exclude" ;;
-    copy.includeDirs)  echo "gtr.copy.includeDirs" ;;
-    copy.excludeDirs)  echo "gtr.copy.excludeDirs" ;;
-    hooks.postCreate)  echo "gtr.hook.postCreate" ;;
-    hooks.preRemove)   echo "gtr.hook.preRemove" ;;
-    hooks.postRemove)  echo "gtr.hook.postRemove" ;;
-    hooks.postCd)      echo "gtr.hook.postCd" ;;
-    defaults.editor)   echo "gtr.editor.default" ;;
-    editor.workspace)  echo "gtr.editor.workspace" ;;
-    defaults.ai)       echo "gtr.ai.default" ;;
-    worktrees.dir)     echo "gtr.worktrees.dir" ;;
-    worktrees.prefix)  echo "gtr.worktrees.prefix" ;;
-    defaults.branch)   echo "gtr.defaultBranch" ;;
-    defaults.provider) echo "gtr.provider" ;;
-    gtr.*)             echo "$1" ;;
-    *)                 echo "" ;;
-  esac
+  local pair
+  for pair in "${_CFG_KEY_MAP[@]}"; do
+    if [ "${pair#*|}" = "$1" ]; then
+      echo "${pair%%|*}"
+      return
+    fi
+  done
+  # Passthrough for gtr.* keys already in canonical form
+  case "$1" in gtr.*) echo "$1" ;; esac
 }
 
 # Get all values for a multi-valued config key
@@ -192,54 +190,42 @@ cfg_bool() {
   esac
 }
 
-# Set a config value
-# Usage: cfg_set key value [--global]
-cfg_set() {
-  local key="$1"
-  local value="$2"
-  local scope="${3:-local}"
-  local flag=""
-
-  case "$scope" in
-    --global|global) flag="--global" ;;
-    --system|system) flag="--system" ;;
-    --local|local|*) flag="--local" ;;
+# Convert scope name to git config flag
+# Usage: _cfg_scope_flag <scope>
+# Returns: --local, --global, or --system
+_cfg_scope_flag() {
+  case "${1:-local}" in
+    --global|global) echo "--global" ;;
+    --system|system) echo "--system" ;;
+    *)               echo "--local" ;;
   esac
+}
 
-  git config $flag "$key" "$value"
+# Set a config value
+# Usage: cfg_set key value [scope]
+cfg_set() {
+  local flag
+  flag=$(_cfg_scope_flag "${3:-local}")
+  # shellcheck disable=SC2086
+  git config $flag "$1" "$2"
 }
 
 # Add a value to a multi-valued config key
-# Usage: cfg_add key value [--global]
+# Usage: cfg_add key value [scope]
 cfg_add() {
-  local key="$1"
-  local value="$2"
-  local scope="${3:-local}"
-  local flag=""
-
-  case "$scope" in
-    --global|global) flag="--global" ;;
-    --system|system) flag="--system" ;;
-    --local|local|*) flag="--local" ;;
-  esac
-
-  git config $flag --add "$key" "$value"
+  local flag
+  flag=$(_cfg_scope_flag "${3:-local}")
+  # shellcheck disable=SC2086
+  git config $flag --add "$1" "$2"
 }
 
 # Unset a config value
-# Usage: cfg_unset key [--global]
+# Usage: cfg_unset key [scope]
 cfg_unset() {
-  local key="$1"
-  local scope="${2:-local}"
-  local flag=""
-
-  case "$scope" in
-    --global|global) flag="--global" ;;
-    --system|system) flag="--system" ;;
-    --local|local|*) flag="--local" ;;
-  esac
-
-  git config $flag --unset-all "$key" 2>/dev/null || true
+  local flag
+  flag=$(_cfg_scope_flag "${2:-local}")
+  # shellcheck disable=SC2086
+  git config $flag --unset-all "$1" 2>/dev/null || true
 }
 
 # List all gtr.* config values
@@ -271,8 +257,8 @@ cfg_list() {
       local result=""
       local key value line
 
-      # Set up cleanup trap for helper function (protects against early exit/return)
-      trap 'unset -f _cfg_list_add_entry 2>/dev/null' RETURN
+      # Set up cleanup trap for helper functions (protects against early exit/return)
+      trap 'unset -f _cfg_list_add_entry _cfg_list_parse_entries 2>/dev/null' RETURN
 
       # Helper function to add entries with origin (inline to avoid Bash 3.2 nameref issues)
       # Uses Unit Separator ($'\x1f') as delimiter to avoid conflicts with any values
@@ -295,72 +281,50 @@ cfg_list() {
         result="${result}${entry_key}"$'\x1f'"${entry_value}"$'\x1f'"${origin}"$'\n'
       }
 
+      # Parse get-regexp output and add each entry with an origin label
+      _cfg_list_parse_entries() {
+        local origin="$1"
+        local entries="$2"
+        while IFS= read -r line; do
+          [ -z "$line" ] && continue
+          key="${line%% *}"
+          if [[ "$line" == *" "* ]]; then
+            value="${line#* }"
+          else
+            value=""
+          fi
+          _cfg_list_add_entry "$origin" "$key" "$value"
+        done <<< "$entries"
+      }
+
       # Process in priority order: local > .gtrconfig > global > system
-      local local_entries global_entries system_entries
-
-      # 1. Local git config (highest priority)
-      local_entries=$(git config --local --get-regexp '^gtr\.' 2>/dev/null || true)
-      while IFS= read -r line; do
-        [ -z "$line" ] && continue
-        key="${line%% *}"
-        # Handle empty values (no space in line means value is empty)
-        if [[ "$line" == *" "* ]]; then
-          value="${line#* }"
-        else
-          value=""
-        fi
-        _cfg_list_add_entry "local" "$key" "$value"
-      done <<< "$local_entries"
+      _cfg_list_parse_entries "local" \
+        "$(git config --local --get-regexp '^gtr\.' 2>/dev/null || true)"
 
-      # 2. .gtrconfig file (team defaults)
+      # .gtrconfig needs key remapping from file format to gtr.* format
       if [ -n "$config_file" ] && [ -f "$config_file" ]; then
         while IFS= read -r line; do
           [ -z "$line" ] && continue
-          local fkey fvalue mapped_key
+          local fkey mapped_key
           fkey="${line%% *}"
-          # Handle empty values (no space in line means value is empty)
           if [[ "$line" == *" "* ]]; then
-            fvalue="${line#* }"
+            value="${line#* }"
           else
-            fvalue=""
+            value=""
           fi
-          # Map .gtrconfig keys to gtr.* format
           mapped_key=$(cfg_map_from_file_key "$fkey")
-          [ -z "$mapped_key" ] && continue  # Skip unmapped keys
-          _cfg_list_add_entry ".gtrconfig" "$mapped_key" "$fvalue"
+          [ -z "$mapped_key" ] && continue
+          _cfg_list_add_entry ".gtrconfig" "$mapped_key" "$value"
         done < <(git config -f "$config_file" --get-regexp '.' 2>/dev/null || true)
       fi
 
-      # 3. Global git config
-      global_entries=$(git config --global --get-regexp '^gtr\.' 2>/dev/null || true)
-      while IFS= read -r line; do
-        [ -z "$line" ] && continue
-        key="${line%% *}"
-        # Handle empty values (no space in line means value is empty)
-        if [[ "$line" == *" "* ]]; then
-          value="${line#* }"
-        else
-          value=""
-        fi
-        _cfg_list_add_entry "global" "$key" "$value"
-      done <<< "$global_entries"
-
-      # 4. System git config (lowest priority)
-      system_entries=$(git config --system --get-regexp '^gtr\.' 2>/dev/null || true)
-      while IFS= read -r line; do
-        [ -z "$line" ] && continue
-        key="${line%% *}"
-        # Handle empty values (no space in line means value is empty)
-        if [[ "$line" == *" "* ]]; then
-          value="${line#* }"
-        else
-          value=""
-        fi
-        _cfg_list_add_entry "system" "$key" "$value"
-      done <<< "$system_entries"
+      _cfg_list_parse_entries "global" \
+        "$(git config --global --get-regexp '^gtr\.' 2>/dev/null || true)"
+      _cfg_list_parse_entries "system" \
+        "$(git config --system --get-regexp '^gtr\.' 2>/dev/null || true)"
 
-      # Clean up helper function and clear trap (trap handles early exit cases)
-      unset -f _cfg_list_add_entry
+      # Clean up helper functions and clear trap (trap handles early exit cases)
+      unset -f _cfg_list_add_entry _cfg_list_parse_entries
       trap - RETURN
 
       output="$result"
diff --git a/lib/copy.sh b/lib/copy.sh
index b2c79c0..80fc3e7 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -1,6 +1,16 @@
 #!/usr/bin/env bash
 # File copying utilities with pattern matching
 
+# Check if a path/pattern is unsafe (absolute or contains directory traversal)
+# Usage: _is_unsafe_path "pattern"
+# Returns: 0 if unsafe, 1 if safe
+_is_unsafe_path() {
+  case "$1" in
+    /*|*/../*|../*|*/..|..) return 0 ;;
+  esac
+  return 1
+}
+
 # Check if a path matches any exclude pattern
 # Usage: is_excluded "path" "excludes_newline_separated"
 # Returns: 0 if excluded, 1 if not
@@ -83,12 +93,10 @@ copy_patterns() {
     [ -z "$pattern" ] && continue
 
     # Security: reject absolute paths and parent directory traversal
-    case "$pattern" in
-      /*|*/../*|../*|*/..|..)
-        log_warn "Skipping unsafe pattern (absolute path or '..' path segment): $pattern"
-        continue
-        ;;
-    esac
+    if _is_unsafe_path "$pattern"; then
+      log_warn "Skipping unsafe pattern (absolute path or '..' path segment): $pattern"
+      continue
+    fi
 
     # Detect if pattern uses ** (requires globstar)
     if [ "$have_globstar" -eq 0 ] && echo "$pattern" | grep -q '\*\*'; then
@@ -215,12 +223,10 @@ copy_directories() {
     [ -z "$pattern" ] && continue
 
     # Security: reject absolute paths and parent directory traversal
-    case "$pattern" in
-      /*|*/../*|../*|*/..|..)
-        log_warn "Skipping unsafe pattern: $pattern"
-        continue
-        ;;
-    esac
+    if _is_unsafe_path "$pattern"; then
+      log_warn "Skipping unsafe pattern: $pattern"
+      continue
+    fi
 
     # Find directories matching the pattern
     # Use -path for patterns with slashes (e.g., vendor/bundle), -name for basenames
@@ -255,12 +261,10 @@ copy_directories() {
             [ -z "$exclude_pattern" ] && continue
 
             # Security: reject absolute paths and parent directory traversal in excludes
-            case "$exclude_pattern" in
-              /*|*/../*|../*|*/..|..)
-                log_warn "Skipping unsafe exclude pattern: $exclude_pattern"
-                continue
-                ;;
-            esac
+            if _is_unsafe_path "$exclude_pattern"; then
+              log_warn "Skipping unsafe exclude pattern: $exclude_pattern"
+              continue
+            fi
 
             # Check if pattern applies to this copied directory
             # Supports patterns like:
diff --git a/lib/core.sh b/lib/core.sh
index e60f906..cf2e3d6 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -139,21 +139,28 @@ resolve_default_branch() {
   fi
 }
 
-# Get the current branch of a worktree
+# Get current branch name with Git 2.22+ fallback
+# Usage: get_current_branch [directory]
+# Returns: branch name, "HEAD" if detached, or empty
+get_current_branch() {
+  local dir_flag=""
+  # shellcheck disable=SC2086
+  [ -n "${1:-}" ] && dir_flag="-C $1"
+  git $dir_flag branch --show-current 2>/dev/null ||
+    git $dir_flag rev-parse --abbrev-ref HEAD 2>/dev/null
+}
+
+# Get the current branch of a worktree (with detached HEAD normalization)
 # Usage: current_branch worktree_path
 current_branch() {
   local worktree_path="$1"
-  local branch
 
   if [ ! -d "$worktree_path" ]; then
     return 1
   fi
 
-  # Try --show-current (Git 2.22+), fallback to rev-parse for older Git
-  branch=$(cd "$worktree_path" && git branch --show-current 2>/dev/null)
-  if [ -z "$branch" ]; then
-    branch=$(cd "$worktree_path" && git rev-parse --abbrev-ref HEAD 2>/dev/null)
-  fi
+  local branch
+  branch=$(get_current_branch "$worktree_path")
 
   # Normalize detached HEAD
   if [ "$branch" = "HEAD" ]; then
@@ -280,6 +287,15 @@ unpack_target() {
   read _ctx_is_main _ctx_worktree_path _ctx_branch <<< "$1"
 }
 
+# Resolve an identifier to a worktree and set _ctx_* variables in one step
+# Usage: resolve_worktree <identifier> <repo_root> <base_dir> <prefix>
+# Sets: _ctx_is_main, _ctx_worktree_path, _ctx_branch
+resolve_worktree() {
+  local target
+  target=$(resolve_target "$1" "$2" "$3" "$4") || return 1
+  unpack_target "$target"
+}
+
 # Create a new git worktree
 # Usage: create_worktree base_dir prefix branch_name from_ref track_mode [skip_fetch] [force] [custom_name] [folder_override]
 # track_mode: auto, remote, local, or none

From 1aa5b20a841d68073d1da9a468aff2783f793534 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 15:33:44 -0800
Subject: [PATCH 02/19] refactor: streamline editor adapter scripts with
 terminal definition

Consolidate the logic for checking and opening editors (Emacs, Neovim, Vim) into a single terminal editor adapter function. This refactor reduces redundancy in the editor scripts and enhances maintainability by utilizing shared global variables for command execution and error messaging.
---
 adapters/editor/emacs.sh | 22 ++++----------------
 adapters/editor/nvim.sh  | 21 +++----------------
 adapters/editor/vim.sh   | 21 +++----------------
 bin/gtr                  | 44 +++++++++++++++++++++++++++++++++-------
 lib/config.sh            | 11 ++++++++++
 5 files changed, 58 insertions(+), 61 deletions(-)

diff --git a/adapters/editor/emacs.sh b/adapters/editor/emacs.sh
index 473a79f..d0ba404 100755
--- a/adapters/editor/emacs.sh
+++ b/adapters/editor/emacs.sh
@@ -1,21 +1,7 @@
 #!/usr/bin/env bash
 # Emacs editor adapter
 
-# Check if Emacs is available
-editor_can_open() {
-  command -v emacs >/dev/null 2>&1
-}
-
-# Open a directory in Emacs
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "Emacs not found. Install from https://www.gnu.org/software/emacs/"
-    return 1
-  fi
-
-  # Open emacs with the directory
-  emacs "$path" &
-}
+_EDITOR_CMD="emacs"
+_EDITOR_ERR_MSG="Emacs not found. Install from https://www.gnu.org/software/emacs/"
+_EDITOR_BACKGROUND=1
+_editor_define_terminal
diff --git a/adapters/editor/nvim.sh b/adapters/editor/nvim.sh
index d845cae..61193df 100755
--- a/adapters/editor/nvim.sh
+++ b/adapters/editor/nvim.sh
@@ -1,21 +1,6 @@
 #!/usr/bin/env bash
 # Neovim editor adapter
 
-# Check if Neovim is available
-editor_can_open() {
-  command -v nvim >/dev/null 2>&1
-}
-
-# Open a directory in Neovim
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "Neovim not found. Install from https://neovim.io"
-    return 1
-  fi
-
-  # Open neovim in the directory
-  (cd "$path" && nvim .)
-}
+_EDITOR_CMD="nvim"
+_EDITOR_ERR_MSG="Neovim not found. Install from https://neovim.io"
+_editor_define_terminal
diff --git a/adapters/editor/vim.sh b/adapters/editor/vim.sh
index 2f1b0e4..3b41b1c 100755
--- a/adapters/editor/vim.sh
+++ b/adapters/editor/vim.sh
@@ -1,21 +1,6 @@
 #!/usr/bin/env bash
 # Vim editor adapter
 
-# Check if Vim is available
-editor_can_open() {
-  command -v vim >/dev/null 2>&1
-}
-
-# Open a directory in Vim
-# Usage: editor_open path
-editor_open() {
-  local path="$1"
-
-  if ! editor_can_open; then
-    log_error "Vim not found. Install via your package manager."
-    return 1
-  fi
-
-  # Open vim in the directory
-  (cd "$path" && vim .)
-}
+_EDITOR_CMD="vim"
+_EDITOR_ERR_MSG="Vim not found. Install via your package manager."
+_editor_define_terminal
diff --git a/bin/gtr b/bin/gtr
index e830f7e..cd9f892 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -111,6 +111,27 @@ _editor_define_standard() {
   }
 }
 
+# Terminal editor adapter builder — for editors that run in the current terminal
+# Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_BACKGROUND (optional, 0 or 1)
+_editor_define_terminal() {
+  editor_can_open() {
+    command -v "$_EDITOR_CMD" >/dev/null 2>&1
+  }
+
+  editor_open() {
+    local path="$1"
+    if ! editor_can_open; then
+      log_error "$_EDITOR_ERR_MSG"
+      return 1
+    fi
+    if [ "${_EDITOR_BACKGROUND:-0}" = "1" ]; then
+      "$_EDITOR_CMD" "$path" &
+    else
+      (cd "$path" && "$_EDITOR_CMD" .)
+    fi
+  }
+}
+
 # Main dispatcher
 main() {
   local cmd="${1:-help}"
@@ -276,7 +297,7 @@ _auto_launch_editor() {
   local editor
   editor=$(cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor)
   if [ "$editor" != "none" ]; then
-    load_editor_adapter "$editor"
+    load_editor_adapter "$editor" || return 1
     local workspace_file
     workspace_file=$(resolve_workspace_file "$worktree_path")
     log_step "Opening in $editor..."
@@ -295,7 +316,7 @@ _auto_launch_ai() {
   if [ "$ai_tool" = "none" ]; then
     log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
   else
-    load_ai_adapter "$ai_tool"
+    load_ai_adapter "$ai_tool" || return 1
     log_step "Starting $ai_tool..."
     ai_start "$worktree_path"
   fi
@@ -455,8 +476,8 @@ cmd_create() {
   log_info "Worktree created: $worktree_path"
 
   # Auto-launch editor/AI or show next steps
-  [ "$open_editor" -eq 1 ] && _auto_launch_editor "$worktree_path"
-  [ "$start_ai" -eq 1 ] && _auto_launch_ai "$worktree_path"
+  [ "$open_editor" -eq 1 ] && { _auto_launch_editor "$worktree_path" || true; }
+  [ "$start_ai" -eq 1 ] && { _auto_launch_ai "$worktree_path" || true; }
   if [ "$open_editor" -eq 0 ] && [ "$start_ai" -eq 0 ]; then
     _post_create_next_steps "$branch_name" "$folder_name" "$folder_override" "$repo_root" "$base_dir" "$prefix"
   fi
@@ -926,7 +947,7 @@ cmd_editor() {
     log_info "Opened in file browser"
   else
     # Load editor adapter and open
-    load_editor_adapter "$editor"
+    load_editor_adapter "$editor" || exit 1
     local workspace_file
     workspace_file=$(resolve_workspace_file "$worktree_path")
     log_step "Opening in $editor..."
@@ -983,7 +1004,7 @@ cmd_ai() {
   fi
 
   # Load AI adapter
-  load_ai_adapter "$ai_tool"
+  load_ai_adapter "$ai_tool" || exit 1
 
   resolve_repo_context || exit 1
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
@@ -1525,6 +1546,9 @@ cmd_config() {
       if [ -n "$extra_args" ]; then
         log_warn "set action: ignoring extra arguments: $extra_args"
       fi
+      if ! _cfg_is_known_key "$key"; then
+        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
+      fi
       cfg_set "$key" "$value" "$resolved_scope"
       log_info "Config set: $key = $value ($resolved_scope)"
       ;;
@@ -1537,6 +1561,9 @@ cmd_config() {
       if [ -n "$extra_args" ]; then
         log_warn "add action: ignoring extra arguments: $extra_args"
       fi
+      if ! _cfg_is_known_key "$key"; then
+        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
+      fi
       cfg_add "$key" "$value" "$resolved_scope"
       log_info "Config added: $key = $value ($resolved_scope)"
       ;;
@@ -1549,6 +1576,9 @@ cmd_config() {
       if [ -n "$value" ] || [ -n "$extra_args" ]; then
         log_warn "unset action: ignoring extra arguments: ${value}${value:+ }${extra_args}"
       fi
+      if ! _cfg_is_known_key "$key"; then
+        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
+      fi
       cfg_unset "$key" "$resolved_scope"
       log_info "Config unset: $key ($resolved_scope)"
       ;;
@@ -1878,7 +1908,7 @@ _load_adapter() {
     log_error "$label '$name' not found"
     log_info "Built-in adapters: $builtin_list"
     log_info "Or use any $label command available in your PATH (e.g., $path_hint)"
-    exit 1
+    return 1
   fi
 
   # Set globals for generic adapter functions
diff --git a/lib/config.sh b/lib/config.sh
index d68bcfc..3ba06e4 100644
--- a/lib/config.sh
+++ b/lib/config.sh
@@ -125,6 +125,17 @@ cfg_map_from_file_key() {
   case "$1" in gtr.*) echo "$1" ;; esac
 }
 
+# Check if a key is a recognized gtr.* config key
+# Usage: _cfg_is_known_key <key>
+# Returns: 0 if known, 1 if not
+_cfg_is_known_key() {
+  local pair
+  for pair in "${_CFG_KEY_MAP[@]}"; do
+    [ "${pair%%|*}" = "$1" ] && return 0
+  done
+  return 1
+}
+
 # Get all values for a multi-valued config key
 # Usage: cfg_get_all key [file_key] [scope]
 # file_key: optional key name in .gtrconfig (e.g., "copy.include" for gtr.copy.include)

From 9cd81a43fb8fd9cc89c92ea64a16db297c3cc49f Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 15:35:22 -0800
Subject: [PATCH 03/19] refactor: simplify get_current_branch function logic

Refactor the get_current_branch function to improve clarity and maintainability. The updated implementation uses conditional statements to handle directory input more cleanly, eliminating redundancy in the command execution for both specified and current directories.
---
 lib/core.sh | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/lib/core.sh b/lib/core.sh
index cf2e3d6..9907530 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -143,11 +143,13 @@ resolve_default_branch() {
 # Usage: get_current_branch [directory]
 # Returns: branch name, "HEAD" if detached, or empty
 get_current_branch() {
-  local dir_flag=""
-  # shellcheck disable=SC2086
-  [ -n "${1:-}" ] && dir_flag="-C $1"
-  git $dir_flag branch --show-current 2>/dev/null ||
-    git $dir_flag rev-parse --abbrev-ref HEAD 2>/dev/null
+  if [ -n "${1:-}" ]; then
+    git -C "$1" branch --show-current 2>/dev/null ||
+      git -C "$1" rev-parse --abbrev-ref HEAD 2>/dev/null
+  else
+    git branch --show-current 2>/dev/null ||
+      git rev-parse --abbrev-ref HEAD 2>/dev/null
+  fi
 }
 
 # Get the current branch of a worktree (with detached HEAD normalization)

From 06c2301c8bcb1b247b8cad8dd55af5b2dee53b48 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 15:53:40 -0800
Subject: [PATCH 04/19] feat: add CI workflow for linting and testing

Introduce a GitHub Actions workflow to automate linting with ShellCheck and testing with BATS. The workflow triggers on pushes and pull requests to the main branch, ensuring code quality and functionality through automated checks. Additionally, refactor the copy function in lib/copy.sh to improve maintainability by extracting the file copying logic into a dedicated helper function.
---
 .github/workflows/lint.yml      |  33 +++++++++++
 bin/gtr                         |  15 ++++-
 lib/copy.sh                     | 102 ++++++++++++++------------------
 lib/core.sh                     |  12 ++--
 lib/hooks.sh                    |   1 +
 lib/platform.sh                 |  25 ++++++--
 tests/copy_safety.bats          |  84 ++++++++++++++++++++++++++
 tests/resolve_base_dir.bats     |  40 +++++++++++++
 tests/sanitize_branch_name.bats |  51 ++++++++++++++++
 tests/test_helper.bash          |  17 ++++++
 10 files changed, 310 insertions(+), 70 deletions(-)
 create mode 100644 .github/workflows/lint.yml
 create mode 100644 tests/copy_safety.bats
 create mode 100644 tests/resolve_base_dir.bats
 create mode 100644 tests/sanitize_branch_name.bats
 create mode 100644 tests/test_helper.bash

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
new file mode 100644
index 0000000..e24cfa9
--- /dev/null
+++ b/.github/workflows/lint.yml
@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  shellcheck:
+    name: ShellCheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ShellCheck
+        run: sudo apt-get install -y shellcheck
+
+      - name: Run ShellCheck
+        run: |
+          shellcheck bin/gtr bin/git-gtr lib/*.sh adapters/editor/*.sh adapters/ai/*.sh
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install BATS
+        run: sudo apt-get install -y bats
+
+      - name: Run tests
+        run: bats tests/
diff --git a/bin/gtr b/bin/gtr
index cd9f892..23ee89d 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -2,6 +2,8 @@
 # gtr - Git worktree runner
 # Portable, cross-platform git worktree management
 
+# shellcheck disable=SC2329 # Functions defined inside adapter builders are invoked indirectly
+
 set -e
 
 # Version
@@ -1048,7 +1050,9 @@ cmd_list() {
     # Output: path<tab>branch<tab>status
     local branch status
     branch=$(get_current_branch "$repo_root")
-    [ -z "$branch" ] || [ "$branch" = "HEAD" ] && branch="(detached)"
+    if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
+      branch="(detached)"
+    fi
     status=$(worktree_status "$repo_root")
     printf "%s\t%s\t%s\n" "$repo_root" "$branch" "$status"
 
@@ -1077,7 +1081,9 @@ cmd_list() {
   # Always show repo root first
   local branch
   branch=$(get_current_branch "$repo_root")
-  [ -z "$branch" ] || [ "$branch" = "HEAD" ] && branch="(detached)"
+  if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
+    branch="(detached)"
+  fi
   printf "%-30s %s\n" "$branch [main repo]" "$repo_root"
 
   # Show worktrees sorted by branch name
@@ -1329,6 +1335,7 @@ cmd_doctor() {
     # Check if adapter exists
     local editor_adapter="$GTR_DIR/adapters/editor/${editor}.sh"
     if [ -f "$editor_adapter" ]; then
+      # shellcheck disable=SC1090
       . "$editor_adapter"
       if editor_can_open 2>/dev/null; then
         echo "[OK] Editor: $editor (found)"
@@ -1349,6 +1356,7 @@ cmd_doctor() {
     # Check if adapter exists
     local adapter_file="$GTR_DIR/adapters/ai/${ai_tool}.sh"
     if [ -f "$adapter_file" ]; then
+      # shellcheck disable=SC1090
       . "$adapter_file"
       if ai_can_start 2>/dev/null; then
         echo "[OK] AI tool: $ai_tool (found)"
@@ -1419,6 +1427,7 @@ cmd_adapter() {
     if [ -f "$adapter_file" ]; then
       local adapter_name
       adapter_name=$(basename "$adapter_file" .sh)
+      # shellcheck disable=SC1090
       . "$adapter_file"
 
       if editor_can_open 2>/dev/null; then
@@ -1440,6 +1449,7 @@ cmd_adapter() {
     if [ -f "$adapter_file" ]; then
       local adapter_name
       adapter_name=$(basename "$adapter_file" .sh)
+      # shellcheck disable=SC1090
       . "$adapter_file"
 
       if ai_can_start 2>/dev/null; then
@@ -1896,6 +1906,7 @@ _load_adapter() {
 
   # Try loading explicit adapter first (allows special handling)
   if [ -f "$adapter_file" ]; then
+    # shellcheck disable=SC1090
     . "$adapter_file"
     return 0
   fi
diff --git a/lib/copy.sh b/lib/copy.sh
index 80fc3e7..14f34aa 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -48,6 +48,48 @@ parse_pattern_file() {
   grep -v '^#' "$file_path" 2>/dev/null | grep -v '^[[:space:]]*$' || true
 }
 
+# Copy a single file to destination, handling exclusion, path preservation, and dry-run
+# Usage: _copy_pattern_file file dst_root excludes preserve_paths dry_run
+# Returns: 0 if file was copied (or would be in dry-run), 1 if skipped/failed
+_copy_pattern_file() {
+  local file="$1"
+  local dst_root="$2"
+  local excludes="$3"
+  local preserve_paths="$4"
+  local dry_run="$5"
+
+  # Remove leading ./
+  file="${file#./}"
+
+  # Skip if excluded
+  is_excluded "$file" "$excludes" && return 1
+
+  # Determine destination path
+  local dest_file
+  if [ "$preserve_paths" = "true" ]; then
+    dest_file="$dst_root/$file"
+  else
+    dest_file="$dst_root/$(basename "$file")"
+  fi
+
+  # Copy the file (or show what would be copied in dry-run mode)
+  if [ "$dry_run" = "true" ]; then
+    log_info "[dry-run] Would copy: $file"
+    return 0
+  fi
+
+  local dest_dir
+  dest_dir=$(dirname "$dest_file")
+  mkdir -p "$dest_dir"
+  if cp "$file" "$dest_file" 2>/dev/null; then
+    log_info "Copied $file"
+    return 0
+  else
+    log_warn "Failed to copy $file"
+    return 1
+  fi
+}
+
 # Copy files matching patterns from source to destination
 # Usage: copy_patterns src_root dst_root includes excludes [preserve_paths] [dry_run]
 # includes: newline-separated glob patterns to include
@@ -102,36 +144,8 @@ copy_patterns() {
     if [ "$have_globstar" -eq 0 ] && echo "$pattern" | grep -q '\*\*'; then
       # Fallback to find for ** patterns on Bash 3.2
       while IFS= read -r file; do
-        # Remove leading ./
-        file="${file#./}"
-
-        # Skip if excluded
-        is_excluded "$file" "$excludes" && continue
-
-        # Determine destination path
-        local dest_file
-        if [ "$preserve_paths" = "true" ]; then
-          dest_file="$dst_root/$file"
-        else
-          dest_file="$dst_root/$(basename "$file")"
-        fi
-
-        # Create destination directory (skip in dry-run mode)
-        local dest_dir
-        dest_dir=$(dirname "$dest_file")
-
-        # Copy the file (or show what would be copied in dry-run mode)
-        if [ "$dry_run" = "true" ]; then
-          log_info "[dry-run] Would copy: $file"
+        if _copy_pattern_file "$file" "$dst_root" "$excludes" "$preserve_paths" "$dry_run"; then
           copied_count=$((copied_count + 1))
-        else
-          mkdir -p "$dest_dir"
-          if cp "$file" "$dest_file" 2>/dev/null; then
-            log_info "Copied $file"
-            copied_count=$((copied_count + 1))
-          else
-            log_warn "Failed to copy $file"
-          fi
         fi
       done <<EOF
 $(find . -path "./$pattern" -type f 2>/dev/null)
@@ -142,36 +156,8 @@ EOF
         # Skip if not a file
         [ -f "$file" ] || continue
 
-        # Remove leading ./
-        file="${file#./}"
-
-        # Skip if excluded
-        is_excluded "$file" "$excludes" && continue
-
-        # Determine destination path
-        local dest_file
-        if [ "$preserve_paths" = "true" ]; then
-          dest_file="$dst_root/$file"
-        else
-          dest_file="$dst_root/$(basename "$file")"
-        fi
-
-        # Create destination directory (skip in dry-run mode)
-        local dest_dir
-        dest_dir=$(dirname "$dest_file")
-
-        # Copy the file (or show what would be copied in dry-run mode)
-        if [ "$dry_run" = "true" ]; then
-          log_info "[dry-run] Would copy: $file"
+        if _copy_pattern_file "$file" "$dst_root" "$excludes" "$preserve_paths" "$dry_run"; then
           copied_count=$((copied_count + 1))
-        else
-          mkdir -p "$dest_dir"
-          if cp "$file" "$dest_file" 2>/dev/null; then
-            log_info "Copied $file"
-            copied_count=$((copied_count + 1))
-          else
-            log_warn "Failed to copy $file"
-          fi
         fi
       done
     fi
diff --git a/lib/core.sh b/lib/core.sh
index 9907530..e7a2b2f 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -54,10 +54,12 @@ resolve_base_dir() {
     # Default: <repo>-worktrees next to the repo
     base_dir="$(dirname "$repo_root")/${repo_name}-worktrees"
   else
-    # Expand tilde to home directory
+    # Expand literal tilde to home directory
+    # Patterns must quote ~ to prevent bash tilde expansion in case arms
+    # shellcheck disable=SC2088
     case "$base_dir" in
-      ~/*) base_dir="$HOME/${base_dir#~/}" ;;
-      ~) base_dir="$HOME" ;;
+      "~/"*) base_dir="$HOME/${base_dir#"~/"}" ;;
+      "~") base_dir="$HOME" ;;
     esac
 
     # Check if absolute or relative
@@ -89,7 +91,7 @@ resolve_base_dir() {
 
   # Warn if worktree dir is inside repo (but not a sibling)
   if [[ "$base_dir" == "$canonical_repo_root"/* ]]; then
-    local rel_path="${base_dir#$canonical_repo_root/}"
+    local rel_path="${base_dir#"$canonical_repo_root"/}"
     # Check if .gitignore exists and whether it includes the worktree directory
     if [ -f "$canonical_repo_root/.gitignore" ]; then
       if ! grep -qE "^/?${rel_path}/?\$|^/?${rel_path}/\*?\$" "$canonical_repo_root/.gitignore" 2>/dev/null; then
@@ -234,7 +236,7 @@ resolve_target() {
   local repo_root="$2"
   local base_dir="$3"
   local prefix="$4"
-  local id path branch sanitized_name
+  local path branch sanitized_name
 
   # Special case: ID 1 is always the repo root
   if [ "$identifier" = "1" ]; then
diff --git a/lib/hooks.sh b/lib/hooks.sh
index e6682df..c291974 100644
--- a/lib/hooks.sh
+++ b/lib/hooks.sh
@@ -36,6 +36,7 @@ run_hooks() {
     if (
       # Export each KEY=VALUE exactly as passed, safely quoted
       for kv in "${envs[@]}"; do
+        # shellcheck disable=SC2163
         export "$kv"
       done
       # Execute the hook
diff --git a/lib/platform.sh b/lib/platform.sh
index 5aaa386..e4e89b3 100644
--- a/lib/platform.sh
+++ b/lib/platform.sh
@@ -68,6 +68,15 @@ open_in_gui() {
   esac
 }
 
+# Escape a string for safe interpolation into AppleScript double-quoted strings
+# Handles backslashes and double quotes that would break AppleScript syntax
+_escape_applescript() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  printf '%s' "$s"
+}
+
 # Spawn a new terminal window/tab in a directory
 # Usage: spawn_terminal_in path title [command]
 # Note: Best-effort implementation, may not work on all systems
@@ -81,6 +90,12 @@ spawn_terminal_in() {
 
   case "$os" in
     darwin)
+      # Escape variables for AppleScript string interpolation
+      local safe_path safe_title safe_cmd
+      safe_path=$(_escape_applescript "$path")
+      safe_title=$(_escape_applescript "$title")
+      safe_cmd=$(_escape_applescript "$cmd")
+
       # Try iTerm2 first, then Terminal.app
       if osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true' 2>/dev/null | grep -q "iTerm"; then
         osascript <<-EOF 2>/dev/null || true
@@ -88,9 +103,9 @@ spawn_terminal_in() {
 						tell current window
 							create tab with default profile
 							tell current session
-								write text "cd \"$path\""
-								set name to "$title"
-								$([ -n "$cmd" ] && echo "write text \"$cmd\"")
+								write text "cd \"$safe_path\""
+								set name to "$safe_title"
+								$([ -n "$safe_cmd" ] && echo "write text \"$safe_cmd\"")
 							end tell
 						end tell
 					end tell
@@ -98,8 +113,8 @@ spawn_terminal_in() {
       else
         osascript <<-EOF 2>/dev/null || true
 					tell application "Terminal"
-						do script "cd \"$path\"; $cmd"
-						set custom title of front window to "$title"
+						do script "cd \"$safe_path\"; $safe_cmd"
+						set custom title of front window to "$safe_title"
 					end tell
 				EOF
       fi
diff --git a/tests/copy_safety.bats b/tests/copy_safety.bats
new file mode 100644
index 0000000..2ce9a4b
--- /dev/null
+++ b/tests/copy_safety.bats
@@ -0,0 +1,84 @@
+#!/usr/bin/env bats
+
+setup() {
+  load test_helper
+  source "$PROJECT_ROOT/lib/copy.sh"
+}
+
+# --- _is_unsafe_path tests ---
+
+@test "absolute path is unsafe" {
+  _is_unsafe_path "/etc/passwd"
+}
+
+@test "relative path is safe" {
+  ! _is_unsafe_path "src/main.js"
+}
+
+@test "parent traversal at start is unsafe" {
+  _is_unsafe_path "../secret"
+}
+
+@test "parent traversal in middle is unsafe" {
+  _is_unsafe_path "foo/../../etc/passwd"
+}
+
+@test "parent traversal at end is unsafe" {
+  _is_unsafe_path "foo/.."
+}
+
+@test "bare double-dot is unsafe" {
+  _is_unsafe_path ".."
+}
+
+@test "dotfile is safe" {
+  ! _is_unsafe_path ".env"
+}
+
+@test "nested relative path is safe" {
+  ! _is_unsafe_path "src/lib/utils.js"
+}
+
+@test "glob pattern is safe" {
+  ! _is_unsafe_path "*.txt"
+}
+
+@test "double-star glob is safe" {
+  ! _is_unsafe_path "**/*.js"
+}
+
+# --- is_excluded tests ---
+
+@test "exact match is excluded" {
+  is_excluded "node_modules" "node_modules"
+}
+
+@test "non-matching path is not excluded" {
+  ! is_excluded "src/index.js" "node_modules"
+}
+
+@test "glob pattern excludes matching path" {
+  is_excluded "build/output.js" "build/*"
+}
+
+@test "empty excludes means nothing excluded" {
+  ! is_excluded "anything" ""
+}
+
+@test "multiple excludes work" {
+  local excludes
+  excludes=$(printf '%s\n' "*.log" "dist/*" "node_modules")
+  is_excluded "error.log" "$excludes"
+}
+
+@test "multiple excludes check all patterns" {
+  local excludes
+  excludes=$(printf '%s\n' "*.log" "dist/*" "node_modules")
+  is_excluded "dist/bundle.js" "$excludes"
+}
+
+@test "non-matching against multiple excludes" {
+  local excludes
+  excludes=$(printf '%s\n' "*.log" "dist/*")
+  ! is_excluded "src/app.js" "$excludes"
+}
diff --git a/tests/resolve_base_dir.bats b/tests/resolve_base_dir.bats
new file mode 100644
index 0000000..8fca8ad
--- /dev/null
+++ b/tests/resolve_base_dir.bats
@@ -0,0 +1,40 @@
+#!/usr/bin/env bats
+
+setup() {
+  load test_helper
+  source "$PROJECT_ROOT/lib/core.sh"
+
+  # Create a temporary git repo for testing
+  TEST_REPO=$(mktemp -d)
+  git -C "$TEST_REPO" init --quiet
+  git -C "$TEST_REPO" commit --allow-empty -m "init" --quiet
+}
+
+teardown() {
+  rm -rf "$TEST_REPO"
+}
+
+@test "default base dir is repo-worktrees sibling" {
+  result=$(resolve_base_dir "$TEST_REPO")
+  expected="$(dirname "$TEST_REPO")/$(basename "$TEST_REPO")-worktrees"
+  [ "$result" = "$expected" ]
+}
+
+@test "absolute path config is used as-is" {
+  # Override cfg_default to return an absolute path
+  cfg_default() { printf "/custom/worktrees"; }
+  result=$(resolve_base_dir "$TEST_REPO")
+  [ "$result" = "/custom/worktrees" ]
+}
+
+@test "tilde in path is expanded" {
+  cfg_default() { printf "~/my-worktrees"; }
+  result=$(resolve_base_dir "$TEST_REPO")
+  [ "$result" = "$HOME/my-worktrees" ]
+}
+
+@test "relative path is resolved from repo root" {
+  cfg_default() { printf ".worktrees"; }
+  result=$(resolve_base_dir "$TEST_REPO")
+  [ "$result" = "$TEST_REPO/.worktrees" ]
+}
diff --git a/tests/sanitize_branch_name.bats b/tests/sanitize_branch_name.bats
new file mode 100644
index 0000000..6aa3352
--- /dev/null
+++ b/tests/sanitize_branch_name.bats
@@ -0,0 +1,51 @@
+#!/usr/bin/env bats
+
+setup() {
+  load test_helper
+  source "$PROJECT_ROOT/lib/core.sh"
+}
+
+@test "simple branch name passes through unchanged" {
+  result=$(sanitize_branch_name "my-feature")
+  [ "$result" = "my-feature" ]
+}
+
+@test "slashes are replaced with hyphens" {
+  result=$(sanitize_branch_name "feature/user-auth")
+  [ "$result" = "feature-user-auth" ]
+}
+
+@test "nested slashes are replaced" {
+  result=$(sanitize_branch_name "org/team/feature")
+  [ "$result" = "org-team-feature" ]
+}
+
+@test "spaces are replaced with hyphens" {
+  result=$(sanitize_branch_name "my feature branch")
+  [ "$result" = "my-feature-branch" ]
+}
+
+@test "colons are replaced with hyphens" {
+  result=$(sanitize_branch_name "fix:bug")
+  [ "$result" = "fix-bug" ]
+}
+
+@test "leading hyphens are stripped" {
+  result=$(sanitize_branch_name "/leading-slash")
+  [ "$result" = "leading-slash" ]
+}
+
+@test "trailing hyphens are stripped" {
+  result=$(sanitize_branch_name "trailing-slash/")
+  [ "$result" = "trailing-slash" ]
+}
+
+@test "multiple special chars produce single hyphens" {
+  result=$(sanitize_branch_name "a//b")
+  [ "$result" = "a--b" ]
+}
+
+@test "backslashes are replaced" {
+  result=$(sanitize_branch_name 'feature\auth')
+  [ "$result" = "feature-auth" ]
+}
diff --git a/tests/test_helper.bash b/tests/test_helper.bash
new file mode 100644
index 0000000..e7a1ffe
--- /dev/null
+++ b/tests/test_helper.bash
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Shared test helper — sources libs with minimal stubs for isolated testing
+
+TESTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$TESTS_DIR/.." && pwd)"
+
+# Stubs for ui.sh functions (avoid log output in tests)
+log_info() { :; }
+log_warn() { :; }
+log_error() { :; }
+log_step() { :; }
+export -f log_info log_warn log_error log_step
+
+# Stubs for config.sh functions (tests that need real config should source it explicitly)
+cfg_default() { printf "%s" "${3:-}"; }
+cfg_get_all() { :; }
+export -f cfg_default cfg_get_all

From 5368d32531bcc7b34e67c00a7b0d50371e40c74b Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 16:22:21 -0800
Subject: [PATCH 05/19] fix: address CI failures and review feedback

- Add apt-get update before installs in CI workflow
- Suppress SC2317 on nested adapter functions in bin/gtr
- Replace SC2015 pattern with if-statement in lib/copy.sh
- Pre-compute AppleScript cmd line to avoid set -e abort in heredoc
- Add git identity config in test setup for CI environments
- Fix misleading test description for special char replacement
---
 .github/workflows/lint.yml      | 4 ++--
 bin/gtr                         | 6 ++++++
 lib/copy.sh                     | 4 +++-
 lib/platform.sh                 | 8 +++++++-
 tests/resolve_base_dir.bats     | 2 ++
 tests/sanitize_branch_name.bats | 2 +-
 6 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index e24cfa9..ba9c881 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install ShellCheck
-        run: sudo apt-get install -y shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
 
       - name: Run ShellCheck
         run: |
@@ -27,7 +27,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install BATS
-        run: sudo apt-get install -y bats
+        run: sudo apt-get update && sudo apt-get install -y bats
 
       - name: Run tests
         run: bats tests/
diff --git a/bin/gtr b/bin/gtr
index 23ee89d..4393306 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -69,10 +69,12 @@ ai_start() {
 # Standard AI adapter builder — used by adapter files that follow the common pattern
 # Sets globals then call this: _AI_CMD, _AI_ERR_MSG, _AI_INFO_LINES (array)
 _ai_define_standard() {
+  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
   ai_can_start() {
     command -v "$_AI_CMD" >/dev/null 2>&1
   }
 
+  # shellcheck disable=SC2317
   ai_start() {
     local path="$1"; shift
     if ! ai_can_start; then
@@ -94,10 +96,12 @@ _ai_define_standard() {
 # Standard editor adapter builder — used by adapter files that follow the common pattern
 # Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_WORKSPACE (optional, 0 or 1)
 _editor_define_standard() {
+  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
   editor_can_open() {
     command -v "$_EDITOR_CMD" >/dev/null 2>&1
   }
 
+  # shellcheck disable=SC2317
   editor_open() {
     local path="$1"
     local workspace="${2:-}"
@@ -116,10 +120,12 @@ _editor_define_standard() {
 # Terminal editor adapter builder — for editors that run in the current terminal
 # Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_BACKGROUND (optional, 0 or 1)
 _editor_define_terminal() {
+  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
   editor_can_open() {
     command -v "$_EDITOR_CMD" >/dev/null 2>&1
   }
 
+  # shellcheck disable=SC2317
   editor_open() {
     local path="$1"
     if ! editor_can_open; then
diff --git a/lib/copy.sh b/lib/copy.sh
index 14f34aa..accd4e2 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -299,7 +299,9 @@ copy_directories() {
                     cd "$exclude_old_pwd" || true
 
                     # Log only if we actually removed something
-                    [ "$removed_any" -eq 1 ] && log_info "Excluded subdirectory $exclude_pattern" || true
+                    if [ "$removed_any" -eq 1 ]; then
+                      log_info "Excluded subdirectory $exclude_pattern"
+                    fi
                     ;;
                 esac
                 ;;
diff --git a/lib/platform.sh b/lib/platform.sh
index e4e89b3..eea44d6 100644
--- a/lib/platform.sh
+++ b/lib/platform.sh
@@ -96,6 +96,12 @@ spawn_terminal_in() {
       safe_title=$(_escape_applescript "$title")
       safe_cmd=$(_escape_applescript "$cmd")
 
+      # Pre-compute optional AppleScript write-text line (avoids set -e abort in heredoc)
+      local iterm_cmd_line=""
+      if [ -n "$safe_cmd" ]; then
+        iterm_cmd_line="write text \"$safe_cmd\""
+      fi
+
       # Try iTerm2 first, then Terminal.app
       if osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true' 2>/dev/null | grep -q "iTerm"; then
         osascript <<-EOF 2>/dev/null || true
@@ -105,7 +111,7 @@ spawn_terminal_in() {
 							tell current session
 								write text "cd \"$safe_path\""
 								set name to "$safe_title"
-								$([ -n "$safe_cmd" ] && echo "write text \"$safe_cmd\"")
+								$iterm_cmd_line
 							end tell
 						end tell
 					end tell
diff --git a/tests/resolve_base_dir.bats b/tests/resolve_base_dir.bats
index 8fca8ad..8a4fede 100644
--- a/tests/resolve_base_dir.bats
+++ b/tests/resolve_base_dir.bats
@@ -7,6 +7,8 @@ setup() {
   # Create a temporary git repo for testing
   TEST_REPO=$(mktemp -d)
   git -C "$TEST_REPO" init --quiet
+  git -C "$TEST_REPO" config user.name "Test User"
+  git -C "$TEST_REPO" config user.email "test@example.com"
   git -C "$TEST_REPO" commit --allow-empty -m "init" --quiet
 }
 
diff --git a/tests/sanitize_branch_name.bats b/tests/sanitize_branch_name.bats
index 6aa3352..69e89c9 100644
--- a/tests/sanitize_branch_name.bats
+++ b/tests/sanitize_branch_name.bats
@@ -40,7 +40,7 @@ setup() {
   [ "$result" = "trailing-slash" ]
 }
 
-@test "multiple special chars produce single hyphens" {
+@test "multiple special chars are each replaced" {
   result=$(sanitize_branch_name "a//b")
   [ "$result" = "a--b" ]
 }

From 25ede699673f808b688dcf711874c8e3ba51130c Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 16:26:18 -0800
Subject: [PATCH 06/19] refactor: improve error handling in copy_directories
 function

Update the copy_directories function in lib/copy.sh to enhance error handling by using a conditional statement for the removal of matched paths. This change ensures that the removal status is only set when the command succeeds, improving code clarity and maintainability.
---
 lib/copy.sh | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/copy.sh b/lib/copy.sh
index accd4e2..9ed56dd 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -290,7 +290,9 @@ copy_directories() {
                     for matched_path in $pattern_suffix; do
                       # Check if glob matched anything (avoid literal pattern if no match)
                       if [ -e "$matched_path" ]; then
-                        rm -rf "$matched_path" 2>/dev/null && removed_any=1 || true
+                        if rm -rf "$matched_path" 2>/dev/null; then
+                          removed_any=1
+                        fi
                       fi
                     done
 

From 98858e3feb1d12f4659d6df87473e1f7c58bf9a3 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 16:31:59 -0800
Subject: [PATCH 07/19] refactor: enhance current_branch function for better
 detection

Update the current_branch function to handle cases where the branch is either empty or set to HEAD, normalizing the output to indicate a detached state. Additionally, refactor cmd_list to utilize the updated current_branch function, improving code clarity and maintainability.
---
 bin/gtr     | 10 ++--------
 lib/core.sh |  4 ++--
 2 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/bin/gtr b/bin/gtr
index 4393306..64e7064 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -1055,10 +1055,7 @@ cmd_list() {
   if [ "$porcelain" -eq 1 ]; then
     # Output: path<tab>branch<tab>status
     local branch status
-    branch=$(get_current_branch "$repo_root")
-    if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
-      branch="(detached)"
-    fi
+    branch=$(current_branch "$repo_root")
     status=$(worktree_status "$repo_root")
     printf "%s\t%s\t%s\n" "$repo_root" "$branch" "$status"
 
@@ -1086,10 +1083,7 @@ cmd_list() {
 
   # Always show repo root first
   local branch
-  branch=$(get_current_branch "$repo_root")
-  if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
-    branch="(detached)"
-  fi
+  branch=$(current_branch "$repo_root")
   printf "%-30s %s\n" "$branch [main repo]" "$repo_root"
 
   # Show worktrees sorted by branch name
diff --git a/lib/core.sh b/lib/core.sh
index e7a2b2f..4663361 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -166,8 +166,8 @@ current_branch() {
   local branch
   branch=$(get_current_branch "$worktree_path")
 
-  # Normalize detached HEAD
-  if [ "$branch" = "HEAD" ]; then
+  # Normalize detached HEAD or empty (failed detection)
+  if [ -z "$branch" ] || [ "$branch" = "HEAD" ]; then
     branch="(detached)"
   fi
 

From e56424d8997f9b1aa5831e361b3f32dee464f2ee Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 16:58:35 -0800
Subject: [PATCH 08/19] refactor: enhance adapter management and command
 structure

- Introduced a new adapter loading infrastructure in `lib/adapters.sh`, consolidating editor and AI adapter definitions into registries for improved maintainability.
- Updated the `bin/gtr` script to source command handlers dynamically, streamlining command execution.
- Added new commands for listing available adapters and starting AI tools, enhancing user interaction and functionality.
- Removed outdated individual adapter scripts, transitioning to a registry-based approach for standard adapters, which simplifies the addition of new tools.
- Improved documentation in various instruction files to clarify when to use registry entries versus custom adapter files.
---
 .github/instructions/ai.instructions.md     |   26 +-
 .github/instructions/editor.instructions.md |   30 +-
 .github/instructions/lib.instructions.md    |    2 +-
 .github/workflows/lint.yml                  |    2 +-
 CLAUDE.md                                   |   38 +-
 CONTRIBUTING.md                             |   83 +-
 adapters/ai/aider.sh                        |    7 -
 adapters/ai/auggie.sh                       |    7 -
 adapters/ai/codex.sh                        |   10 -
 adapters/ai/continue.sh                     |    7 -
 adapters/ai/copilot.sh                      |   11 -
 adapters/ai/gemini.sh                       |   10 -
 adapters/ai/opencode.sh                     |    7 -
 adapters/editor/atom.sh                     |    6 -
 adapters/editor/cursor.sh                   |    7 -
 adapters/editor/emacs.sh                    |    7 -
 adapters/editor/idea.sh                     |    6 -
 adapters/editor/nvim.sh                     |    6 -
 adapters/editor/pycharm.sh                  |    6 -
 adapters/editor/sublime.sh                  |    6 -
 adapters/editor/vim.sh                      |    6 -
 adapters/editor/vscode.sh                   |    7 -
 adapters/editor/webstorm.sh                 |    6 -
 adapters/editor/zed.sh                      |    6 -
 bin/gtr                                     | 2077 +------------------
 lib/adapters.sh                             |  324 +++
 lib/commands/adapter.sh                     |   87 +
 lib/commands/ai.sh                          |   67 +
 lib/commands/clean.sh                       |  187 ++
 lib/commands/completion.sh                  |   63 +
 lib/commands/config.sh                      |  143 ++
 lib/commands/copy.sh                        |  122 ++
 lib/commands/create.sh                      |  304 +++
 lib/commands/doctor.sh                      |  116 ++
 lib/commands/editor.sh                      |   52 +
 lib/commands/go.sh                          |   29 +
 lib/commands/help.sh                        |  220 ++
 lib/commands/init.sh                        |  196 ++
 lib/commands/list.sh                        |   75 +
 lib/commands/remove.sh                      |   95 +
 lib/commands/rename.sh                      |  116 ++
 lib/commands/run.sh                         |   58 +
 lib/core.sh                                 |    7 +-
 43 files changed, 2368 insertions(+), 2279 deletions(-)
 delete mode 100644 adapters/ai/aider.sh
 delete mode 100644 adapters/ai/auggie.sh
 delete mode 100644 adapters/ai/codex.sh
 delete mode 100644 adapters/ai/continue.sh
 delete mode 100644 adapters/ai/copilot.sh
 delete mode 100644 adapters/ai/gemini.sh
 delete mode 100644 adapters/ai/opencode.sh
 delete mode 100755 adapters/editor/atom.sh
 delete mode 100644 adapters/editor/cursor.sh
 delete mode 100755 adapters/editor/emacs.sh
 delete mode 100755 adapters/editor/idea.sh
 delete mode 100755 adapters/editor/nvim.sh
 delete mode 100755 adapters/editor/pycharm.sh
 delete mode 100755 adapters/editor/sublime.sh
 delete mode 100755 adapters/editor/vim.sh
 delete mode 100644 adapters/editor/vscode.sh
 delete mode 100755 adapters/editor/webstorm.sh
 delete mode 100644 adapters/editor/zed.sh
 create mode 100644 lib/adapters.sh
 create mode 100644 lib/commands/adapter.sh
 create mode 100644 lib/commands/ai.sh
 create mode 100644 lib/commands/clean.sh
 create mode 100644 lib/commands/completion.sh
 create mode 100644 lib/commands/config.sh
 create mode 100644 lib/commands/copy.sh
 create mode 100644 lib/commands/create.sh
 create mode 100644 lib/commands/doctor.sh
 create mode 100644 lib/commands/editor.sh
 create mode 100644 lib/commands/go.sh
 create mode 100644 lib/commands/help.sh
 create mode 100644 lib/commands/init.sh
 create mode 100644 lib/commands/list.sh
 create mode 100644 lib/commands/remove.sh
 create mode 100644 lib/commands/rename.sh
 create mode 100644 lib/commands/run.sh

diff --git a/.github/instructions/ai.instructions.md b/.github/instructions/ai.instructions.md
index bde7500..51d8eee 100644
--- a/.github/instructions/ai.instructions.md
+++ b/.github/instructions/ai.instructions.md
@@ -2,11 +2,26 @@
 applyTo: adapters/ai/**/*.sh
 ---
 
-# AI Instructions
+# AI Adapter Instructions
 
-## Adding Features
+## When to Use a File vs Registry
 
-### New AI Tool Adapter (`adapters/ai/<name>.sh`)
+Most AI tools are defined as **registry entries** in `lib/adapters.sh` — no adapter file needed.
+Only create an adapter file in `adapters/ai/` for tools that need **custom behavior** beyond the standard builder (see `claude.sh` or `cursor.sh` for examples).
+
+## Adding a Standard AI Tool (Registry)
+
+Add a line to `_AI_REGISTRY` in `lib/adapters.sh`:
+
+```
+yourname|yourcmd|ToolName not found. Install with: ...|Extra info;More info
+```
+
+Format: `name|cmd|err_msg|info_lines` (info lines are semicolon-separated)
+
+## Adding a Custom AI Tool (File Override)
+
+Create `adapters/ai/<name>.sh` implementing:
 
 ```bash
 #!/usr/bin/env bash
@@ -27,7 +42,9 @@ ai_start() {
 }
 ```
 
-**Also update**: Same as editor adapters (README, completions, help text)
+File-based adapters take precedence over registry entries of the same name.
+
+**Also update**: README, completions (bash/zsh/fish), help text in `lib/commands/help.sh`
 
 ## Contract & Guidelines
 
@@ -38,5 +55,4 @@ ai_start() {
 - Accept extra args after `--`: preserve ordering (`ai_start` receives already-shifted args).
 - Prefer fast startup; heavy initialization belongs in hooks (`postCreate`), not adapters.
 - When adding adapter: update `cmd_help`, README tool list, and completions (bash/zsh/fish).
-- Test manually: `bash -c 'source adapters/ai/<tool>.sh && ai_can_start && echo OK'`.
 - Inspect function definition if needed: `declare -f ai_start`.
diff --git a/.github/instructions/editor.instructions.md b/.github/instructions/editor.instructions.md
index 6bd84ba..7bc3c3d 100644
--- a/.github/instructions/editor.instructions.md
+++ b/.github/instructions/editor.instructions.md
@@ -2,11 +2,28 @@
 applyTo: adapters/editor/**/*.sh
 ---
 
-# Editor Instructions
+# Editor Adapter Instructions
 
-## Adding Features
+## When to Use a File vs Registry
 
-### New Editor Adapter (`adapters/editor/<name>.sh`)
+Most editors are defined as **registry entries** in `lib/adapters.sh` — no adapter file needed.
+Only create an adapter file in `adapters/editor/` for editors that need **custom behavior** beyond what the standard/terminal builders provide (see `nano.sh` for an example).
+
+## Adding a Standard Editor (Registry)
+
+Add a line to `_EDITOR_REGISTRY` in `lib/adapters.sh`:
+
+```
+yourname|yourcmd|standard|EditorName not found. Install from https://...|flags
+```
+
+Format: `name|cmd|type|err_msg|flags`
+- `type`: `standard` (GUI app) or `terminal` (runs in terminal)
+- `flags`: comma-separated — `workspace` (supports .code-workspace), `background` (terminal bg)
+
+## Adding a Custom Editor (File Override)
+
+Create `adapters/editor/<name>.sh` implementing:
 
 ```bash
 #!/usr/bin/env bash
@@ -26,11 +43,13 @@ editor_open() {
 }
 ```
 
+File-based adapters take precedence over registry entries of the same name.
+
 **Also update**:
 
 - README.md (setup instructions)
 - All three completion files: `completions/gtr.bash`, `completions/_git-gtr`, `completions/gtr.fish`
-- Help text in `bin/gtr` (`cmd_help` function)
+- Help text in `lib/commands/help.sh` (`cmd_help` function)
 
 ## Contract & Guidelines
 
@@ -38,8 +57,7 @@ editor_open() {
 - Quote all paths; support spaces. Avoid changing PWD globally—no subshell needed (editor opens path).
 - Use `log_error` with actionable install guidance if command missing.
 - Keep adapter lean: no project scans, no blocking prompts.
-- Naming: file name = tool name (`zed.sh` → `zed` flag). Avoid uppercase.
+- Naming: file/registry name = tool name (`zed` → `zed` flag). Avoid uppercase.
 - Update: README editor list, completions (bash/zsh/fish), help (`Available editors:`), optional screenshots.
-- Manual test: `bash -c 'source adapters/editor/<tool>.sh && editor_can_open && editor_open . || echo fail'`.
 - Fallback behavior: if editor absent, fail clearly; do NOT silently defer to file browser.
 - Inspect function definition if needed: `declare -f editor_open`.
diff --git a/.github/instructions/lib.instructions.md b/.github/instructions/lib.instructions.md
index d44ed19..717a759 100644
--- a/.github/instructions/lib.instructions.md
+++ b/.github/instructions/lib.instructions.md
@@ -21,7 +21,7 @@ applyTo: lib/**/*.sh
 
 ## Change Guidelines
 
-- Preserve adapter contracts; do not rename exported functions used by `bin/gtr`.
+- Preserve adapter contracts; do not rename exported functions used by command handlers in `lib/commands/`.
 - Add new config keys with `gtr.<name>` prefix; avoid collisions.
 - For performance-sensitive loops (e.g. directory scans) prefer built-ins (`find`, `grep`) with minimal subshells.
 - Any new Git command: add fallback for older versions or guard with detection.
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index ba9c881..f7dfeac 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -18,7 +18,7 @@ jobs:
 
       - name: Run ShellCheck
         run: |
-          shellcheck bin/gtr bin/git-gtr lib/*.sh adapters/editor/*.sh adapters/ai/*.sh
+          shellcheck bin/gtr bin/git-gtr lib/*.sh lib/commands/*.sh adapters/editor/*.sh adapters/ai/*.sh
 
   test:
     name: Tests
diff --git a/CLAUDE.md b/CLAUDE.md
index 1f3184d..3cf71c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,28 +39,30 @@ mkdir -p /tmp/gtr-test && cd /tmp/gtr-test && git init && git commit --allow-emp
 ### Binary Structure
 
 - `bin/git-gtr` — Thin wrapper enabling `git gtr` subcommand invocation
-- `bin/gtr` — Main script (~1960 lines), contains `main()` dispatcher + all `cmd_*` handlers
+- `bin/gtr` — Entry point (~105 lines): sources libraries and commands, contains `main()` dispatcher
 
 ### Module Structure
 
-| File              | Purpose                                                                                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------- |
-| `lib/core.sh`     | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
-| `lib/config.sh`   | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
-| `lib/copy.sh`     | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
-| `lib/hooks.sh`    | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
-| `lib/ui.sh`       | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
-| `lib/platform.sh` | OS detection, GUI helpers                                                                                   |
+| File               | Purpose                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `lib/core.sh`      | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
+| `lib/config.sh`    | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
+| `lib/copy.sh`      | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
+| `lib/hooks.sh`     | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
+| `lib/ui.sh`        | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
+| `lib/platform.sh`  | OS detection, GUI helpers                                                                                   |
+| `lib/adapters.sh`  | Adapter registry, builder functions, generic fallbacks, loader functions                                    |
+| `lib/commands/*.sh` | One file per subcommand: `cmd_create`, `cmd_remove`, etc. (16 files)                                       |
 
 ### Adapters
 
-Editor adapters in `adapters/editor/` and AI adapters in `adapters/ai/` are dynamically sourced via `load_editor_adapter()` and `load_ai_adapter()` in `bin/gtr`.
+Most adapters are defined declaratively in the **adapter registry** (`lib/adapters.sh`) using pipe-delimited entries. Custom adapters that need special logic remain as override files in `adapters/editor/` and `adapters/ai/`.
 
-**Editor adapters** (atom, cursor, emacs, idea, nano, nvim, pycharm, sublime, vim, vscode, webstorm, zed): implement `editor_can_open()` + `editor_open(path)`.
+**Registry-defined adapters**: atom, cursor, emacs, idea, nvim, pycharm, sublime, vim, vscode, webstorm, zed (editors) and aider, auggie, codex, continue, copilot, gemini, opencode (AI).
 
-**AI adapters** (aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode): implement `ai_can_start()` + `ai_start(path, args...)`.
+**Custom adapter files**: `adapters/editor/nano.sh`, `adapters/ai/claude.sh`, `adapters/ai/cursor.sh` — these implement `editor_can_open()`/`editor_open()` or `ai_can_start()`/`ai_start()` directly.
 
-**Generic fallback**: `GTR_EDITOR_CMD` / `GTR_AI_CMD` env vars allow custom tools without adapter files.
+**Loading order**: file override → registry → generic PATH fallback. `GTR_EDITOR_CMD` / `GTR_AI_CMD` env vars allow custom tools without adapters.
 
 ### Command Flow
 
@@ -106,15 +108,17 @@ cmd_editor() → resolve_target() → load_editor_adapter() → editor_open()
 
 ### Adding a New Command
 
-1. Add `cmd_<name>()` function in `bin/gtr`
-2. Add case entry in `main()` dispatcher (around line 71)
-3. Add help text in `cmd_help()`
+1. Create `lib/commands/<name>.sh` with `cmd_<name>()` function
+2. Add case entry in `main()` dispatcher in `bin/gtr`
+3. Add help text in `lib/commands/help.sh`
 4. Update all three completion files: `completions/gtr.bash`, `completions/_git-gtr`, `completions/git-gtr.fish`
 5. Update README.md
 
 ### Adding an Adapter
 
-Create `adapters/{editor,ai}/<name>.sh` implementing the two required functions (see existing adapters for patterns). Then update: help text in `cmd_help()` and `load_*_adapter()`, all three completions, README.md.
+**Standard adapters** (just a command name + error message): Add an entry to `_EDITOR_REGISTRY` or `_AI_REGISTRY` in `lib/adapters.sh`. Then update: help text in `lib/commands/help.sh`, all three completions, README.md.
+
+**Custom adapters** (special logic needed): Create `adapters/{editor,ai}/<name>.sh` implementing the two required functions (see `adapters/ai/claude.sh` for an example). File-based adapters take priority over registry entries.
 
 ### Updating the Version
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1594849..5c0b5ef 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,17 +32,25 @@ We welcome feature suggestions! Please:
 
 ```
 git-worktree-runner/
-├── bin/gtr              # Main executable dispatcher
+├── bin/gtr              # Main executable (~105 lines: sources libs, dispatches commands)
 ├── lib/                 # Core functionality
-│   ├── core.sh         # Git worktree operations
+│   ├── ui.sh           # User interface (logging, prompts)
 │   ├── config.sh       # Configuration (git-config wrapper)
 │   ├── platform.sh     # OS-specific utilities
-│   ├── ui.sh           # User interface (logging, prompts)
+│   ├── core.sh         # Git worktree operations
 │   ├── copy.sh         # File copying logic
-│   └── hooks.sh        # Hook execution
-├── adapters/           # Pluggable integrations
-│   ├── editor/         # Editor adapters (cursor, vscode, zed)
-│   └── ai/             # AI tool adapters (aider)
+│   ├── hooks.sh        # Hook execution
+│   ├── provider.sh     # GitHub/GitLab provider detection
+│   ├── adapters.sh     # Adapter registries, builders, and loaders
+│   └── commands/       # Command handlers (one file per command)
+│       ├── create.sh   # cmd_create + helpers
+│       ├── remove.sh   # cmd_remove
+│       ├── rename.sh   # cmd_rename
+│       ├── ...         # (16 files total, one per command)
+│       └── help.sh     # cmd_help
+├── adapters/           # Custom adapter overrides (non-registry)
+│   ├── editor/nano.sh  # nano (custom terminal behavior)
+│   └── ai/             # claude.sh, cursor.sh (custom logic)
 ├── completions/        # Shell completions (bash, zsh, fish)
 └── templates/          # Example configs and scripts
 ```
@@ -92,60 +100,43 @@ do_something() {
 
 #### Adding an Editor Adapter
 
-1. Create `adapters/editor/yourname.sh`:
+Most editors follow a standard pattern and can be added as a **registry entry** in `lib/adapters.sh` (no separate file needed).
 
-```bash
-#!/usr/bin/env bash
-# YourEditor adapter
+**Option A: Registry entry** (preferred for standard editors)
 
-editor_can_open() {
-  command -v yourcommand >/dev/null 2>&1
-}
+Add a line to `_EDITOR_REGISTRY` in `lib/adapters.sh`:
 
-editor_open() {
-  local path="$1"
+```
+yourname|yourcmd|standard|YourEditor not found. Install from https://...|flags
+```
 
-  if ! editor_can_open; then
-    log_error "YourEditor not found. Install from https://..."
-    return 1
-  fi
+Format: `name|cmd|type|err_msg|flags` where:
+- `type`: `standard` (GUI app) or `terminal` (runs in current terminal)
+- `flags`: comma-separated — `workspace` (supports .code-workspace files), `background` (run in background)
 
-  yourcommand "$path"
-}
-```
+**Option B: Custom adapter file** (for editors with non-standard behavior)
+
+Create `adapters/editor/yourname.sh` implementing `editor_can_open()` and `editor_open()`. See `adapters/editor/nano.sh` for an example.
 
-2. Update README.md with setup instructions
-3. Update completions to include new editor
-4. Test on macOS, Linux, and Windows if possible
+**Also update**: README.md, all three completion files, help text in `lib/commands/help.sh`.
 
 #### Adding an AI Tool Adapter
 
-1. Create `adapters/ai/yourtool.sh`:
+**Option A: Registry entry** (preferred for standard CLI tools)
 
-```bash
-#!/usr/bin/env bash
-# YourTool AI adapter
+Add a line to `_AI_REGISTRY` in `lib/adapters.sh`:
 
-ai_can_start() {
-  command -v yourtool >/dev/null 2>&1
-}
+```
+yourname|yourcmd|YourTool not found. Install with: ...|Extra info line 1;Extra info line 2
+```
 
-ai_start() {
-  local path="$1"
-  shift
+Format: `name|cmd|err_msg|info_lines` (info lines are semicolon-separated).
 
-  if ! ai_can_start; then
-    log_error "YourTool not found. Install with: ..."
-    return 1
-  fi
+**Option B: Custom adapter file** (for tools with non-standard behavior)
 
-  (cd "$path" && yourtool "$@")
-}
-```
+Create `adapters/ai/yourname.sh` implementing `ai_can_start()` and `ai_start()`. See `adapters/ai/claude.sh` for an example.
 
-2. Update README.md
-3. Update completions
-4. Add example usage
+**Also update**: README.md, completions, help text.
 
 #### Adding Core Features
 
diff --git a/adapters/ai/aider.sh b/adapters/ai/aider.sh
deleted file mode 100644
index bff7290..0000000
--- a/adapters/ai/aider.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# Aider AI coding assistant adapter
-
-_AI_CMD="aider"
-_AI_ERR_MSG="Aider not found. Install with: pip install aider-chat"
-_AI_INFO_LINES=("See https://aider.chat for more information")
-_ai_define_standard
diff --git a/adapters/ai/auggie.sh b/adapters/ai/auggie.sh
deleted file mode 100644
index 4f64093..0000000
--- a/adapters/ai/auggie.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# Auggie CLI AI adapter
-
-_AI_CMD="auggie"
-_AI_ERR_MSG="Auggie CLI not found. Install with: npm install -g @augmentcode/auggie"
-_AI_INFO_LINES=("See https://www.augmentcode.com/product/CLI for more information")
-_ai_define_standard
diff --git a/adapters/ai/codex.sh b/adapters/ai/codex.sh
deleted file mode 100644
index 2a3278f..0000000
--- a/adapters/ai/codex.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# OpenAI Codex CLI adapter
-
-_AI_CMD="codex"
-_AI_ERR_MSG="Codex CLI not found. Install with: npm install -g @openai/codex"
-_AI_INFO_LINES=(
-  "Or: brew install codex"
-  "See https://github.com/openai/codex for more info"
-)
-_ai_define_standard
diff --git a/adapters/ai/continue.sh b/adapters/ai/continue.sh
deleted file mode 100644
index eef2a52..0000000
--- a/adapters/ai/continue.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# Continue CLI adapter
-
-_AI_CMD="cn"
-_AI_ERR_MSG="Continue CLI not found. Install from https://continue.dev"
-_AI_INFO_LINES=("See https://docs.continue.dev/cli/install for installation")
-_ai_define_standard
diff --git a/adapters/ai/copilot.sh b/adapters/ai/copilot.sh
deleted file mode 100644
index e002742..0000000
--- a/adapters/ai/copilot.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/usr/bin/env bash
-# GitHub Copilot CLI adapter
-
-_AI_CMD="copilot"
-_AI_ERR_MSG="GitHub Copilot CLI not found."
-_AI_INFO_LINES=(
-  "Install with: npm install -g @github/copilot"
-  "Or: brew install copilot-cli"
-  "See https://github.com/github/copilot-cli for more information"
-)
-_ai_define_standard
diff --git a/adapters/ai/gemini.sh b/adapters/ai/gemini.sh
deleted file mode 100644
index 4c447ad..0000000
--- a/adapters/ai/gemini.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# Gemini CLI adapter
-
-_AI_CMD="gemini"
-_AI_ERR_MSG="Gemini CLI not found. Install with: npm install -g @google/gemini-cli"
-_AI_INFO_LINES=(
-  "Or: brew install gemini-cli"
-  "See https://github.com/google-gemini/gemini-cli for more info"
-)
-_ai_define_standard
diff --git a/adapters/ai/opencode.sh b/adapters/ai/opencode.sh
deleted file mode 100644
index 8c5782b..0000000
--- a/adapters/ai/opencode.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# OpenCode adapter
-
-_AI_CMD="opencode"
-_AI_ERR_MSG="OpenCode not found. Install from https://opencode.ai"
-_AI_INFO_LINES=("Make sure the 'opencode' CLI is available in your PATH")
-_ai_define_standard
diff --git a/adapters/editor/atom.sh b/adapters/editor/atom.sh
deleted file mode 100755
index 98fef7e..0000000
--- a/adapters/editor/atom.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Atom editor adapter
-
-_EDITOR_CMD="atom"
-_EDITOR_ERR_MSG="Atom not found. Install from https://atom.io"
-_editor_define_standard
diff --git a/adapters/editor/cursor.sh b/adapters/editor/cursor.sh
deleted file mode 100644
index a6f20bd..0000000
--- a/adapters/editor/cursor.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# Cursor editor adapter
-
-_EDITOR_CMD="cursor"
-_EDITOR_ERR_MSG="Cursor not found. Install from https://cursor.com or enable the shell command."
-_EDITOR_WORKSPACE=1
-_editor_define_standard
diff --git a/adapters/editor/emacs.sh b/adapters/editor/emacs.sh
deleted file mode 100755
index d0ba404..0000000
--- a/adapters/editor/emacs.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# Emacs editor adapter
-
-_EDITOR_CMD="emacs"
-_EDITOR_ERR_MSG="Emacs not found. Install from https://www.gnu.org/software/emacs/"
-_EDITOR_BACKGROUND=1
-_editor_define_terminal
diff --git a/adapters/editor/idea.sh b/adapters/editor/idea.sh
deleted file mode 100755
index e5369fe..0000000
--- a/adapters/editor/idea.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# IntelliJ IDEA editor adapter
-
-_EDITOR_CMD="idea"
-_EDITOR_ERR_MSG="IntelliJ IDEA 'idea' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
-_editor_define_standard
diff --git a/adapters/editor/nvim.sh b/adapters/editor/nvim.sh
deleted file mode 100755
index 61193df..0000000
--- a/adapters/editor/nvim.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Neovim editor adapter
-
-_EDITOR_CMD="nvim"
-_EDITOR_ERR_MSG="Neovim not found. Install from https://neovim.io"
-_editor_define_terminal
diff --git a/adapters/editor/pycharm.sh b/adapters/editor/pycharm.sh
deleted file mode 100755
index b10c7e5..0000000
--- a/adapters/editor/pycharm.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# PyCharm editor adapter
-
-_EDITOR_CMD="pycharm"
-_EDITOR_ERR_MSG="PyCharm 'pycharm' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
-_editor_define_standard
diff --git a/adapters/editor/sublime.sh b/adapters/editor/sublime.sh
deleted file mode 100755
index 8a997b2..0000000
--- a/adapters/editor/sublime.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Sublime Text editor adapter
-
-_EDITOR_CMD="subl"
-_EDITOR_ERR_MSG="Sublime Text 'subl' command not found. Install from https://www.sublimetext.com"
-_editor_define_standard
diff --git a/adapters/editor/vim.sh b/adapters/editor/vim.sh
deleted file mode 100755
index 3b41b1c..0000000
--- a/adapters/editor/vim.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Vim editor adapter
-
-_EDITOR_CMD="vim"
-_EDITOR_ERR_MSG="Vim not found. Install via your package manager."
-_editor_define_terminal
diff --git a/adapters/editor/vscode.sh b/adapters/editor/vscode.sh
deleted file mode 100644
index aac5719..0000000
--- a/adapters/editor/vscode.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# VS Code editor adapter
-
-_EDITOR_CMD="code"
-_EDITOR_ERR_MSG="VS Code 'code' command not found. Install from https://code.visualstudio.com"
-_EDITOR_WORKSPACE=1
-_editor_define_standard
diff --git a/adapters/editor/webstorm.sh b/adapters/editor/webstorm.sh
deleted file mode 100755
index 29ba7b9..0000000
--- a/adapters/editor/webstorm.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# WebStorm editor adapter
-
-_EDITOR_CMD="webstorm"
-_EDITOR_ERR_MSG="WebStorm 'webstorm' command not found. Enable shell launcher in Tools > Create Command-line Launcher"
-_editor_define_standard
diff --git a/adapters/editor/zed.sh b/adapters/editor/zed.sh
deleted file mode 100644
index 983a8a7..0000000
--- a/adapters/editor/zed.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Zed editor adapter
-
-_EDITOR_CMD="zed"
-_EDITOR_ERR_MSG="Zed not found. Install from https://zed.dev"
-_editor_define_standard
diff --git a/bin/gtr b/bin/gtr
index 64e7064..4eefd26 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -2,8 +2,6 @@
 # gtr - Git worktree runner
 # Portable, cross-platform git worktree management
 
-# shellcheck disable=SC2329 # Functions defined inside adapter builders are invoked indirectly
-
 set -e
 
 # Version
@@ -30,115 +28,13 @@ resolve_script_dir() {
 . "$GTR_DIR/lib/copy.sh"
 . "$GTR_DIR/lib/hooks.sh"
 . "$GTR_DIR/lib/provider.sh"
+. "$GTR_DIR/lib/adapters.sh"
 
-# Generic adapter functions (used when no explicit adapter file exists)
-# These will be overridden if an adapter file is sourced
-# Globals set by load_editor_adapter: GTR_EDITOR_CMD, GTR_EDITOR_CMD_NAME
-editor_can_open() {
-  command -v "$GTR_EDITOR_CMD_NAME" >/dev/null 2>&1
-}
-
-editor_open() {
-  local path="$1"
-  local workspace="${2:-}"
-  local target="$path"
-
-  # Use workspace file if provided and exists
-  if [ -n "$workspace" ] && [ -f "$workspace" ]; then
-    target="$workspace"
-  fi
-
-  # $GTR_EDITOR_CMD may contain arguments (e.g., "code --wait")
-  # Using eval here is necessary to handle multi-word commands properly
-  eval "$GTR_EDITOR_CMD \"\$target\""
-}
-
-# Globals set by load_ai_adapter: GTR_AI_CMD, GTR_AI_CMD_NAME
-ai_can_start() {
-  command -v "$GTR_AI_CMD_NAME" >/dev/null 2>&1
-}
-
-ai_start() {
-  local path="$1"
-  shift
-  # $GTR_AI_CMD may contain arguments (e.g., "bunx @github/copilot@latest")
-  # Using eval here is necessary to handle multi-word commands properly
-  (cd "$path" && eval "$GTR_AI_CMD \"\$@\"")
-}
-
-# Standard AI adapter builder — used by adapter files that follow the common pattern
-# Sets globals then call this: _AI_CMD, _AI_ERR_MSG, _AI_INFO_LINES (array)
-_ai_define_standard() {
-  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
-  ai_can_start() {
-    command -v "$_AI_CMD" >/dev/null 2>&1
-  }
-
-  # shellcheck disable=SC2317
-  ai_start() {
-    local path="$1"; shift
-    if ! ai_can_start; then
-      log_error "$_AI_ERR_MSG"
-      local _line
-      for _line in "${_AI_INFO_LINES[@]}"; do
-        log_info "$_line"
-      done
-      return 1
-    fi
-    if [ ! -d "$path" ]; then
-      log_error "Directory not found: $path"
-      return 1
-    fi
-    (cd "$path" && "$_AI_CMD" "$@")
-  }
-}
-
-# Standard editor adapter builder — used by adapter files that follow the common pattern
-# Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_WORKSPACE (optional, 0 or 1)
-_editor_define_standard() {
-  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
-  editor_can_open() {
-    command -v "$_EDITOR_CMD" >/dev/null 2>&1
-  }
-
-  # shellcheck disable=SC2317
-  editor_open() {
-    local path="$1"
-    local workspace="${2:-}"
-    if ! editor_can_open; then
-      log_error "$_EDITOR_ERR_MSG"
-      return 1
-    fi
-    if [ "${_EDITOR_WORKSPACE:-0}" = "1" ] && [ -n "$workspace" ] && [ -f "$workspace" ]; then
-      "$_EDITOR_CMD" "$workspace"
-    else
-      "$_EDITOR_CMD" "$path"
-    fi
-  }
-}
-
-# Terminal editor adapter builder — for editors that run in the current terminal
-# Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_BACKGROUND (optional, 0 or 1)
-_editor_define_terminal() {
-  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
-  editor_can_open() {
-    command -v "$_EDITOR_CMD" >/dev/null 2>&1
-  }
-
-  # shellcheck disable=SC2317
-  editor_open() {
-    local path="$1"
-    if ! editor_can_open; then
-      log_error "$_EDITOR_ERR_MSG"
-      return 1
-    fi
-    if [ "${_EDITOR_BACKGROUND:-0}" = "1" ]; then
-      "$_EDITOR_CMD" "$path" &
-    else
-      (cd "$path" && "$_EDITOR_CMD" .)
-    fi
-  }
-}
+# Source command handlers
+for _cmd_file in "$GTR_DIR"/lib/commands/*.sh; do
+  . "$_cmd_file"
+done
+unset _cmd_file
 
 # Main dispatcher
 main() {
@@ -205,1964 +101,5 @@ main() {
   esac
 }
 
-# Create command
-# Copy files and directories to newly created worktree
-# Usage: _post_create_copy repo_root worktree_path
-_post_create_copy() {
-  local repo_root="$1"
-  local worktree_path="$2"
-
-  local includes excludes file_includes
-  includes=$(cfg_get_all gtr.copy.include copy.include)
-  excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
-
-  # Read .worktreeinclude file if exists
-  file_includes=$(parse_pattern_file "$repo_root/.worktreeinclude")
-
-  # Merge patterns (newline-separated)
-  if [ -n "$file_includes" ]; then
-    if [ -n "$includes" ]; then
-      includes="$includes"$'\n'"$file_includes"
-    else
-      includes="$file_includes"
-    fi
-  fi
-
-  if [ -n "$includes" ]; then
-    log_step "Copying files..."
-    copy_patterns "$repo_root" "$worktree_path" "$includes" "$excludes"
-  fi
-
-  # Copy directories (typically git-ignored dirs like node_modules, .venv)
-  local dir_includes dir_excludes
-  dir_includes=$(cfg_get_all gtr.copy.includeDirs copy.includeDirs)
-  dir_excludes=$(cfg_get_all gtr.copy.excludeDirs copy.excludeDirs)
-
-  if [ -n "$dir_includes" ]; then
-    log_step "Copying directories..."
-    copy_directories "$repo_root" "$worktree_path" "$dir_includes" "$dir_excludes"
-  fi
-}
-
-# Show next steps after worktree creation (resolves collision for --folder overrides)
-# Usage: _post_create_next_steps branch_name folder_name folder_override repo_root base_dir prefix
-_post_create_next_steps() {
-  local branch_name="$1" folder_name="$2" folder_override="$3"
-  local repo_root="$4" base_dir="$5" prefix="$6"
-
-  local next_steps_id
-  if [ -n "$folder_override" ]; then
-    # Check if folder_name would resolve to main repo (collision with current branch)
-    local resolve_result
-    if resolve_result=$(resolve_target "$folder_name" "$repo_root" "$base_dir" "$prefix" 2>/dev/null); then
-      unpack_target "$resolve_result"
-      if [ "$_ctx_is_main" = "1" ]; then
-        # Collision: folder name matches current branch, use branch name instead
-        next_steps_id="$branch_name"
-      else
-        next_steps_id="$folder_name"
-      fi
-    else
-      next_steps_id="$folder_name"
-    fi
-  else
-    next_steps_id="$branch_name"
-  fi
-
-  echo ""
-  echo "Next steps:"
-  echo "  git gtr editor $next_steps_id  # Open in editor"
-  echo "  git gtr ai $next_steps_id      # Start AI tool"
-  echo "  cd \"\$(git gtr go $next_steps_id)\"  # Navigate to worktree"
-}
-
-# Determine the base ref for worktree creation
-# Usage: _create_resolve_from_ref <from_ref> <from_current> <repo_root>
-# Prints: resolved ref
-_create_resolve_from_ref() {
-  local from_ref="$1" from_current="$2" repo_root="$3"
-
-  if [ -z "$from_ref" ]; then
-    if [ "$from_current" -eq 1 ]; then
-      from_ref=$(get_current_branch)
-      if [ -z "$from_ref" ] || [ "$from_ref" = "HEAD" ]; then
-        log_warn "Currently in detached HEAD state - falling back to default branch"
-        from_ref=$(resolve_default_branch "$repo_root")
-      else
-        log_info "Creating from current branch: $from_ref"
-      fi
-    else
-      from_ref=$(resolve_default_branch "$repo_root")
-    fi
-  fi
-
-  printf "%s" "$from_ref"
-}
-
-# Auto-launch editor for a worktree
-_auto_launch_editor() {
-  local worktree_path="$1"
-  local editor
-  editor=$(cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor)
-  if [ "$editor" != "none" ]; then
-    load_editor_adapter "$editor" || return 1
-    local workspace_file
-    workspace_file=$(resolve_workspace_file "$worktree_path")
-    log_step "Opening in $editor..."
-    editor_open "$worktree_path" "$workspace_file"
-  else
-    open_in_gui "$worktree_path"
-    log_info "Opened in file browser (no editor configured)"
-  fi
-}
-
-# Auto-launch AI tool for a worktree
-_auto_launch_ai() {
-  local worktree_path="$1"
-  local ai_tool
-  ai_tool=$(cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai)
-  if [ "$ai_tool" = "none" ]; then
-    log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
-  else
-    load_ai_adapter "$ai_tool" || return 1
-    log_step "Starting $ai_tool..."
-    ai_start "$worktree_path"
-  fi
-}
-
-cmd_create() {
-  local branch_name=""
-  local from_ref=""
-  local from_current=0
-  local track_mode="auto"
-  local skip_copy=0
-  local skip_fetch=0
-  local skip_hooks=0
-  local yes_mode=0
-  local force=0
-  local custom_name=""
-  local folder_override=""
-  local open_editor=0
-  local start_ai=0
-
-  # Parse flags and arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --from)
-        from_ref="$2"
-        shift 2
-        ;;
-      --from-current)
-        from_current=1
-        shift
-        ;;
-      --track)
-        track_mode="$2"
-        shift 2
-        ;;
-      --no-copy)
-        skip_copy=1
-        shift
-        ;;
-      --no-fetch)
-        skip_fetch=1
-        shift
-        ;;
-      --no-hooks)
-        skip_hooks=1
-        shift
-        ;;
-      --yes)
-        yes_mode=1
-        shift
-        ;;
-      --force)
-        force=1
-        shift
-        ;;
-      --name)
-        custom_name="$2"
-        shift 2
-        ;;
-      --folder)
-        folder_override="$2"
-        shift 2
-        ;;
-      --editor|-e)
-        open_editor=1
-        shift
-        ;;
-      --ai|-a)
-        start_ai=1
-        shift
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        # Positional argument: treat as branch name
-        if [ -z "$branch_name" ]; then
-          branch_name="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
-
-  # Validate flag combinations
-  if [ -n "$folder_override" ] && [ -n "$custom_name" ]; then
-    log_error "--folder and --name cannot be used together"
-    exit 1
-  fi
-
-  if [ "$force" -eq 1 ] && [ -z "$custom_name" ] && [ -z "$folder_override" ]; then
-    log_error "--force requires --name or --folder to distinguish worktrees"
-    if [ -n "$branch_name" ]; then
-      echo "Example: git gtr new $branch_name --force --name backend" >&2
-      echo "     or: git gtr new $branch_name --force --folder my-folder" >&2
-    else
-      echo "Example: git gtr new feature-auth --force --name backend" >&2
-      echo "     or: git gtr new feature-auth --force --folder my-folder" >&2
-    fi
-    exit 1
-  fi
-
-  # Get repo info
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Get branch name if not provided
-  if [ -z "$branch_name" ]; then
-    if [ "$yes_mode" -eq 1 ]; then
-      log_error "Branch name required in non-interactive mode"
-      exit 1
-    fi
-    branch_name=$(prompt_input "Enter branch name:")
-    if [ -z "$branch_name" ]; then
-      log_error "Branch name required"
-      exit 1
-    fi
-  fi
-
-  # Determine from_ref with precedence: --from > --from-current > default
-  from_ref=$(_create_resolve_from_ref "$from_ref" "$from_current" "$repo_root")
-
-  # Construct folder name for display
-  local folder_name
-  if [ -n "$folder_override" ]; then
-    folder_name=$(sanitize_branch_name "$folder_override")
-  elif [ -n "$custom_name" ]; then
-    folder_name="$(sanitize_branch_name "$branch_name")-${custom_name}"
-  else
-    folder_name=$(sanitize_branch_name "$branch_name")
-  fi
-
-  log_step "Creating worktree: $folder_name"
-  echo "Location: $base_dir/${prefix}${folder_name}"
-  echo "Branch: $branch_name"
-
-  # Create the worktree
-  if ! worktree_path=$(create_worktree "$base_dir" "$prefix" "$branch_name" "$from_ref" "$track_mode" "$skip_fetch" "$force" "$custom_name" "$folder_override"); then
-    exit 1
-  fi
-
-  # Copy files based on patterns
-  if [ "$skip_copy" -eq 0 ]; then
-    _post_create_copy "$repo_root" "$worktree_path"
-  fi
-
-  # Run post-create hooks (unless --no-hooks)
-  if [ "$skip_hooks" -eq 0 ]; then
-    run_hooks_in postCreate "$worktree_path" \
-      REPO_ROOT="$repo_root" \
-      WORKTREE_PATH="$worktree_path" \
-      BRANCH="$branch_name"
-  fi
-
-  echo ""
-  log_info "Worktree created: $worktree_path"
-
-  # Auto-launch editor/AI or show next steps
-  [ "$open_editor" -eq 1 ] && { _auto_launch_editor "$worktree_path" || true; }
-  [ "$start_ai" -eq 1 ] && { _auto_launch_ai "$worktree_path" || true; }
-  if [ "$open_editor" -eq 0 ] && [ "$start_ai" -eq 0 ]; then
-    _post_create_next_steps "$branch_name" "$folder_name" "$folder_override" "$repo_root" "$base_dir" "$prefix"
-  fi
-}
-
-# Remove command
-cmd_remove() {
-  local delete_branch=0
-  local yes_mode=0
-  local force=0
-  local identifiers=""
-
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --delete-branch)
-        delete_branch=1
-        shift
-        ;;
-      --yes)
-        yes_mode=1
-        shift
-        ;;
-      --force)
-        force=1
-        shift
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        identifiers="$identifiers $1"
-        shift
-        ;;
-    esac
-  done
-
-  if [ -z "$identifiers" ]; then
-    log_error "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
-    exit 1
-  fi
-
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  for identifier in $identifiers; do
-    # Resolve target branch
-    local is_main worktree_path branch_name
-    resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || continue
-    is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch_name="$_ctx_branch"
-
-    # Cannot remove main repository
-    if [ "$is_main" = "1" ]; then
-      log_error "Cannot remove main repository"
-      continue
-    fi
-
-    log_step "Removing worktree: $(basename "$worktree_path")"
-
-    # Run pre-remove hooks (abort on failure unless --force)
-    if ! run_hooks_in preRemove "$worktree_path" \
-      REPO_ROOT="$repo_root" \
-      WORKTREE_PATH="$worktree_path" \
-      BRANCH="$branch_name"; then
-      if [ "$force" -eq 0 ]; then
-        log_error "Pre-remove hook failed for $branch_name. Use --force to skip hooks."
-        continue
-      else
-        log_warn "Pre-remove hook failed, continuing due to --force"
-      fi
-    fi
-
-    # Remove the worktree
-    if ! remove_worktree "$worktree_path" "$force"; then
-      continue
-    fi
-
-    # Handle branch deletion
-    if [ -n "$branch_name" ]; then
-      if [ "$delete_branch" -eq 1 ]; then
-        if [ "$yes_mode" -eq 1 ] || prompt_yes_no "Also delete branch '$branch_name'?"; then
-          if git branch -D "$branch_name" 2>/dev/null; then
-            log_info "Branch deleted: $branch_name"
-          else
-            log_warn "Could not delete branch: $branch_name"
-          fi
-        fi
-      fi
-    fi
-
-    # Run post-remove hooks
-    run_hooks postRemove \
-      REPO_ROOT="$repo_root" \
-      WORKTREE_PATH="$worktree_path" \
-      BRANCH="$branch_name"
-  done
-}
-
-# Rename command (rename worktree and branch)
-cmd_rename() {
-  local old_identifier=""
-  local new_name=""
-  local force=0
-  local yes_mode=0
-
-  # Parse flags and arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --force)
-        force=1
-        shift
-        ;;
-      --yes)
-        yes_mode=1
-        shift
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$old_identifier" ]; then
-          old_identifier="$1"
-        elif [ -z "$new_name" ]; then
-          new_name="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
-
-  # Validate arguments
-  if [ -z "$old_identifier" ] || [ -z "$new_name" ]; then
-    log_error "Usage: git gtr mv <old> <new> [--force] [--yes]"
-    exit 1
-  fi
-
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Resolve old worktree
-  local is_main old_path old_branch
-  resolve_worktree "$old_identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  is_main="$_ctx_is_main" old_path="$_ctx_worktree_path" old_branch="$_ctx_branch"
-
-  # Cannot rename main repository
-  if [ "$is_main" = "1" ]; then
-    log_error "Cannot rename main repository"
-    exit 1
-  fi
-
-  # Sanitize new name and construct new path
-  local new_sanitized new_path
-  new_sanitized=$(sanitize_branch_name "$new_name")
-  new_path="$base_dir/${prefix}${new_sanitized}"
-
-  # Check if new path already exists
-  if [ -d "$new_path" ]; then
-    log_error "Worktree already exists at: $new_path"
-    exit 1
-  fi
-
-  # Check if new branch name already exists
-  if git -C "$repo_root" show-ref --verify --quiet "refs/heads/$new_name"; then
-    log_error "Branch '$new_name' already exists"
-    exit 1
-  fi
-
-  log_step "Renaming worktree"
-  echo "Branch: $old_branch → $new_name"
-  echo "Folder: $(basename "$old_path") → ${prefix}${new_sanitized}"
-
-  # Confirm unless --yes
-  if [ "$yes_mode" -eq 0 ]; then
-    if ! prompt_yes_no "Proceed with rename?"; then
-      log_info "Cancelled"
-      exit 0
-    fi
-  fi
-
-  # Rename the branch first
-  if ! git -C "$repo_root" branch -m "$old_branch" "$new_name"; then
-    log_error "Failed to rename branch"
-    exit 1
-  fi
-
-  # Move the worktree
-  local move_args=()
-  if [ "$force" -eq 1 ]; then
-    move_args+=(--force)
-  fi
-
-  if ! git -C "$repo_root" worktree move "$old_path" "$new_path" "${move_args[@]}"; then
-    # Rollback: rename branch back
-    log_warn "Worktree move failed, rolling back branch rename..."
-    git -C "$repo_root" branch -m "$new_name" "$old_branch" 2>/dev/null || true
-    log_error "Failed to move worktree"
-    exit 1
-  fi
-
-  echo ""
-  log_info "Renamed: $old_branch → $new_name"
-  log_info "Location: $new_path"
-
-  # Check if remote tracking branch exists and warn
-  if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/$old_branch"; then
-    echo ""
-    log_warn "Remote branch 'origin/$old_branch' still exists"
-    log_info "To update remote, run:"
-    echo "  git push origin :$old_branch $new_name"
-  fi
-}
-
-# Go command (navigate to worktree - prints path for shell integration)
-cmd_go() {
-  if [ $# -ne 1 ]; then
-    log_error "Usage: git gtr go <id|branch>"
-    exit 1
-  fi
-
-  local identifier="$1"
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Resolve target branch
-  local is_main worktree_path branch
-  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
-
-  # Human messages to stderr so stdout can be used in command substitution
-  if [ "$is_main" = "1" ]; then
-    echo "Main repo" >&2
-  else
-    echo "Worktree: $branch" >&2
-  fi
-  echo "Branch: $branch" >&2
-
-  # Print path to stdout for shell integration: cd "$(gtr go my-feature)"
-  printf "%s\n" "$worktree_path"
-}
-
-# Run command (execute command in worktree directory)
-cmd_run() {
-  local identifier=""
-  local -a run_args=()
-
-  # Parse arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$identifier" ]; then
-          identifier="$1"
-          shift
-        else
-          run_args=("$@")  # Capture all remaining args as the command
-          break
-        fi
-        ;;
-    esac
-  done
-
-  # Validation
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr run <id|branch> <command...>"
-    exit 1
-  fi
-
-  if [ ${#run_args[@]} -eq 0 ]; then
-    log_error "Usage: git gtr run <id|branch> <command...>"
-    log_error "No command specified"
-    exit 1
-  fi
-
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Resolve target branch
-  local is_main worktree_path branch
-  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
-
-  # Human messages to stderr (like cmd_go)
-  if [ "$is_main" = "1" ]; then
-    log_step "Running in: main repo"
-  else
-    log_step "Running in: $branch"
-  fi
-  echo "Command: ${run_args[*]}" >&2
-  echo "" >&2
-
-  # Execute command in worktree directory (exit code propagates)
-  (cd "$worktree_path" && "${run_args[@]}")
-}
-
-# Copy command (copy files between worktrees)
-cmd_copy() {
-  local source="1"  # Default: main repo
-  local targets=""
-  local patterns=""
-  local all_mode=0
-  local dry_run=0
-
-  # Parse arguments (patterns come after -- separator, like git pathspec)
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --from)
-        source="$2"
-        shift 2
-        ;;
-      -n|--dry-run)
-        dry_run=1
-        shift
-        ;;
-      -a|--all)
-        all_mode=1
-        shift
-        ;;
-      --)
-        shift
-        # Remaining args are patterns (like git pathspec)
-        while [ $# -gt 0 ]; do
-          if [ -n "$patterns" ]; then
-            patterns="$patterns"$'\n'"$1"
-          else
-            patterns="$1"
-          fi
-          shift
-        done
-        break
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        targets="$targets $1"
-        shift
-        ;;
-    esac
-  done
-
-  # Validation
-  if [ "$all_mode" -eq 0 ] && [ -z "$targets" ]; then
-    log_error "Usage: git gtr copy <target>... [-n] [-a] [--from <source>] [-- <pattern>...]"
-    exit 1
-  fi
-
-  # Get repo context
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Resolve source path
-  local src_path
-  resolve_worktree "$source" "$repo_root" "$base_dir" "$prefix" || exit 1
-  src_path="$_ctx_worktree_path"
-
-  # Get patterns (flag > config)
-  if [ -z "$patterns" ]; then
-    patterns=$(cfg_get_all gtr.copy.include copy.include)
-    # Also check .worktreeinclude
-    if [ -f "$repo_root/.worktreeinclude" ]; then
-      local file_patterns
-      file_patterns=$(parse_pattern_file "$repo_root/.worktreeinclude")
-      if [ -n "$file_patterns" ]; then
-        if [ -n "$patterns" ]; then
-          patterns="$patterns"$'\n'"$file_patterns"
-        else
-          patterns="$file_patterns"
-        fi
-      fi
-    fi
-  fi
-
-  if [ -z "$patterns" ]; then
-    log_error "No patterns specified. Use '-- <pattern>...' or configure gtr.copy.include"
-    exit 1
-  fi
-
-  local excludes
-  excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
-
-  # Build target list for --all mode
-  if [ "$all_mode" -eq 1 ]; then
-    targets=$(list_worktree_branches "$base_dir" "$prefix")
-    if [ -z "$targets" ]; then
-      log_error "No worktrees found"
-      exit 1
-    fi
-  fi
-
-  # Process each target
-  local copied_any=0
-  for target_id in $targets; do
-    local dst_path dst_branch
-    resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue
-    dst_path="$_ctx_worktree_path" dst_branch="$_ctx_branch"
-
-    # Skip if source == destination
-    [ "$src_path" = "$dst_path" ] && continue
-
-    if [ "$dry_run" -eq 1 ]; then
-      log_step "[dry-run] Would copy to: $dst_branch"
-      copy_patterns "$src_path" "$dst_path" "$patterns" "$excludes" "true" "true"
-    else
-      log_step "Copying to: $dst_branch"
-      copy_patterns "$src_path" "$dst_path" "$patterns" "$excludes" "true"
-    fi
-    copied_any=1
-  done
-
-  if [ "$copied_any" -eq 0 ]; then
-    log_warn "No files copied (source and target may be the same)"
-  fi
-}
-
-# Editor command
-cmd_editor() {
-  local identifier=""
-  local editor=""
-
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --editor)
-        editor="$2"
-        shift 2
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$identifier" ]; then
-          identifier="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
-
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr editor <id|branch> [--editor <name>]"
-    exit 1
-  fi
-
-  # Get editor from flag or config (with .gtrconfig support)
-  if [ -z "$editor" ]; then
-    editor=$(cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor)
-  fi
-
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Resolve target branch
-  local worktree_path branch
-  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
-
-  if [ "$editor" = "none" ]; then
-    # Just open in GUI file browser
-    open_in_gui "$worktree_path"
-    log_info "Opened in file browser"
-  else
-    # Load editor adapter and open
-    load_editor_adapter "$editor" || exit 1
-    local workspace_file
-    workspace_file=$(resolve_workspace_file "$worktree_path")
-    log_step "Opening in $editor..."
-    editor_open "$worktree_path" "$workspace_file"
-  fi
-}
-
-# AI command
-cmd_ai() {
-  local identifier=""
-  local ai_tool=""
-  local -a ai_args=()
-
-  # Parse arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --ai)
-        ai_tool="$2"
-        shift 2
-        ;;
-      --)
-        shift
-        ai_args=("$@")
-        break
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$identifier" ]; then
-          identifier="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
-
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
-    exit 1
-  fi
-
-  # Get AI tool from flag or config (with .gtrconfig support)
-  if [ -z "$ai_tool" ]; then
-    ai_tool=$(cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai)
-  fi
-
-  # Check if AI tool is configured
-  if [ "$ai_tool" = "none" ]; then
-    log_error "No AI tool configured"
-    log_info "Set default: git gtr config set gtr.ai.default claude"
-    exit 1
-  fi
-
-  # Load AI adapter
-  load_ai_adapter "$ai_tool" || exit 1
-
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  # Resolve target branch
-  local worktree_path branch
-  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
-
-  log_step "Starting $ai_tool for: $branch"
-  echo "Directory: $worktree_path"
-  echo "Branch: $branch"
-
-  ai_start "$worktree_path" "${ai_args[@]}"
-}
-
-# List command
-cmd_list() {
-  local porcelain=0
-
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --porcelain)
-        porcelain=1
-        shift
-        ;;
-      *)
-        shift
-        ;;
-    esac
-  done
-
-  local repo_root base_dir prefix
-  repo_root=$(discover_repo_root) 2>/dev/null || return 0
-  base_dir=$(resolve_base_dir "$repo_root")
-  prefix=$(cfg_default gtr.worktrees.prefix GTR_WORKTREES_PREFIX "")
-
-  # Machine-readable output (porcelain)
-  if [ "$porcelain" -eq 1 ]; then
-    # Output: path<tab>branch<tab>status
-    local branch status
-    branch=$(current_branch "$repo_root")
-    status=$(worktree_status "$repo_root")
-    printf "%s\t%s\t%s\n" "$repo_root" "$branch" "$status"
-
-    if [ -d "$base_dir" ]; then
-      # Find all worktree directories and output: path<tab>branch<tab>status
-      # Exclude the base directory itself to avoid matching when prefix is empty
-      find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | while IFS= read -r dir; do
-        # Skip the base directory itself
-        [ "$dir" = "$base_dir" ] && continue
-        local branch status
-        branch=$(current_branch "$dir")
-        [ -z "$branch" ] && branch="(detached)"
-        status=$(worktree_status "$dir")
-        printf "%s\t%s\t%s\n" "$dir" "$branch" "$status"
-      done | LC_ALL=C sort -k2,2
-    fi
-    return 0
-  fi
-
-  # Human-readable output - table format
-  echo "Git Worktrees"
-  echo ""
-  printf "%-30s %s\n" "BRANCH" "PATH"
-  printf "%-30s %s\n" "------" "----"
-
-  # Always show repo root first
-  local branch
-  branch=$(current_branch "$repo_root")
-  printf "%-30s %s\n" "$branch [main repo]" "$repo_root"
-
-  # Show worktrees sorted by branch name
-  if [ -d "$base_dir" ]; then
-    find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | while IFS= read -r dir; do
-      # Skip the base directory itself
-      [ "$dir" = "$base_dir" ] && continue
-      local branch
-      branch=$(current_branch "$dir")
-      [ -z "$branch" ] && branch="(detached)"
-      printf "%-30s %s\n" "$branch" "$dir"
-    done | LC_ALL=C sort -k1,1
-  fi
-
-  echo ""
-  echo ""
-  echo "Tip: Use 'git gtr list --porcelain' for machine-readable output"
-}
-
-# Clean command (remove prunable worktrees)
-# Remove worktrees whose PRs/MRs are merged (handles squash merges)
-# Usage: _clean_merged repo_root base_dir prefix yes_mode dry_run
-_clean_merged() {
-  local repo_root="$1" base_dir="$2" prefix="$3" yes_mode="$4" dry_run="$5"
-
-  log_step "Checking for worktrees with merged PRs/MRs..."
-
-  # Detect hosting provider (GitHub, GitLab, etc.)
-  local provider
-  provider=$(detect_provider) || true
-  if [ -z "$provider" ]; then
-    local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null || true)
-    if [ -z "$remote_url" ]; then
-      log_error "No remote URL configured for 'origin'"
-    else
-      # Sanitize URL to avoid leaking embedded credentials (e.g., https://token@host/...)
-      local safe_url="${remote_url%%@*}"
-      if [ "$safe_url" != "$remote_url" ]; then
-        safe_url="<redacted>@${remote_url#*@}"
-      fi
-      log_error "Could not detect hosting provider from remote URL: $safe_url"
-      log_info "Set manually: git gtr config set gtr.provider github  (or gitlab)"
-    fi
-    exit 1
-  fi
-
-  # Ensure provider CLI is available and authenticated
-  ensure_provider_cli "$provider" || exit 1
-
-  # Fetch latest from origin
-  log_step "Fetching from origin..."
-  git fetch origin --prune 2>/dev/null || log_warn "Could not fetch from origin"
-
-  local removed=0
-  local skipped=0
-
-  # Get main repo branch to exclude it
-  local main_branch
-  main_branch=$(current_branch "$repo_root")
-
-  # Iterate through worktree directories
-  for dir in "$base_dir/${prefix}"*; do
-    [ -d "$dir" ] || continue
-
-    local branch
-    branch=$(current_branch "$dir")
-
-    if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
-      log_warn "Skipping $dir (detached HEAD)"
-      skipped=$((skipped + 1))
-      continue
-    fi
-
-    # Skip if same as main repo branch
-    if [ "$branch" = "$main_branch" ]; then
-      continue
-    fi
-
-    # Check if worktree has uncommitted changes
-    if ! git -C "$dir" diff --quiet 2>/dev/null || \
-       ! git -C "$dir" diff --cached --quiet 2>/dev/null; then
-      log_warn "Skipping $branch (has uncommitted changes)"
-      skipped=$((skipped + 1))
-      continue
-    fi
-
-    # Check for untracked files
-    if [ -n "$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null)" ]; then
-      log_warn "Skipping $branch (has untracked files)"
-      skipped=$((skipped + 1))
-      continue
-    fi
-
-    # Check if branch has a merged PR/MR
-    if check_branch_merged "$provider" "$branch"; then
-      if [ "$dry_run" -eq 1 ]; then
-        log_info "[dry-run] Would remove: $branch ($dir)"
-        removed=$((removed + 1))
-      elif [ "$yes_mode" -eq 1 ] || prompt_yes_no "Remove worktree and delete branch '$branch'?"; then
-        log_step "Removing worktree: $branch"
-        local remove_output
-        if remove_output=$(git worktree remove "$dir" 2>&1); then
-          # Also delete the local branch
-          git branch -d "$branch" 2>/dev/null || git branch -D "$branch" 2>/dev/null || true
-          log_info "Removed: $branch"
-          removed=$((removed + 1))
-        else
-          if [ -n "$remove_output" ]; then
-            log_error "Failed to remove worktree: $remove_output"
-          else
-            log_error "Failed to remove worktree: $branch"
-          fi
-        fi
-      else
-        log_warn "Skipped: $branch (user declined)"
-        skipped=$((skipped + 1))
-      fi
-    fi
-    # Branches without merged PRs are silently skipped (this is the normal case)
-  done
-
-  echo ""
-  if [ "$dry_run" -eq 1 ]; then
-    log_info "Dry run complete. Would remove: $removed, Skipped: $skipped"
-  else
-    log_info "Merged cleanup complete. Removed: $removed, Skipped: $skipped"
-  fi
-}
-
-cmd_clean() {
-  local merged_mode=0
-  local yes_mode=0
-  local dry_run=0
-
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --merged)
-        merged_mode=1
-        shift
-        ;;
-      --yes|-y)
-        yes_mode=1
-        shift
-        ;;
-      --dry-run|-n)
-        dry_run=1
-        shift
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        shift
-        ;;
-    esac
-  done
-
-  log_step "Cleaning up stale worktrees..."
-
-  # Run git worktree prune
-  if git worktree prune 2>/dev/null; then
-    log_info "Pruned stale worktree administrative files"
-  fi
-
-  resolve_repo_context || exit 1
-  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
-
-  if [ ! -d "$base_dir" ]; then
-    log_info "No worktrees directory to clean"
-    return 0
-  fi
-
-  # Find and remove empty directories
-  local cleaned=0
-  local empty_dirs
-  empty_dirs=$(find "$base_dir" -maxdepth 1 -type d -empty 2>/dev/null | grep -v "^${base_dir}$" || true)
-
-  if [ -n "$empty_dirs" ]; then
-    while IFS= read -r dir; do
-      if [ -n "$dir" ]; then
-        if rmdir "$dir" 2>/dev/null; then
-          cleaned=$((cleaned + 1))
-          log_info "Removed empty directory: $(basename "$dir")"
-        fi
-      fi
-    done <<EOF
-$empty_dirs
-EOF
-  fi
-
-  if [ "$cleaned" -gt 0 ]; then
-    log_info "Cleanup complete ($cleaned director$([ "$cleaned" -eq 1 ] && echo 'y' || echo 'ies') removed)"
-  else
-    log_info "Cleanup complete (no empty directories found)"
-  fi
-
-  # --merged mode: remove worktrees with merged PRs/MRs (handles squash merges)
-  if [ "$merged_mode" -eq 1 ]; then
-    _clean_merged "$repo_root" "$base_dir" "$prefix" "$yes_mode" "$dry_run"
-  fi
-}
-
-# Doctor command (health check)
-cmd_doctor() {
-  echo "Running git gtr health check..."
-  echo ""
-
-  local issues=0
-
-  # Check git
-  if command -v git >/dev/null 2>&1; then
-    local git_version
-    git_version=$(git --version)
-    echo "[OK] Git: $git_version"
-  else
-    echo "[x] Git: not found"
-    issues=$((issues + 1))
-  fi
-
-  # Check repo
-  local repo_root
-  if repo_root=$(discover_repo_root 2>/dev/null); then
-    echo "[OK] Repository: $repo_root"
-
-    # Check worktree base dir
-    local base_dir prefix
-    base_dir=$(resolve_base_dir "$repo_root")
-    prefix=$(cfg_default gtr.worktrees.prefix GTR_WORKTREES_PREFIX "")
-
-    if [ -d "$base_dir" ]; then
-      local count
-      count=$(find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | wc -l | tr -d ' ')
-      echo "[OK] Worktrees directory: $base_dir ($count worktrees)"
-    else
-      echo "[i] Worktrees directory: $base_dir (not created yet)"
-    fi
-  else
-    echo "[x] Not in a git repository"
-    issues=$((issues + 1))
-  fi
-
-  # Check configured editor (with .gtrconfig support)
-  local editor
-  editor=$(cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor)
-  if [ "$editor" != "none" ]; then
-    # Check if adapter exists
-    local editor_adapter="$GTR_DIR/adapters/editor/${editor}.sh"
-    if [ -f "$editor_adapter" ]; then
-      # shellcheck disable=SC1090
-      . "$editor_adapter"
-      if editor_can_open 2>/dev/null; then
-        echo "[OK] Editor: $editor (found)"
-      else
-        echo "[!] Editor: $editor (configured but not found in PATH)"
-      fi
-    else
-      echo "[!] Editor: $editor (adapter not found)"
-    fi
-  else
-    echo "[i] Editor: none configured"
-  fi
-
-  # Check configured AI tool (with .gtrconfig support)
-  local ai_tool
-  ai_tool=$(cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai)
-  if [ "$ai_tool" != "none" ]; then
-    # Check if adapter exists
-    local adapter_file="$GTR_DIR/adapters/ai/${ai_tool}.sh"
-    if [ -f "$adapter_file" ]; then
-      # shellcheck disable=SC1090
-      . "$adapter_file"
-      if ai_can_start 2>/dev/null; then
-        echo "[OK] AI tool: $ai_tool (found)"
-      else
-        echo "[!] AI tool: $ai_tool (configured but not found in PATH)"
-      fi
-    else
-      echo "[!] AI tool: $ai_tool (adapter not found)"
-    fi
-  else
-    echo "[i] AI tool: none configured"
-  fi
-
-  # Check OS
-  local os
-  os=$(detect_os)
-  echo "[OK] Platform: $os"
-
-  # Check hosting provider
-  if [ -n "$repo_root" ]; then
-    local provider
-    provider=$(detect_provider 2>/dev/null)
-    if [ -n "$provider" ]; then
-      echo "[OK] Provider: $provider"
-      case "$provider" in
-        github)
-          if command -v gh >/dev/null 2>&1; then
-            echo "[OK] GitHub CLI: $(gh --version 2>/dev/null | head -1)"
-          else
-            echo "[!] GitHub CLI: not found (needed for: clean --merged)"
-          fi
-          ;;
-        gitlab)
-          if command -v glab >/dev/null 2>&1; then
-            echo "[OK] GitLab CLI: $(glab --version 2>/dev/null | head -1)"
-          else
-            echo "[!] GitLab CLI: not found (needed for: clean --merged)"
-          fi
-          ;;
-      esac
-    else
-      echo "[i] Provider: unknown (set gtr.provider for clean --merged)"
-    fi
-  fi
-
-  echo ""
-  if [ "$issues" -eq 0 ]; then
-    echo "Everything looks good!"
-    return 0
-  else
-    echo "[!] Found $issues issue(s)"
-    return 1
-  fi
-}
-
-# Adapter command (list available adapters)
-cmd_adapter() {
-  echo "Available Adapters"
-  echo ""
-
-  # Editor adapters
-  echo "Editor Adapters:"
-  echo ""
-  printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
-  printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
-
-  for adapter_file in "$GTR_DIR"/adapters/editor/*.sh; do
-    if [ -f "$adapter_file" ]; then
-      local adapter_name
-      adapter_name=$(basename "$adapter_file" .sh)
-      # shellcheck disable=SC1090
-      . "$adapter_file"
-
-      if editor_can_open 2>/dev/null; then
-        printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
-      else
-        printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
-      fi
-    fi
-  done
-
-  echo ""
-  echo ""
-  echo "AI Tool Adapters:"
-  echo ""
-  printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
-  printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
-
-  for adapter_file in "$GTR_DIR"/adapters/ai/*.sh; do
-    if [ -f "$adapter_file" ]; then
-      local adapter_name
-      adapter_name=$(basename "$adapter_file" .sh)
-      # shellcheck disable=SC1090
-      . "$adapter_file"
-
-      if ai_can_start 2>/dev/null; then
-        printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
-      else
-        printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
-      fi
-    fi
-  done
-
-  echo ""
-  echo ""
-  echo "Tip: Set defaults with:"
-  echo "   git gtr config set gtr.editor.default <name>"
-  echo "   git gtr config set gtr.ai.default <name>"
-}
-
-# Config command
-cmd_config() {
-  local scope="auto"
-  local action="" key="" value=""
-  local extra_args=""
-
-  # Parse args flexibly: action, key, value, and --global/--local anywhere
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --global|global)
-        scope="global"
-        shift
-        ;;
-      --local|local)
-        scope="local"
-        shift
-        ;;
-      --system|system)
-        scope="system"
-        shift
-        ;;
-      get|set|unset|add|list)
-        action="$1"
-        shift
-        ;;
-      *)
-        if [ -z "$key" ]; then
-          key="$1"
-          shift
-        elif [ -z "$value" ] && { [ "$action" = "set" ] || [ "$action" = "add" ]; }; then
-          value="$1"
-          shift
-        else
-          # Track extra tokens for validation (add space only if not first)
-          extra_args="${extra_args:+$extra_args }$1"
-          shift
-        fi
-        ;;
-    esac
-  done
-
-  # Default action: list if no action and no key, otherwise get
-  if [ -z "$action" ]; then
-    if [ -z "$key" ]; then
-      action="list"
-    else
-      action="get"
-    fi
-  fi
-
-  # Resolve "auto" scope to "local" for set/add/unset operations (they need explicit scope)
-  # This ensures log messages show the actual scope being used
-  local resolved_scope="$scope"
-  if [ "$scope" = "auto" ] && [ "$action" != "list" ] && [ "$action" != "get" ]; then
-    resolved_scope="local"
-  fi
-
-  # Reject --system for write operations (requires root, not commonly useful)
-  if [ "$scope" = "system" ]; then
-    case "$action" in
-      set|add|unset)
-        log_error "--system is not supported for write operations (requires root privileges)"
-        log_error "Use --local or --global instead"
-        exit 1
-        ;;
-    esac
-  fi
-
-  case "$action" in
-    get)
-      if [ -z "$key" ]; then
-        log_error "Usage: git gtr config get <key> [--local|--global|--system]"
-        exit 1
-      fi
-      # Warn on unexpected extra arguments
-      if [ -n "$extra_args" ]; then
-        log_warn "get action: ignoring extra arguments: $extra_args"
-      fi
-      cfg_get_all "$key" "" "$scope"
-      ;;
-    set)
-      if [ -z "$key" ] || [ -z "$value" ]; then
-        log_error "Usage: git gtr config set <key> <value> [--local|--global]"
-        exit 1
-      fi
-      # Warn on unexpected extra arguments
-      if [ -n "$extra_args" ]; then
-        log_warn "set action: ignoring extra arguments: $extra_args"
-      fi
-      if ! _cfg_is_known_key "$key"; then
-        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
-      fi
-      cfg_set "$key" "$value" "$resolved_scope"
-      log_info "Config set: $key = $value ($resolved_scope)"
-      ;;
-    add)
-      if [ -z "$key" ] || [ -z "$value" ]; then
-        log_error "Usage: git gtr config add <key> <value> [--local|--global]"
-        exit 1
-      fi
-      # Warn on unexpected extra arguments
-      if [ -n "$extra_args" ]; then
-        log_warn "add action: ignoring extra arguments: $extra_args"
-      fi
-      if ! _cfg_is_known_key "$key"; then
-        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
-      fi
-      cfg_add "$key" "$value" "$resolved_scope"
-      log_info "Config added: $key = $value ($resolved_scope)"
-      ;;
-    unset)
-      if [ -z "$key" ]; then
-        log_error "Usage: git gtr config unset <key> [--local|--global]"
-        exit 1
-      fi
-      # Warn on unexpected extra arguments (including value which unset doesn't use)
-      if [ -n "$value" ] || [ -n "$extra_args" ]; then
-        log_warn "unset action: ignoring extra arguments: ${value}${value:+ }${extra_args}"
-      fi
-      if ! _cfg_is_known_key "$key"; then
-        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
-      fi
-      cfg_unset "$key" "$resolved_scope"
-      log_info "Config unset: $key ($resolved_scope)"
-      ;;
-    list)
-      # Warn on unexpected extra arguments
-      if [ -n "$key" ] || [ -n "$extra_args" ]; then
-        log_warn "list action doesn't accept additional arguments (ignoring: ${key}${key:+ }${extra_args})"
-      fi
-      # Use cfg_list for proper formatting and .gtrconfig support
-      cfg_list "$scope"
-      ;;
-    *)
-      log_error "Unknown config action: $action"
-      log_error "Usage: git gtr config [list] [--local|--global|--system]"
-      log_error "       git gtr config {get|set|add|unset} <key> [value] [--local|--global]"
-      exit 1
-      ;;
-  esac
-}
-
-# Completion command (generate shell completions)
-cmd_completion() {
-  local shell="${1:-}"
-
-  case "$shell" in
-    bash)
-      cat "$GTR_DIR/completions/gtr.bash"
-      ;;
-    zsh)
-      # Output zstyle registration + completion loading
-      # The zstyle MUST run before compinit to register gtr as a git subcommand
-      cat <<EOF
-# git-gtr zsh completion
-# Generated by: git gtr completion zsh
-# Add to ~/.zshrc (before compinit):
-#   eval "\$(git gtr completion zsh)"
-
-# Register gtr as a git subcommand (MUST be before compinit)
-zstyle ':completion:*:*:git:*' user-commands gtr:'Git worktree management'
-
-# Add completions to fpath and initialize
-fpath=($GTR_DIR/completions \$fpath)
-
-# Note: If you already have compinit in your .zshrc, you may want to
-# source this file before your existing compinit call and remove the
-# autoload line below.
-autoload -Uz compinit && compinit -C
-EOF
-      ;;
-    fish)
-      cat "$GTR_DIR/completions/git-gtr.fish"
-      ;;
-    ""|--help|-h)
-      echo "Generate shell completions for git gtr"
-      echo ""
-      echo "Usage: git gtr completion <shell>"
-      echo ""
-      echo "Shells:"
-      echo "  bash    Generate Bash completions"
-      echo "  zsh     Generate Zsh completions"
-      echo "  fish    Generate Fish completions"
-      echo ""
-      echo "Examples:"
-      echo "  # Bash: add to ~/.bashrc"
-      echo "  source <(git gtr completion bash)"
-      echo ""
-      echo "  # Zsh: add to ~/.zshrc (BEFORE any existing compinit call)"
-      echo "  eval \"\$(git gtr completion zsh)\""
-      echo ""
-      echo "  # Fish: save to completions directory"
-      echo "  git gtr completion fish > ~/.config/fish/completions/git-gtr.fish"
-      return 0
-      ;;
-    *)
-      log_error "Unknown shell: $shell"
-      log_error "Supported shells: bash, zsh, fish"
-      log_info "Run 'git gtr completion --help' for usage"
-      return 1
-      ;;
-  esac
-}
-
-# Init command (generate shell integration for cd support)
-cmd_init() {
-  local shell="${1:-}"
-
-  case "$shell" in
-    bash)
-      cat <<'BASH'
-# git-gtr shell integration
-# Add to ~/.bashrc:
-#   eval "$(git gtr init bash)"
-
-gtr() {
-  if [ "$#" -gt 0 ] && [ "$1" = "cd" ]; then
-    shift
-    local dir
-    dir="$(command git gtr go "$@")" && cd "$dir" && {
-      local _gtr_hooks _gtr_hook _gtr_seen _gtr_config_file
-      _gtr_hooks=""
-      _gtr_seen=""
-      # Read from git config (local > global > system)
-      _gtr_hooks="$(git config --get-all gtr.hook.postCd 2>/dev/null)" || true
-      # Read from .gtrconfig if it exists
-      _gtr_config_file="$(git rev-parse --show-toplevel 2>/dev/null)/.gtrconfig"
-      if [ -f "$_gtr_config_file" ]; then
-        local _gtr_file_hooks
-        _gtr_file_hooks="$(git config -f "$_gtr_config_file" --get-all hooks.postCd 2>/dev/null)" || true
-        if [ -n "$_gtr_file_hooks" ]; then
-          if [ -n "$_gtr_hooks" ]; then
-            _gtr_hooks="$_gtr_hooks"$'\n'"$_gtr_file_hooks"
-          else
-            _gtr_hooks="$_gtr_file_hooks"
-          fi
-        fi
-      fi
-      if [ -n "$_gtr_hooks" ]; then
-        # Deduplicate while preserving order
-        _gtr_seen=""
-        export WORKTREE_PATH="$dir"
-        export REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
-        export BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
-        while IFS= read -r _gtr_hook; do
-          [ -z "$_gtr_hook" ] && continue
-          case "$_gtr_seen" in *"|$_gtr_hook|"*) continue ;; esac
-          _gtr_seen="$_gtr_seen|$_gtr_hook|"
-          eval "$_gtr_hook" || echo "gtr: postCd hook failed: $_gtr_hook" >&2
-        done <<< "$_gtr_hooks"
-        unset WORKTREE_PATH REPO_ROOT BRANCH
-      fi
-    }
-  else
-    command git gtr "$@"
-  fi
-}
-
-# Forward completions to gtr wrapper
-if type _git_gtr &>/dev/null; then
-  complete -F _git_gtr gtr
-fi
-BASH
-      ;;
-    zsh)
-      cat <<'ZSH'
-# git-gtr shell integration
-# Add to ~/.zshrc:
-#   eval "$(git gtr init zsh)"
-
-gtr() {
-  if [ "$#" -gt 0 ] && [ "$1" = "cd" ]; then
-    shift
-    local dir
-    dir="$(command git gtr go "$@")" && cd "$dir" && {
-      local _gtr_hooks _gtr_hook _gtr_seen _gtr_config_file
-      _gtr_hooks=""
-      _gtr_seen=""
-      # Read from git config (local > global > system)
-      _gtr_hooks="$(git config --get-all gtr.hook.postCd 2>/dev/null)" || true
-      # Read from .gtrconfig if it exists
-      _gtr_config_file="$(git rev-parse --show-toplevel 2>/dev/null)/.gtrconfig"
-      if [ -f "$_gtr_config_file" ]; then
-        local _gtr_file_hooks
-        _gtr_file_hooks="$(git config -f "$_gtr_config_file" --get-all hooks.postCd 2>/dev/null)" || true
-        if [ -n "$_gtr_file_hooks" ]; then
-          if [ -n "$_gtr_hooks" ]; then
-            _gtr_hooks="$_gtr_hooks"$'\n'"$_gtr_file_hooks"
-          else
-            _gtr_hooks="$_gtr_file_hooks"
-          fi
-        fi
-      fi
-      if [ -n "$_gtr_hooks" ]; then
-        # Deduplicate while preserving order
-        _gtr_seen=""
-        export WORKTREE_PATH="$dir"
-        export REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
-        export BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
-        while IFS= read -r _gtr_hook; do
-          [ -z "$_gtr_hook" ] && continue
-          case "$_gtr_seen" in *"|$_gtr_hook|"*) continue ;; esac
-          _gtr_seen="$_gtr_seen|$_gtr_hook|"
-          eval "$_gtr_hook" || echo "gtr: postCd hook failed: $_gtr_hook" >&2
-        done <<< "$_gtr_hooks"
-        unset WORKTREE_PATH REPO_ROOT BRANCH
-      fi
-    }
-  else
-    command git gtr "$@"
-  fi
-}
-
-# Forward completions to gtr wrapper
-if (( $+functions[_git-gtr] )); then
-  compdef gtr=git-gtr
-fi
-ZSH
-      ;;
-    fish)
-      cat <<'FISH'
-# git-gtr shell integration
-# Add to ~/.config/fish/config.fish:
-#   git gtr init fish | source
-
-function gtr
-  if test (count $argv) -gt 0; and test "$argv[1]" = "cd"
-    set -l dir (command git gtr go $argv[2..])
-    and cd $dir
-    and begin
-      set -l _gtr_hooks
-      set -l _gtr_seen
-      # Read from git config (local > global > system)
-      set -l _gtr_git_hooks (git config --get-all gtr.hook.postCd 2>/dev/null)
-      # Read from .gtrconfig if it exists
-      set -l _gtr_config_file (git rev-parse --show-toplevel 2>/dev/null)"/.gtrconfig"
-      set -l _gtr_file_hooks
-      if test -f "$_gtr_config_file"
-        set _gtr_file_hooks (git config -f "$_gtr_config_file" --get-all hooks.postCd 2>/dev/null)
-      end
-      # Merge and deduplicate
-      set _gtr_hooks $_gtr_git_hooks $_gtr_file_hooks
-      if test (count $_gtr_hooks) -gt 0
-        set -lx WORKTREE_PATH "$dir"
-        set -lx REPO_ROOT (git rev-parse --show-toplevel 2>/dev/null)
-        set -lx BRANCH (git rev-parse --abbrev-ref HEAD 2>/dev/null)
-        for _gtr_hook in $_gtr_hooks
-          if test -n "$_gtr_hook"
-            if not contains -- "$_gtr_hook" $_gtr_seen
-              set -a _gtr_seen "$_gtr_hook"
-              eval "$_gtr_hook"; or echo "gtr: postCd hook failed: $_gtr_hook" >&2
-            end
-          end
-        end
-      end
-    end
-  else
-    command git gtr $argv
-  end
-end
-
-# Forward completions to gtr wrapper
-complete -c gtr -w git-gtr
-FISH
-      ;;
-    ""|--help|-h)
-      echo "Generate shell integration for git gtr"
-      echo ""
-      echo "Usage: git gtr init <shell>"
-      echo ""
-      echo "This outputs a gtr() shell function that enables:"
-      echo "  gtr cd <branch>    Change directory to worktree"
-      echo "  gtr <command>      Passes through to git gtr"
-      echo ""
-      echo "Shells:"
-      echo "  bash    Generate Bash integration"
-      echo "  zsh     Generate Zsh integration"
-      echo "  fish    Generate Fish integration"
-      echo ""
-      echo "Examples:"
-      echo "  # Bash: add to ~/.bashrc"
-      echo "  eval \"\$(git gtr init bash)\""
-      echo ""
-      echo "  # Zsh: add to ~/.zshrc"
-      echo "  eval \"\$(git gtr init zsh)\""
-      echo ""
-      echo "  # Fish: add to ~/.config/fish/config.fish"
-      echo "  git gtr init fish | source"
-      return 0
-      ;;
-    *)
-      log_error "Unknown shell: $shell"
-      log_error "Supported shells: bash, zsh, fish"
-      log_info "Run 'git gtr init --help' for usage"
-      return 1
-      ;;
-  esac
-}
-
-# Resolve workspace file for VS Code/Cursor editors
-# Returns the workspace file path if found, empty otherwise
-resolve_workspace_file() {
-  local worktree_path="$1"
-
-  # Check config first (gtr.editor.workspace or editor.workspace in .gtrconfig)
-  local configured
-  configured=$(cfg_default gtr.editor.workspace "" "" editor.workspace)
-
-  # Opt-out: "none" disables workspace lookup entirely
-  if [ "$configured" = "none" ]; then
-    return 0
-  fi
-
-  if [ -n "$configured" ]; then
-    local full_path="$worktree_path/$configured"
-    if [ -f "$full_path" ]; then
-      echo "$full_path"
-    fi
-    # Explicit config set - don't fall through to auto-detect
-    return 0
-  fi
-
-  # Auto-detect: find first .code-workspace in worktree root
-  local ws_file
-  ws_file=$(find "$worktree_path" -maxdepth 1 -name "*.code-workspace" -type f 2>/dev/null | head -1)
-  if [ -n "$ws_file" ]; then
-    echo "$ws_file"
-  fi
-}
-
-# Load editor adapter
-# Load an adapter by type (shared implementation for editor and AI adapters)
-# Usage: _load_adapter <type> <name> <label> <builtin_list> <path_hint>
-_load_adapter() {
-  local type="$1" name="$2" label="$3" builtin_list="$4" path_hint="$5"
-  local adapter_file="$GTR_DIR/adapters/${type}/${name}.sh"
-
-  # Try loading explicit adapter first (allows special handling)
-  if [ -f "$adapter_file" ]; then
-    # shellcheck disable=SC1090
-    . "$adapter_file"
-    return 0
-  fi
-
-  # Generic fallback: check if command exists in PATH
-  # Extract first word (command name) from potentially multi-word string
-  local cmd_name="${name%% *}"
-
-  if ! command -v "$cmd_name" >/dev/null 2>&1; then
-    log_error "$label '$name' not found"
-    log_info "Built-in adapters: $builtin_list"
-    log_info "Or use any $label command available in your PATH (e.g., $path_hint)"
-    return 1
-  fi
-
-  # Set globals for generic adapter functions
-  # Note: $name may contain arguments (e.g., "code --wait", "bunx @github/copilot@latest")
-  if [ "$type" = "editor" ]; then
-    GTR_EDITOR_CMD="$name"
-    GTR_EDITOR_CMD_NAME="$cmd_name"
-  else
-    GTR_AI_CMD="$name"
-    GTR_AI_CMD_NAME="$cmd_name"
-  fi
-}
-
-load_editor_adapter() {
-  _load_adapter "editor" "$1" "Editor" \
-    "cursor, vscode, zed, idea, pycharm, webstorm, vim, nvim, emacs, sublime, nano, atom" \
-    "code-insiders, fleet"
-}
-
-load_ai_adapter() {
-  _load_adapter "ai" "$1" "AI tool" \
-    "aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode" \
-    "bunx, gpt"
-}
-
-# Help command
-cmd_help() {
-  cat <<'EOF'
-git gtr - Git worktree runner
-
-PHILOSOPHY: Configuration over flags. Set defaults once, then use simple commands.
-
-────────────────────────────────────────────────────────────────────────────────
-
-QUICK START:
-  cd ~/your-repo                                   # Navigate to git repo first
-  git gtr config set gtr.editor.default cursor     # One-time setup
-  git gtr config set gtr.ai.default claude         # One-time setup
-  git gtr new my-feature                           # Creates worktree in folder "my-feature"
-  git gtr editor my-feature                        # Opens in cursor
-  git gtr ai my-feature                            # Starts claude
-  git gtr rm my-feature                            # Remove when done
-
-────────────────────────────────────────────────────────────────────────────────
-
-KEY CONCEPTS:
-  • Worktree folders are named after the branch name
-  • Main repo is accessible via special ID '1' (e.g., git gtr go 1, git gtr editor 1)
-  • Commands accept branch names to identify worktrees
-    Example: git gtr editor my-feature, git gtr go feature/user-auth
-
-────────────────────────────────────────────────────────────────────────────────
-
-CORE COMMANDS (daily workflow):
-
-  new <branch> [options]
-         Create a new worktree (folder named after branch)
-         --from <ref>: create from specific ref
-         --from-current: create from current branch (for parallel variants)
-         --track <mode>: tracking mode (auto|remote|local|none)
-         --no-copy: skip file copying
-         --no-fetch: skip git fetch
-         --no-hooks: skip post-create hooks
-         --force: allow same branch in multiple worktrees (requires --name or --folder)
-         --name <suffix>: custom folder name suffix (e.g., backend, frontend)
-         --folder <name>: custom folder name (replaces default, useful for long branches)
-         --yes: non-interactive mode
-         -e, --editor: open in editor after creation
-         -a, --ai: start AI tool after creation
-
-  editor <branch> [--editor <name>]
-         Open worktree in editor (uses gtr.editor.default or --editor)
-         Special: use '1' to open repo root
-
-  ai <branch> [--ai <name>] [-- args...]
-         Start AI coding tool in worktree (uses gtr.ai.default or --ai)
-         Special: use '1' to open repo root
-
-  go <branch>
-         Print worktree path (tip: use 'gtr cd <branch>' with shell integration)
-         Special: use '1' for repo root
-
-  run <branch> <command...>
-         Execute command in worktree directory
-         Special: use '1' to run in repo root
-
-         Examples:
-           git gtr run feature npm test
-           git gtr run feature-auth git status
-           git gtr run 1 npm run build
-
-  list [--porcelain]
-         List all worktrees
-         Aliases: ls
-
-  rm <branch> [<branch>...] [options]
-         Remove worktree(s) by branch name
-         --delete-branch: also delete the branch
-         --force: force removal (dirty worktree)
-         --yes: skip confirmation
-
-  mv <old> <new> [--force] [--yes]
-         Rename worktree and its branch
-         Aliases: rename
-         --force: force move (locked worktree)
-         --yes: skip confirmation
-         Note: Only renames local branch. Remote branch unchanged.
-
-         Examples:
-           git gtr mv feature-wip feature-auth
-           git gtr rename old-name new-name
-
-  copy <target>... [options] [-- <pattern>...]
-         Copy files from main repo to worktree(s)
-         -n, --dry-run: preview without copying
-         -a, --all: copy to all worktrees
-         --from <source>: copy from different worktree (default: main repo)
-         Patterns after -- override gtr.copy.include config
-
-         Examples:
-           git gtr copy my-feature                       # Uses configured patterns
-           git gtr copy my-feature -- ".env*"            # Explicit pattern
-           git gtr copy my-feature -- ".env*" "*.json"   # Multiple patterns
-           git gtr copy -a -- ".env*"                    # Update all worktrees
-           git gtr copy my-feature -n -- "**/.env*"      # Dry-run preview
-
-────────────────────────────────────────────────────────────────────────────────
-
-SETUP & MAINTENANCE:
-
-  config [list] [--local|--global|--system]
-  config get <key> [--local|--global|--system]
-  config {set|add|unset} <key> [value] [--local|--global]
-         Manage configuration
-         - list: show all gtr.* config values (default when no args)
-         - get: read a config value (merged from all sources by default)
-         - set: set a single value (replaces existing)
-         - add: add a value (for multi-valued configs like hooks, copy patterns)
-         - unset: remove a config value
-         Without scope flag, list/get show merged config from all sources
-         Use --local/--global to target a specific scope for write operations
-
-  doctor
-         Health check (verify git, editors, AI tools)
-
-  adapter
-         List available editor & AI tool adapters
-         Note: Any command in your PATH can be used (e.g., code-insiders, bunx)
-
-  clean [options]
-         Remove stale/prunable worktrees and empty directories
-         --merged: also remove worktrees with merged PRs/MRs
-                   Auto-detects GitHub (gh) or GitLab (glab) from remote URL
-                   Override: git gtr config set gtr.provider gitlab
-         --yes, -y: skip confirmation prompts
-         --dry-run, -n: show what would be removed without removing
-
-  completion <shell>
-         Generate shell completions (bash, zsh, fish)
-         Usage: eval "$(git gtr completion zsh)"
-
-  init <shell>
-         Generate shell integration for cd support (bash, zsh, fish)
-         Usage: eval "$(git gtr init bash)"
-
-  version
-         Show version
-
-────────────────────────────────────────────────────────────────────────────────
-
-WORKFLOW EXAMPLES:
-
-  # One-time repo setup
-  cd ~/GitHub/my-project
-  git gtr config set gtr.editor.default cursor
-  git gtr config set gtr.ai.default claude
-
-  # Daily workflow
-  git gtr new feature/user-auth               # Create worktree (folder: feature-user-auth)
-  git gtr editor feature/user-auth            # Open in editor
-  git gtr ai feature/user-auth                # Start AI tool
-
-  # Run commands in worktree
-  git gtr run feature/user-auth npm test      # Run tests
-  git gtr run feature/user-auth npm run dev   # Start dev server
-
-  # Navigate to worktree directory
-  gtr cd feature/user-auth                  # With shell integration (git gtr init)
-  cd "$(git gtr go feature/user-auth)"      # Without shell integration
-
-  # Override defaults with flags
-  git gtr editor feature/user-auth --editor vscode
-  git gtr ai feature/user-auth --ai aider
-
-  # Chain commands together
-  git gtr new hotfix && git gtr editor hotfix && git gtr ai hotfix
-
-  # Create variant worktrees from current branch (for parallel work)
-  git checkout feature/user-auth
-  git gtr new variant-1 --from-current        # Creates variant-1 from feature/user-auth
-  git gtr new variant-2 --from-current        # Creates variant-2 from feature/user-auth
-
-  # When finished
-  git gtr rm feature/user-auth --delete-branch
-
-  # Check setup and available tools
-  git gtr doctor
-  git gtr adapter
-
-────────────────────────────────────────────────────────────────────────────────
-
-CONFIGURATION OPTIONS:
-
-  gtr.worktrees.dir        Worktrees base directory
-  gtr.worktrees.prefix     Worktree folder prefix (default: "")
-  gtr.defaultBranch        Default branch (default: auto)
-  gtr.editor.default       Default editor
-                           Options: cursor, vscode, zed, idea, pycharm,
-                           webstorm, vim, nvim, emacs, sublime, nano,
-                           atom, none
-  gtr.editor.workspace     Workspace file for VS Code/Cursor
-                           (relative path, auto-detects, or "none")
-  gtr.ai.default           Default AI tool
-                           Options: aider, auggie, claude, codex, continue,
-                           copilot, cursor, gemini, opencode, none
-  gtr.copy.include         Files to copy (multi-valued)
-  gtr.copy.exclude         Files to exclude (multi-valued)
-  gtr.copy.includeDirs     Directories to copy (multi-valued)
-                           Example: node_modules, .venv, vendor
-                           WARNING: May include sensitive files!
-                           Use gtr.copy.excludeDirs to exclude them.
-  gtr.copy.excludeDirs     Directories to exclude (multi-valued)
-                           Supports glob patterns (e.g., "node_modules/.cache", "*/.npm")
-  gtr.hook.postCreate      Post-create hooks (multi-valued)
-  gtr.hook.preRemove       Pre-remove hooks (multi-valued, abort on failure)
-  gtr.hook.postRemove      Post-remove hooks (multi-valued)
-  gtr.hook.postCd          Post-cd hooks (multi-valued, shell integration only)
-
-────────────────────────────────────────────────────────────────────────────────
-
-MORE INFO: https://github.com/coderabbitai/git-worktree-runner
-EOF
-}
-
 # Run main
-main "$@"
+main "$@"
\ No newline at end of file
diff --git a/lib/adapters.sh b/lib/adapters.sh
new file mode 100644
index 0000000..2e59882
--- /dev/null
+++ b/lib/adapters.sh
@@ -0,0 +1,324 @@
+#!/usr/bin/env bash
+# Adapter loading infrastructure — registries, builders, generic fallbacks, and loaders
+# shellcheck disable=SC2329 # Functions defined inside adapter builders are invoked indirectly
+
+# Adapter registries — declarative definitions for standard adapters
+# Custom adapters (nano, claude, cursor-ai) remain as override files in adapters/
+# Format — editor: name|cmd|type|err_msg|flags (comma-separated: workspace, background)
+# Format — ai:     name|cmd|err_msg|info_lines (semicolon-separated)
+_EDITOR_REGISTRY="
+atom|atom|standard|Atom not found. Install from https://atom.io|
+cursor|cursor|standard|Cursor not found. Install from https://cursor.com or enable the shell command.|workspace
+emacs|emacs|terminal|Emacs not found. Install from https://www.gnu.org/software/emacs/|background
+idea|idea|standard|IntelliJ IDEA 'idea' command not found. Enable shell launcher in Tools > Create Command-line Launcher|
+nvim|nvim|terminal|Neovim not found. Install from https://neovim.io|
+pycharm|pycharm|standard|PyCharm 'pycharm' command not found. Enable shell launcher in Tools > Create Command-line Launcher|
+sublime|subl|standard|Sublime Text 'subl' command not found. Install from https://www.sublimetext.com|
+vim|vim|terminal|Vim not found. Install via your package manager.|
+vscode|code|standard|VS Code 'code' command not found. Install from https://code.visualstudio.com|workspace
+webstorm|webstorm|standard|WebStorm 'webstorm' command not found. Enable shell launcher in Tools > Create Command-line Launcher|
+zed|zed|standard|Zed not found. Install from https://zed.dev|
+"
+
+_AI_REGISTRY="
+aider|aider|Aider not found. Install with: pip install aider-chat|See https://aider.chat for more information
+auggie|auggie|Auggie CLI not found. Install with: npm install -g @augmentcode/auggie|See https://www.augmentcode.com/product/CLI for more information
+codex|codex|Codex CLI not found. Install with: npm install -g @openai/codex|Or: brew install codex;See https://github.com/openai/codex for more info
+continue|cn|Continue CLI not found. Install from https://continue.dev|See https://docs.continue.dev/cli/install for installation
+copilot|copilot|GitHub Copilot CLI not found.|Install with: npm install -g @github/copilot;Or: brew install copilot-cli;See https://github.com/github/copilot-cli for more information
+gemini|gemini|Gemini CLI not found. Install with: npm install -g @google/gemini-cli|Or: brew install gemini-cli;See https://github.com/google-gemini/gemini-cli for more info
+opencode|opencode|OpenCode not found. Install from https://opencode.ai|Make sure the 'opencode' CLI is available in your PATH
+"
+
+# Registry lookup — find an adapter entry by name
+# Usage: _registry_lookup <registry_content> <name>
+# Prints matching line on success, returns 1 on miss
+_registry_lookup() {
+  local registry="$1" name="$2"
+  local line
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    if [ "${line%%|*}" = "$name" ]; then
+      printf "%s" "$line"
+      return 0
+    fi
+  done <<EOF
+$registry
+EOF
+  return 1
+}
+
+# Load an editor adapter from a registry entry
+# Parses fields and calls the appropriate builder
+_load_from_editor_registry() {
+  local entry="$1"
+  # Parse: name|cmd|type|err_msg|flags
+  local remainder="$entry"
+  local name="${remainder%%|*}"; remainder="${remainder#*|}"
+  local cmd="${remainder%%|*}"; remainder="${remainder#*|}"
+  local type="${remainder%%|*}"; remainder="${remainder#*|}"
+  local err_msg="${remainder%%|*}"; remainder="${remainder#*|}"
+  local flags="$remainder"
+
+  _EDITOR_CMD="$cmd"
+  _EDITOR_ERR_MSG="$err_msg"
+  _EDITOR_WORKSPACE=0
+  _EDITOR_BACKGROUND=0
+
+  case ",$flags," in
+    *,workspace,*) _EDITOR_WORKSPACE=1 ;;
+  esac
+  case ",$flags," in
+    *,background,*) _EDITOR_BACKGROUND=1 ;;
+  esac
+
+  case "$type" in
+    terminal) _editor_define_terminal ;;
+    *)        _editor_define_standard ;;
+  esac
+}
+
+# Load an AI adapter from a registry entry
+# Parses fields and calls the standard builder
+_load_from_ai_registry() {
+  local entry="$1"
+  # Parse: name|cmd|err_msg|info_lines
+  local remainder="$entry"
+  local name="${remainder%%|*}"; remainder="${remainder#*|}"
+  local cmd="${remainder%%|*}"; remainder="${remainder#*|}"
+  local err_msg="${remainder%%|*}"; remainder="${remainder#*|}"
+  local info_lines_raw="$remainder"
+
+  _AI_CMD="$cmd"
+  _AI_ERR_MSG="$err_msg"
+  _AI_INFO_LINES=()
+
+  if [ -n "$info_lines_raw" ]; then
+    local old_ifs="$IFS"
+    IFS=';'
+    # shellcheck disable=SC2086
+    set -- $info_lines_raw
+    _AI_INFO_LINES=("$@")
+    IFS="$old_ifs"
+  fi
+
+  _ai_define_standard
+}
+
+# List all adapter names from a registry
+# Usage: _list_registry_names <registry_content>
+_list_registry_names() {
+  local registry="$1"
+  local names="" line
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    names="${names:+$names, }${line%%|*}"
+  done <<EOF
+$registry
+EOF
+  printf "%s" "$names"
+}
+
+# Generic adapter functions (used when no explicit adapter file exists)
+# These will be overridden if an adapter file is sourced
+# Globals set by load_editor_adapter: GTR_EDITOR_CMD, GTR_EDITOR_CMD_NAME
+editor_can_open() {
+  command -v "$GTR_EDITOR_CMD_NAME" >/dev/null 2>&1
+}
+
+editor_open() {
+  local path="$1"
+  local workspace="${2:-}"
+  local target="$path"
+
+  # Use workspace file if provided and exists
+  if [ -n "$workspace" ] && [ -f "$workspace" ]; then
+    target="$workspace"
+  fi
+
+  # $GTR_EDITOR_CMD may contain arguments (e.g., "code --wait")
+  # Using eval here is necessary to handle multi-word commands properly
+  eval "$GTR_EDITOR_CMD \"\$target\""
+}
+
+# Globals set by load_ai_adapter: GTR_AI_CMD, GTR_AI_CMD_NAME
+ai_can_start() {
+  command -v "$GTR_AI_CMD_NAME" >/dev/null 2>&1
+}
+
+ai_start() {
+  local path="$1"
+  shift
+  # $GTR_AI_CMD may contain arguments (e.g., "bunx @github/copilot@latest")
+  # Using eval here is necessary to handle multi-word commands properly
+  (cd "$path" && eval "$GTR_AI_CMD \"\$@\"")
+}
+
+# Standard AI adapter builder — used by adapter files that follow the common pattern
+# Sets globals then call this: _AI_CMD, _AI_ERR_MSG, _AI_INFO_LINES (array)
+_ai_define_standard() {
+  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
+  ai_can_start() {
+    command -v "$_AI_CMD" >/dev/null 2>&1
+  }
+
+  # shellcheck disable=SC2317
+  ai_start() {
+    local path="$1"; shift
+    if ! ai_can_start; then
+      log_error "$_AI_ERR_MSG"
+      local _line
+      for _line in "${_AI_INFO_LINES[@]}"; do
+        log_info "$_line"
+      done
+      return 1
+    fi
+    if [ ! -d "$path" ]; then
+      log_error "Directory not found: $path"
+      return 1
+    fi
+    (cd "$path" && "$_AI_CMD" "$@")
+  }
+}
+
+# Standard editor adapter builder — used by adapter files that follow the common pattern
+# Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_WORKSPACE (optional, 0 or 1)
+_editor_define_standard() {
+  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
+  editor_can_open() {
+    command -v "$_EDITOR_CMD" >/dev/null 2>&1
+  }
+
+  # shellcheck disable=SC2317
+  editor_open() {
+    local path="$1"
+    local workspace="${2:-}"
+    if ! editor_can_open; then
+      log_error "$_EDITOR_ERR_MSG"
+      return 1
+    fi
+    if [ "${_EDITOR_WORKSPACE:-0}" = "1" ] && [ -n "$workspace" ] && [ -f "$workspace" ]; then
+      "$_EDITOR_CMD" "$workspace"
+    else
+      "$_EDITOR_CMD" "$path"
+    fi
+  }
+}
+
+# Terminal editor adapter builder — for editors that run in the current terminal
+# Sets globals then call this: _EDITOR_CMD, _EDITOR_ERR_MSG, _EDITOR_BACKGROUND (optional, 0 or 1)
+_editor_define_terminal() {
+  # shellcheck disable=SC2317 # Functions are called indirectly via adapter dispatch
+  editor_can_open() {
+    command -v "$_EDITOR_CMD" >/dev/null 2>&1
+  }
+
+  # shellcheck disable=SC2317
+  editor_open() {
+    local path="$1"
+    if ! editor_can_open; then
+      log_error "$_EDITOR_ERR_MSG"
+      return 1
+    fi
+    if [ "${_EDITOR_BACKGROUND:-0}" = "1" ]; then
+      "$_EDITOR_CMD" "$path" &
+    else
+      (cd "$path" && "$_EDITOR_CMD" .)
+    fi
+  }
+}
+
+# Resolve workspace file for VS Code/Cursor editors
+# Returns the workspace file path if found, empty otherwise
+resolve_workspace_file() {
+  local worktree_path="$1"
+
+  # Check config first (gtr.editor.workspace or editor.workspace in .gtrconfig)
+  local configured
+  configured=$(cfg_default gtr.editor.workspace "" "" editor.workspace)
+
+  # Opt-out: "none" disables workspace lookup entirely
+  if [ "$configured" = "none" ]; then
+    return 0
+  fi
+
+  if [ -n "$configured" ]; then
+    local full_path="$worktree_path/$configured"
+    if [ -f "$full_path" ]; then
+      echo "$full_path"
+    fi
+    # Explicit config set - don't fall through to auto-detect
+    return 0
+  fi
+
+  # Auto-detect: find first .code-workspace in worktree root
+  local ws_file
+  ws_file=$(find "$worktree_path" -maxdepth 1 -name "*.code-workspace" -type f 2>/dev/null | head -1)
+  if [ -n "$ws_file" ]; then
+    echo "$ws_file"
+  fi
+}
+
+# Load an adapter by type (shared implementation for editor and AI adapters)
+# Usage: _load_adapter <type> <name> <label> <builtin_list> <path_hint>
+_load_adapter() {
+  local type="$1" name="$2" label="$3" builtin_list="$4" path_hint="$5"
+  local adapter_file="$GTR_DIR/adapters/${type}/${name}.sh"
+
+  # 1. Try loading explicit adapter file (custom overrides like claude, nano)
+  if [ -f "$adapter_file" ]; then
+    # shellcheck disable=SC1090
+    . "$adapter_file"
+    return 0
+  fi
+
+  # 2. Try registry lookup (declarative adapters)
+  local registry entry
+  if [ "$type" = "editor" ]; then
+    registry="$_EDITOR_REGISTRY"
+  else
+    registry="$_AI_REGISTRY"
+  fi
+
+  if entry=$(_registry_lookup "$registry" "$name"); then
+    if [ "$type" = "editor" ]; then
+      _load_from_editor_registry "$entry"
+    else
+      _load_from_ai_registry "$entry"
+    fi
+    return 0
+  fi
+
+  # 3. Generic fallback: check if command exists in PATH
+  # Extract first word (command name) from potentially multi-word string
+  local cmd_name="${name%% *}"
+
+  if ! command -v "$cmd_name" >/dev/null 2>&1; then
+    log_error "$label '$name' not found"
+    log_info "Built-in adapters: $builtin_list"
+    log_info "Or use any $label command available in your PATH (e.g., $path_hint)"
+    return 1
+  fi
+
+  # Set globals for generic adapter functions
+  # Note: $name may contain arguments (e.g., "code --wait", "bunx @github/copilot@latest")
+  if [ "$type" = "editor" ]; then
+    GTR_EDITOR_CMD="$name"
+    GTR_EDITOR_CMD_NAME="$cmd_name"
+  else
+    GTR_AI_CMD="$name"
+    GTR_AI_CMD_NAME="$cmd_name"
+  fi
+}
+
+load_editor_adapter() {
+  local builtin_names
+  builtin_names="$(_list_registry_names "$_EDITOR_REGISTRY"), nano"
+  _load_adapter "editor" "$1" "Editor" "$builtin_names" "code-insiders, fleet"
+}
+
+load_ai_adapter() {
+  local builtin_names
+  builtin_names="$(_list_registry_names "$_AI_REGISTRY"), claude, cursor"
+  _load_adapter "ai" "$1" "AI tool" "$builtin_names" "bunx, gpt"
+}
diff --git a/lib/commands/adapter.sh b/lib/commands/adapter.sh
new file mode 100644
index 0000000..217456e
--- /dev/null
+++ b/lib/commands/adapter.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+# Adapter command (list available adapters)
+cmd_adapter() {
+  echo "Available Adapters"
+  echo ""
+
+  # Editor adapters
+  echo "Editor Adapters:"
+  echo ""
+  printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
+  printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
+
+  # Registry-defined editor adapters
+  local listed_editors=" " line adapter_name
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    adapter_name="${line%%|*}"
+    listed_editors="$listed_editors$adapter_name "
+    _load_from_editor_registry "$line"
+    if editor_can_open 2>/dev/null; then
+      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
+    else
+      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
+    fi
+  done <<EOF
+$_EDITOR_REGISTRY
+EOF
+
+  # File-only editor adapters (custom ones not in registry)
+  local adapter_file
+  for adapter_file in "$GTR_DIR"/adapters/editor/*.sh; do
+    [ -f "$adapter_file" ] || continue
+    adapter_name=$(basename "$adapter_file" .sh)
+    case "$listed_editors" in *" $adapter_name "*) continue ;; esac
+    # shellcheck disable=SC1090
+    . "$adapter_file"
+    if editor_can_open 2>/dev/null; then
+      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
+    else
+      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
+    fi
+  done
+
+  echo ""
+  echo ""
+  echo "AI Tool Adapters:"
+  echo ""
+  printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
+  printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
+
+  # Registry-defined AI adapters
+  local listed_ais=" "
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    adapter_name="${line%%|*}"
+    listed_ais="$listed_ais$adapter_name "
+    _load_from_ai_registry "$line"
+    if ai_can_start 2>/dev/null; then
+      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
+    else
+      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
+    fi
+  done <<EOF
+$_AI_REGISTRY
+EOF
+
+  # File-only AI adapters (custom ones not in registry)
+  for adapter_file in "$GTR_DIR"/adapters/ai/*.sh; do
+    [ -f "$adapter_file" ] || continue
+    adapter_name=$(basename "$adapter_file" .sh)
+    case "$listed_ais" in *" $adapter_name "*) continue ;; esac
+    # shellcheck disable=SC1090
+    . "$adapter_file"
+    if ai_can_start 2>/dev/null; then
+      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
+    else
+      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
+    fi
+  done
+
+  echo ""
+  echo ""
+  echo "Tip: Set defaults with:"
+  echo "   git gtr config set gtr.editor.default <name>"
+  echo "   git gtr config set gtr.ai.default <name>"
+}
\ No newline at end of file
diff --git a/lib/commands/ai.sh b/lib/commands/ai.sh
new file mode 100644
index 0000000..ae3a547
--- /dev/null
+++ b/lib/commands/ai.sh
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+
+# AI command
+cmd_ai() {
+  local identifier=""
+  local ai_tool=""
+  local -a ai_args=()
+
+  # Parse arguments
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --ai)
+        ai_tool="$2"
+        shift 2
+        ;;
+      --)
+        shift
+        ai_args=("$@")
+        break
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        if [ -z "$identifier" ]; then
+          identifier="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  if [ -z "$identifier" ]; then
+    log_error "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
+    exit 1
+  fi
+
+  # Get AI tool from flag or config (with .gtrconfig support)
+  if [ -z "$ai_tool" ]; then
+    ai_tool=$(_cfg_ai_default)
+  fi
+
+  # Check if AI tool is configured
+  if [ "$ai_tool" = "none" ]; then
+    log_error "No AI tool configured"
+    log_info "Set default: git gtr config set gtr.ai.default claude"
+    exit 1
+  fi
+
+  # Load AI adapter
+  load_ai_adapter "$ai_tool" || exit 1
+
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Resolve target branch
+  local worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
+
+  log_step "Starting $ai_tool for: $branch"
+  echo "Directory: $worktree_path"
+  echo "Branch: $branch"
+
+  ai_start "$worktree_path" "${ai_args[@]}"
+}
\ No newline at end of file
diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
new file mode 100644
index 0000000..4891ee9
--- /dev/null
+++ b/lib/commands/clean.sh
@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+
+# Clean command (remove prunable worktrees)
+# Remove worktrees whose PRs/MRs are merged (handles squash merges)
+# Usage: _clean_merged repo_root base_dir prefix yes_mode dry_run
+_clean_merged() {
+  local repo_root="$1" base_dir="$2" prefix="$3" yes_mode="$4" dry_run="$5"
+
+  log_step "Checking for worktrees with merged PRs/MRs..."
+
+  # Detect hosting provider (GitHub, GitLab, etc.)
+  local provider
+  provider=$(detect_provider) || true
+  if [ -z "$provider" ]; then
+    local remote_url
+    remote_url=$(git remote get-url origin 2>/dev/null || true)
+    if [ -z "$remote_url" ]; then
+      log_error "No remote URL configured for 'origin'"
+    else
+      # Sanitize URL to avoid leaking embedded credentials (e.g., https://token@host/...)
+      local safe_url="${remote_url%%@*}"
+      if [ "$safe_url" != "$remote_url" ]; then
+        safe_url="<redacted>@${remote_url#*@}"
+      fi
+      log_error "Could not detect hosting provider from remote URL: $safe_url"
+      log_info "Set manually: git gtr config set gtr.provider github  (or gitlab)"
+    fi
+    exit 1
+  fi
+
+  # Ensure provider CLI is available and authenticated
+  ensure_provider_cli "$provider" || exit 1
+
+  # Fetch latest from origin
+  log_step "Fetching from origin..."
+  git fetch origin --prune 2>/dev/null || log_warn "Could not fetch from origin"
+
+  local removed=0
+  local skipped=0
+
+  # Get main repo branch to exclude it
+  local main_branch
+  main_branch=$(current_branch "$repo_root")
+
+  # Iterate through worktree directories
+  for dir in "$base_dir/${prefix}"*; do
+    [ -d "$dir" ] || continue
+
+    local branch
+    branch=$(current_branch "$dir")
+
+    if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
+      log_warn "Skipping $dir (detached HEAD)"
+      skipped=$((skipped + 1))
+      continue
+    fi
+
+    # Skip if same as main repo branch
+    if [ "$branch" = "$main_branch" ]; then
+      continue
+    fi
+
+    # Check if worktree has uncommitted changes
+    if ! git -C "$dir" diff --quiet 2>/dev/null || \
+       ! git -C "$dir" diff --cached --quiet 2>/dev/null; then
+      log_warn "Skipping $branch (has uncommitted changes)"
+      skipped=$((skipped + 1))
+      continue
+    fi
+
+    # Check for untracked files
+    if [ -n "$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null)" ]; then
+      log_warn "Skipping $branch (has untracked files)"
+      skipped=$((skipped + 1))
+      continue
+    fi
+
+    # Check if branch has a merged PR/MR
+    if check_branch_merged "$provider" "$branch"; then
+      if [ "$dry_run" -eq 1 ]; then
+        log_info "[dry-run] Would remove: $branch ($dir)"
+        removed=$((removed + 1))
+      elif [ "$yes_mode" -eq 1 ] || prompt_yes_no "Remove worktree and delete branch '$branch'?"; then
+        log_step "Removing worktree: $branch"
+        local remove_output
+        if remove_output=$(git worktree remove "$dir" 2>&1); then
+          # Also delete the local branch
+          git branch -d "$branch" 2>/dev/null || git branch -D "$branch" 2>/dev/null || true
+          log_info "Removed: $branch"
+          removed=$((removed + 1))
+        else
+          if [ -n "$remove_output" ]; then
+            log_error "Failed to remove worktree: $remove_output"
+          else
+            log_error "Failed to remove worktree: $branch"
+          fi
+        fi
+      else
+        log_warn "Skipped: $branch (user declined)"
+        skipped=$((skipped + 1))
+      fi
+    fi
+    # Branches without merged PRs are silently skipped (this is the normal case)
+  done
+
+  echo ""
+  if [ "$dry_run" -eq 1 ]; then
+    log_info "Dry run complete. Would remove: $removed, Skipped: $skipped"
+  else
+    log_info "Merged cleanup complete. Removed: $removed, Skipped: $skipped"
+  fi
+}
+
+cmd_clean() {
+  local merged_mode=0
+  local yes_mode=0
+  local dry_run=0
+
+  # Parse flags
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --merged)
+        merged_mode=1
+        shift
+        ;;
+      --yes|-y)
+        yes_mode=1
+        shift
+        ;;
+      --dry-run|-n)
+        dry_run=1
+        shift
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  log_step "Cleaning up stale worktrees..."
+
+  # Run git worktree prune
+  if git worktree prune 2>/dev/null; then
+    log_info "Pruned stale worktree administrative files"
+  fi
+
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  if [ ! -d "$base_dir" ]; then
+    log_info "No worktrees directory to clean"
+    return 0
+  fi
+
+  # Find and remove empty directories
+  local cleaned=0
+  local empty_dirs
+  empty_dirs=$(find "$base_dir" -maxdepth 1 -type d -empty 2>/dev/null | grep -v "^${base_dir}$" || true)
+
+  if [ -n "$empty_dirs" ]; then
+    while IFS= read -r dir; do
+      if [ -n "$dir" ]; then
+        if rmdir "$dir" 2>/dev/null; then
+          cleaned=$((cleaned + 1))
+          log_info "Removed empty directory: $(basename "$dir")"
+        fi
+      fi
+    done <<EOF
+$empty_dirs
+EOF
+  fi
+
+  if [ "$cleaned" -gt 0 ]; then
+    log_info "Cleanup complete ($cleaned director$([ "$cleaned" -eq 1 ] && echo 'y' || echo 'ies') removed)"
+  else
+    log_info "Cleanup complete (no empty directories found)"
+  fi
+
+  # --merged mode: remove worktrees with merged PRs/MRs (handles squash merges)
+  if [ "$merged_mode" -eq 1 ]; then
+    _clean_merged "$repo_root" "$base_dir" "$prefix" "$yes_mode" "$dry_run"
+  fi
+}
\ No newline at end of file
diff --git a/lib/commands/completion.sh b/lib/commands/completion.sh
new file mode 100644
index 0000000..9e95de9
--- /dev/null
+++ b/lib/commands/completion.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+
+# Completion command (generate shell completions)
+cmd_completion() {
+  local shell="${1:-}"
+
+  case "$shell" in
+    bash)
+      cat "$GTR_DIR/completions/gtr.bash"
+      ;;
+    zsh)
+      # Output zstyle registration + completion loading
+      # The zstyle MUST run before compinit to register gtr as a git subcommand
+      cat <<EOF
+# git-gtr zsh completion
+# Generated by: git gtr completion zsh
+# Add to ~/.zshrc (before compinit):
+#   eval "\$(git gtr completion zsh)"
+
+# Register gtr as a git subcommand (MUST be before compinit)
+zstyle ':completion:*:*:git:*' user-commands gtr:'Git worktree management'
+
+# Add completions to fpath and initialize
+fpath=($GTR_DIR/completions \$fpath)
+
+# Note: If you already have compinit in your .zshrc, you may want to
+# source this file before your existing compinit call and remove the
+# autoload line below.
+autoload -Uz compinit && compinit -C
+EOF
+      ;;
+    fish)
+      cat "$GTR_DIR/completions/git-gtr.fish"
+      ;;
+    ""|--help|-h)
+      echo "Generate shell completions for git gtr"
+      echo ""
+      echo "Usage: git gtr completion <shell>"
+      echo ""
+      echo "Shells:"
+      echo "  bash    Generate Bash completions"
+      echo "  zsh     Generate Zsh completions"
+      echo "  fish    Generate Fish completions"
+      echo ""
+      echo "Examples:"
+      echo "  # Bash: add to ~/.bashrc"
+      echo "  source <(git gtr completion bash)"
+      echo ""
+      echo "  # Zsh: add to ~/.zshrc (BEFORE any existing compinit call)"
+      echo "  eval \"\$(git gtr completion zsh)\""
+      echo ""
+      echo "  # Fish: save to completions directory"
+      echo "  git gtr completion fish > ~/.config/fish/completions/git-gtr.fish"
+      return 0
+      ;;
+    *)
+      log_error "Unknown shell: $shell"
+      log_error "Supported shells: bash, zsh, fish"
+      log_info "Run 'git gtr completion --help' for usage"
+      return 1
+      ;;
+  esac
+}
\ No newline at end of file
diff --git a/lib/commands/config.sh b/lib/commands/config.sh
new file mode 100644
index 0000000..2fefb7e
--- /dev/null
+++ b/lib/commands/config.sh
@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+
+# Config command
+cmd_config() {
+  local scope="auto"
+  local action="" key="" value=""
+  local extra_args=""
+
+  # Parse args flexibly: action, key, value, and --global/--local anywhere
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --global|global)
+        scope="global"
+        shift
+        ;;
+      --local|local)
+        scope="local"
+        shift
+        ;;
+      --system|system)
+        scope="system"
+        shift
+        ;;
+      get|set|unset|add|list)
+        action="$1"
+        shift
+        ;;
+      *)
+        if [ -z "$key" ]; then
+          key="$1"
+          shift
+        elif [ -z "$value" ] && { [ "$action" = "set" ] || [ "$action" = "add" ]; }; then
+          value="$1"
+          shift
+        else
+          # Track extra tokens for validation (add space only if not first)
+          extra_args="${extra_args:+$extra_args }$1"
+          shift
+        fi
+        ;;
+    esac
+  done
+
+  # Default action: list if no action and no key, otherwise get
+  if [ -z "$action" ]; then
+    if [ -z "$key" ]; then
+      action="list"
+    else
+      action="get"
+    fi
+  fi
+
+  # Resolve "auto" scope to "local" for set/add/unset operations (they need explicit scope)
+  # This ensures log messages show the actual scope being used
+  local resolved_scope="$scope"
+  if [ "$scope" = "auto" ] && [ "$action" != "list" ] && [ "$action" != "get" ]; then
+    resolved_scope="local"
+  fi
+
+  # Reject --system for write operations (requires root, not commonly useful)
+  if [ "$scope" = "system" ]; then
+    case "$action" in
+      set|add|unset)
+        log_error "--system is not supported for write operations (requires root privileges)"
+        log_error "Use --local or --global instead"
+        exit 1
+        ;;
+    esac
+  fi
+
+  case "$action" in
+    get)
+      if [ -z "$key" ]; then
+        log_error "Usage: git gtr config get <key> [--local|--global|--system]"
+        exit 1
+      fi
+      # Warn on unexpected extra arguments
+      if [ -n "$extra_args" ]; then
+        log_warn "get action: ignoring extra arguments: $extra_args"
+      fi
+      cfg_get_all "$key" "" "$scope"
+      ;;
+    set)
+      if [ -z "$key" ] || [ -z "$value" ]; then
+        log_error "Usage: git gtr config set <key> <value> [--local|--global]"
+        exit 1
+      fi
+      # Warn on unexpected extra arguments
+      if [ -n "$extra_args" ]; then
+        log_warn "set action: ignoring extra arguments: $extra_args"
+      fi
+      if ! _cfg_is_known_key "$key"; then
+        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
+      fi
+      cfg_set "$key" "$value" "$resolved_scope"
+      log_info "Config set: $key = $value ($resolved_scope)"
+      ;;
+    add)
+      if [ -z "$key" ] || [ -z "$value" ]; then
+        log_error "Usage: git gtr config add <key> <value> [--local|--global]"
+        exit 1
+      fi
+      # Warn on unexpected extra arguments
+      if [ -n "$extra_args" ]; then
+        log_warn "add action: ignoring extra arguments: $extra_args"
+      fi
+      if ! _cfg_is_known_key "$key"; then
+        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
+      fi
+      cfg_add "$key" "$value" "$resolved_scope"
+      log_info "Config added: $key = $value ($resolved_scope)"
+      ;;
+    unset)
+      if [ -z "$key" ]; then
+        log_error "Usage: git gtr config unset <key> [--local|--global]"
+        exit 1
+      fi
+      # Warn on unexpected extra arguments (including value which unset doesn't use)
+      if [ -n "$value" ] || [ -n "$extra_args" ]; then
+        log_warn "unset action: ignoring extra arguments: ${value}${value:+ }${extra_args}"
+      fi
+      if ! _cfg_is_known_key "$key"; then
+        log_warn "Unknown config key: $key (not a recognized gtr.* key)"
+      fi
+      cfg_unset "$key" "$resolved_scope"
+      log_info "Config unset: $key ($resolved_scope)"
+      ;;
+    list)
+      # Warn on unexpected extra arguments
+      if [ -n "$key" ] || [ -n "$extra_args" ]; then
+        log_warn "list action doesn't accept additional arguments (ignoring: ${key}${key:+ }${extra_args})"
+      fi
+      # Use cfg_list for proper formatting and .gtrconfig support
+      cfg_list "$scope"
+      ;;
+    *)
+      log_error "Unknown config action: $action"
+      log_error "Usage: git gtr config [list] [--local|--global|--system]"
+      log_error "       git gtr config {get|set|add|unset} <key> [value] [--local|--global]"
+      exit 1
+      ;;
+  esac
+}
\ No newline at end of file
diff --git a/lib/commands/copy.sh b/lib/commands/copy.sh
new file mode 100644
index 0000000..62aef7c
--- /dev/null
+++ b/lib/commands/copy.sh
@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+
+# Copy command (copy files between worktrees)
+cmd_copy() {
+  local source="1"  # Default: main repo
+  local targets=""
+  local patterns=""
+  local all_mode=0
+  local dry_run=0
+
+  # Parse arguments (patterns come after -- separator, like git pathspec)
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --from)
+        source="$2"
+        shift 2
+        ;;
+      -n|--dry-run)
+        dry_run=1
+        shift
+        ;;
+      -a|--all)
+        all_mode=1
+        shift
+        ;;
+      --)
+        shift
+        # Remaining args are patterns (like git pathspec)
+        while [ $# -gt 0 ]; do
+          if [ -n "$patterns" ]; then
+            patterns="$patterns"$'\n'"$1"
+          else
+            patterns="$1"
+          fi
+          shift
+        done
+        break
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        targets="$targets $1"
+        shift
+        ;;
+    esac
+  done
+
+  # Validation
+  if [ "$all_mode" -eq 0 ] && [ -z "$targets" ]; then
+    log_error "Usage: git gtr copy <target>... [-n] [-a] [--from <source>] [-- <pattern>...]"
+    exit 1
+  fi
+
+  # Get repo context
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Resolve source path
+  local src_path
+  resolve_worktree "$source" "$repo_root" "$base_dir" "$prefix" || exit 1
+  src_path="$_ctx_worktree_path"
+
+  # Get patterns (flag > config)
+  if [ -z "$patterns" ]; then
+    patterns=$(cfg_get_all gtr.copy.include copy.include)
+    # Also check .worktreeinclude
+    if [ -f "$repo_root/.worktreeinclude" ]; then
+      local file_patterns
+      file_patterns=$(parse_pattern_file "$repo_root/.worktreeinclude")
+      if [ -n "$file_patterns" ]; then
+        if [ -n "$patterns" ]; then
+          patterns="$patterns"$'\n'"$file_patterns"
+        else
+          patterns="$file_patterns"
+        fi
+      fi
+    fi
+  fi
+
+  if [ -z "$patterns" ]; then
+    log_error "No patterns specified. Use '-- <pattern>...' or configure gtr.copy.include"
+    exit 1
+  fi
+
+  local excludes
+  excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
+
+  # Build target list for --all mode
+  if [ "$all_mode" -eq 1 ]; then
+    targets=$(list_worktree_branches "$base_dir" "$prefix")
+    if [ -z "$targets" ]; then
+      log_error "No worktrees found"
+      exit 1
+    fi
+  fi
+
+  # Process each target
+  local copied_any=0
+  for target_id in $targets; do
+    local dst_path dst_branch
+    resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue
+    dst_path="$_ctx_worktree_path" dst_branch="$_ctx_branch"
+
+    # Skip if source == destination
+    [ "$src_path" = "$dst_path" ] && continue
+
+    if [ "$dry_run" -eq 1 ]; then
+      log_step "[dry-run] Would copy to: $dst_branch"
+      copy_patterns "$src_path" "$dst_path" "$patterns" "$excludes" "true" "true"
+    else
+      log_step "Copying to: $dst_branch"
+      copy_patterns "$src_path" "$dst_path" "$patterns" "$excludes" "true"
+    fi
+    copied_any=1
+  done
+
+  if [ "$copied_any" -eq 0 ]; then
+    log_warn "No files copied (source and target may be the same)"
+  fi
+}
\ No newline at end of file
diff --git a/lib/commands/create.sh b/lib/commands/create.sh
new file mode 100644
index 0000000..8ab94be
--- /dev/null
+++ b/lib/commands/create.sh
@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+
+# Create command
+# Copy files and directories to newly created worktree
+# Usage: _post_create_copy repo_root worktree_path
+_post_create_copy() {
+  local repo_root="$1"
+  local worktree_path="$2"
+
+  local includes excludes file_includes
+  includes=$(cfg_get_all gtr.copy.include copy.include)
+  excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
+
+  # Read .worktreeinclude file if exists
+  file_includes=$(parse_pattern_file "$repo_root/.worktreeinclude")
+
+  # Merge patterns (newline-separated)
+  if [ -n "$file_includes" ]; then
+    if [ -n "$includes" ]; then
+      includes="$includes"$'\n'"$file_includes"
+    else
+      includes="$file_includes"
+    fi
+  fi
+
+  if [ -n "$includes" ]; then
+    log_step "Copying files..."
+    copy_patterns "$repo_root" "$worktree_path" "$includes" "$excludes"
+  fi
+
+  # Copy directories (typically git-ignored dirs like node_modules, .venv)
+  local dir_includes dir_excludes
+  dir_includes=$(cfg_get_all gtr.copy.includeDirs copy.includeDirs)
+  dir_excludes=$(cfg_get_all gtr.copy.excludeDirs copy.excludeDirs)
+
+  if [ -n "$dir_includes" ]; then
+    log_step "Copying directories..."
+    copy_directories "$repo_root" "$worktree_path" "$dir_includes" "$dir_excludes"
+  fi
+}
+
+# Show next steps after worktree creation (resolves collision for --folder overrides)
+# Usage: _post_create_next_steps branch_name folder_name folder_override repo_root base_dir prefix
+_post_create_next_steps() {
+  local branch_name="$1" folder_name="$2" folder_override="$3"
+  local repo_root="$4" base_dir="$5" prefix="$6"
+
+  local next_steps_id
+  if [ -n "$folder_override" ]; then
+    # Check if folder_name would resolve to main repo (collision with current branch)
+    local resolve_result
+    if resolve_result=$(resolve_target "$folder_name" "$repo_root" "$base_dir" "$prefix" 2>/dev/null); then
+      unpack_target "$resolve_result"
+      if [ "$_ctx_is_main" = "1" ]; then
+        # Collision: folder name matches current branch, use branch name instead
+        next_steps_id="$branch_name"
+      else
+        next_steps_id="$folder_name"
+      fi
+    else
+      next_steps_id="$folder_name"
+    fi
+  else
+    next_steps_id="$branch_name"
+  fi
+
+  echo ""
+  echo "Next steps:"
+  echo "  git gtr editor $next_steps_id  # Open in editor"
+  echo "  git gtr ai $next_steps_id      # Start AI tool"
+  echo "  cd \"\$(git gtr go $next_steps_id)\"  # Navigate to worktree"
+}
+
+# Determine the base ref for worktree creation
+# Usage: _create_resolve_from_ref <from_ref> <from_current> <repo_root>
+# Prints: resolved ref
+_create_resolve_from_ref() {
+  local from_ref="$1" from_current="$2" repo_root="$3"
+
+  if [ -z "$from_ref" ]; then
+    if [ "$from_current" -eq 1 ]; then
+      from_ref=$(get_current_branch)
+      if [ -z "$from_ref" ] || [ "$from_ref" = "HEAD" ]; then
+        log_warn "Currently in detached HEAD state - falling back to default branch"
+        from_ref=$(resolve_default_branch "$repo_root")
+      else
+        log_info "Creating from current branch: $from_ref"
+      fi
+    else
+      from_ref=$(resolve_default_branch "$repo_root")
+    fi
+  fi
+
+  printf "%s" "$from_ref"
+}
+
+# Config default helpers — single source of truth for editor/AI config keys
+_cfg_editor_default() {
+  cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor
+}
+
+_cfg_ai_default() {
+  cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai
+}
+
+# Open a worktree in an editor (shared by _auto_launch_editor and cmd_editor)
+# Usage: _open_editor <editor_name> <worktree_path>
+# Returns: 0 on success, 1 on adapter load failure
+_open_editor() {
+  local editor="$1" worktree_path="$2"
+  load_editor_adapter "$editor" || return 1
+  local workspace_file
+  workspace_file=$(resolve_workspace_file "$worktree_path")
+  log_step "Opening in $editor..."
+  editor_open "$worktree_path" "$workspace_file"
+}
+
+# Auto-launch editor for a worktree
+_auto_launch_editor() {
+  local worktree_path="$1"
+  local editor
+  editor=$(_cfg_editor_default)
+  if [ "$editor" != "none" ]; then
+    _open_editor "$editor" "$worktree_path"
+  else
+    open_in_gui "$worktree_path"
+    log_info "Opened in file browser (no editor configured)"
+  fi
+}
+
+# Auto-launch AI tool for a worktree
+_auto_launch_ai() {
+  local worktree_path="$1"
+  local ai_tool
+  ai_tool=$(_cfg_ai_default)
+  if [ "$ai_tool" = "none" ]; then
+    log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
+  else
+    load_ai_adapter "$ai_tool" || return 1
+    log_step "Starting $ai_tool..."
+    ai_start "$worktree_path"
+  fi
+}
+
+cmd_create() {
+  local branch_name=""
+  local from_ref=""
+  local from_current=0
+  local track_mode="auto"
+  local skip_copy=0
+  local skip_fetch=0
+  local skip_hooks=0
+  local yes_mode=0
+  local force=0
+  local custom_name=""
+  local folder_override=""
+  local open_editor=0
+  local start_ai=0
+
+  # Parse flags and arguments
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --from)
+        from_ref="$2"
+        shift 2
+        ;;
+      --from-current)
+        from_current=1
+        shift
+        ;;
+      --track)
+        track_mode="$2"
+        shift 2
+        ;;
+      --no-copy)
+        skip_copy=1
+        shift
+        ;;
+      --no-fetch)
+        skip_fetch=1
+        shift
+        ;;
+      --no-hooks)
+        skip_hooks=1
+        shift
+        ;;
+      --yes)
+        yes_mode=1
+        shift
+        ;;
+      --force)
+        force=1
+        shift
+        ;;
+      --name)
+        custom_name="$2"
+        shift 2
+        ;;
+      --folder)
+        folder_override="$2"
+        shift 2
+        ;;
+      --editor|-e)
+        open_editor=1
+        shift
+        ;;
+      --ai|-a)
+        start_ai=1
+        shift
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        # Positional argument: treat as branch name
+        if [ -z "$branch_name" ]; then
+          branch_name="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  # Validate flag combinations
+  if [ -n "$folder_override" ] && [ -n "$custom_name" ]; then
+    log_error "--folder and --name cannot be used together"
+    exit 1
+  fi
+
+  if [ "$force" -eq 1 ] && [ -z "$custom_name" ] && [ -z "$folder_override" ]; then
+    log_error "--force requires --name or --folder to distinguish worktrees"
+    if [ -n "$branch_name" ]; then
+      echo "Example: git gtr new $branch_name --force --name backend" >&2
+      echo "     or: git gtr new $branch_name --force --folder my-folder" >&2
+    else
+      echo "Example: git gtr new feature-auth --force --name backend" >&2
+      echo "     or: git gtr new feature-auth --force --folder my-folder" >&2
+    fi
+    exit 1
+  fi
+
+  # Get repo info
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Get branch name if not provided
+  if [ -z "$branch_name" ]; then
+    if [ "$yes_mode" -eq 1 ]; then
+      log_error "Branch name required in non-interactive mode"
+      exit 1
+    fi
+    branch_name=$(prompt_input "Enter branch name:")
+    if [ -z "$branch_name" ]; then
+      log_error "Branch name required"
+      exit 1
+    fi
+  fi
+
+  # Determine from_ref with precedence: --from > --from-current > default
+  from_ref=$(_create_resolve_from_ref "$from_ref" "$from_current" "$repo_root")
+
+  # Construct folder name for display
+  local folder_name
+  if [ -n "$folder_override" ]; then
+    folder_name=$(sanitize_branch_name "$folder_override")
+  elif [ -n "$custom_name" ]; then
+    folder_name="$(sanitize_branch_name "$branch_name")-${custom_name}"
+  else
+    folder_name=$(sanitize_branch_name "$branch_name")
+  fi
+
+  log_step "Creating worktree: $folder_name"
+  echo "Location: $base_dir/${prefix}${folder_name}"
+  echo "Branch: $branch_name"
+
+  # Create the worktree
+  if ! worktree_path=$(create_worktree "$base_dir" "$prefix" "$branch_name" "$from_ref" "$track_mode" "$skip_fetch" "$force" "$custom_name" "$folder_override"); then
+    exit 1
+  fi
+
+  # Copy files based on patterns
+  if [ "$skip_copy" -eq 0 ]; then
+    _post_create_copy "$repo_root" "$worktree_path"
+  fi
+
+  # Run post-create hooks (unless --no-hooks)
+  if [ "$skip_hooks" -eq 0 ]; then
+    run_hooks_in postCreate "$worktree_path" \
+      REPO_ROOT="$repo_root" \
+      WORKTREE_PATH="$worktree_path" \
+      BRANCH="$branch_name"
+  fi
+
+  echo ""
+  log_info "Worktree created: $worktree_path"
+
+  # Auto-launch editor/AI or show next steps
+  [ "$open_editor" -eq 1 ] && { _auto_launch_editor "$worktree_path" || true; }
+  [ "$start_ai" -eq 1 ] && { _auto_launch_ai "$worktree_path" || true; }
+  if [ "$open_editor" -eq 0 ] && [ "$start_ai" -eq 0 ]; then
+    _post_create_next_steps "$branch_name" "$folder_name" "$folder_override" "$repo_root" "$base_dir" "$prefix"
+  fi
+}
\ No newline at end of file
diff --git a/lib/commands/doctor.sh b/lib/commands/doctor.sh
new file mode 100644
index 0000000..d627e62
--- /dev/null
+++ b/lib/commands/doctor.sh
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+
+# Doctor command (health check)
+cmd_doctor() {
+  echo "Running git gtr health check..."
+  echo ""
+
+  local issues=0
+
+  # Check git
+  if command -v git >/dev/null 2>&1; then
+    local git_version
+    git_version=$(git --version)
+    echo "[OK] Git: $git_version"
+  else
+    echo "[x] Git: not found"
+    issues=$((issues + 1))
+  fi
+
+  # Check repo
+  local repo_root
+  if repo_root=$(discover_repo_root 2>/dev/null); then
+    echo "[OK] Repository: $repo_root"
+
+    # Check worktree base dir
+    local base_dir prefix
+    base_dir=$(resolve_base_dir "$repo_root")
+    prefix=$(cfg_default gtr.worktrees.prefix GTR_WORKTREES_PREFIX "")
+
+    if [ -d "$base_dir" ]; then
+      local count
+      count=$(find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | wc -l | tr -d ' ')
+      echo "[OK] Worktrees directory: $base_dir ($count worktrees)"
+    else
+      echo "[i] Worktrees directory: $base_dir (not created yet)"
+    fi
+  else
+    echo "[x] Not in a git repository"
+    issues=$((issues + 1))
+  fi
+
+  # Check configured editor (with .gtrconfig support)
+  local editor
+  editor=$(_cfg_editor_default)
+  if [ "$editor" != "none" ]; then
+    if load_editor_adapter "$editor" 2>/dev/null; then
+      if editor_can_open 2>/dev/null; then
+        echo "[OK] Editor: $editor (found)"
+      else
+        echo "[!] Editor: $editor (configured but not found in PATH)"
+      fi
+    else
+      echo "[!] Editor: $editor (adapter not found)"
+    fi
+  else
+    echo "[i] Editor: none configured"
+  fi
+
+  # Check configured AI tool (with .gtrconfig support)
+  local ai_tool
+  ai_tool=$(_cfg_ai_default)
+  if [ "$ai_tool" != "none" ]; then
+    if load_ai_adapter "$ai_tool" 2>/dev/null; then
+      if ai_can_start 2>/dev/null; then
+        echo "[OK] AI tool: $ai_tool (found)"
+      else
+        echo "[!] AI tool: $ai_tool (configured but not found in PATH)"
+      fi
+    else
+      echo "[!] AI tool: $ai_tool (adapter not found)"
+    fi
+  else
+    echo "[i] AI tool: none configured"
+  fi
+
+  # Check OS
+  local os
+  os=$(detect_os)
+  echo "[OK] Platform: $os"
+
+  # Check hosting provider
+  if [ -n "$repo_root" ]; then
+    local provider
+    provider=$(detect_provider 2>/dev/null)
+    if [ -n "$provider" ]; then
+      echo "[OK] Provider: $provider"
+      case "$provider" in
+        github)
+          if command -v gh >/dev/null 2>&1; then
+            echo "[OK] GitHub CLI: $(gh --version 2>/dev/null | head -1)"
+          else
+            echo "[!] GitHub CLI: not found (needed for: clean --merged)"
+          fi
+          ;;
+        gitlab)
+          if command -v glab >/dev/null 2>&1; then
+            echo "[OK] GitLab CLI: $(glab --version 2>/dev/null | head -1)"
+          else
+            echo "[!] GitLab CLI: not found (needed for: clean --merged)"
+          fi
+          ;;
+      esac
+    else
+      echo "[i] Provider: unknown (set gtr.provider for clean --merged)"
+    fi
+  fi
+
+  echo ""
+  if [ "$issues" -eq 0 ]; then
+    echo "Everything looks good!"
+    return 0
+  else
+    echo "[!] Found $issues issue(s)"
+    return 1
+  fi
+}
\ No newline at end of file
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
new file mode 100644
index 0000000..d597297
--- /dev/null
+++ b/lib/commands/editor.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+# Editor command
+cmd_editor() {
+  local identifier=""
+  local editor=""
+
+  # Parse flags
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --editor)
+        editor="$2"
+        shift 2
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        if [ -z "$identifier" ]; then
+          identifier="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  if [ -z "$identifier" ]; then
+    log_error "Usage: git gtr editor <id|branch> [--editor <name>]"
+    exit 1
+  fi
+
+  # Get editor from flag or config (with .gtrconfig support)
+  if [ -z "$editor" ]; then
+    editor=$(_cfg_editor_default)
+  fi
+
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Resolve target branch
+  local worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
+
+  if [ "$editor" = "none" ]; then
+    open_in_gui "$worktree_path"
+    log_info "Opened in file browser"
+  else
+    _open_editor "$editor" "$worktree_path" || exit 1
+  fi
+}
\ No newline at end of file
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
new file mode 100644
index 0000000..47182ae
--- /dev/null
+++ b/lib/commands/go.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+# Go command (navigate to worktree - prints path for shell integration)
+cmd_go() {
+  if [ $# -ne 1 ]; then
+    log_error "Usage: git gtr go <id|branch>"
+    exit 1
+  fi
+
+  local identifier="$1"
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Resolve target branch
+  local is_main worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
+
+  # Human messages to stderr so stdout can be used in command substitution
+  if [ "$is_main" = "1" ]; then
+    echo "Main repo" >&2
+  else
+    echo "Worktree: $branch" >&2
+  fi
+  echo "Branch: $branch" >&2
+
+  # Print path to stdout for shell integration: cd "$(gtr go my-feature)"
+  printf "%s\n" "$worktree_path"
+}
\ No newline at end of file
diff --git a/lib/commands/help.sh b/lib/commands/help.sh
new file mode 100644
index 0000000..c21589b
--- /dev/null
+++ b/lib/commands/help.sh
@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+
+# Help command
+cmd_help() {
+  cat <<'EOF'
+git gtr - Git worktree runner
+
+PHILOSOPHY: Configuration over flags. Set defaults once, then use simple commands.
+
+────────────────────────────────────────────────────────────────────────────────
+
+QUICK START:
+  cd ~/your-repo                                   # Navigate to git repo first
+  git gtr config set gtr.editor.default cursor     # One-time setup
+  git gtr config set gtr.ai.default claude         # One-time setup
+  git gtr new my-feature                           # Creates worktree in folder "my-feature"
+  git gtr editor my-feature                        # Opens in cursor
+  git gtr ai my-feature                            # Starts claude
+  git gtr rm my-feature                            # Remove when done
+
+────────────────────────────────────────────────────────────────────────────────
+
+KEY CONCEPTS:
+  • Worktree folders are named after the branch name
+  • Main repo is accessible via special ID '1' (e.g., git gtr go 1, git gtr editor 1)
+  • Commands accept branch names to identify worktrees
+    Example: git gtr editor my-feature, git gtr go feature/user-auth
+
+────────────────────────────────────────────────────────────────────────────────
+
+CORE COMMANDS (daily workflow):
+
+  new <branch> [options]
+         Create a new worktree (folder named after branch)
+         --from <ref>: create from specific ref
+         --from-current: create from current branch (for parallel variants)
+         --track <mode>: tracking mode (auto|remote|local|none)
+         --no-copy: skip file copying
+         --no-fetch: skip git fetch
+         --no-hooks: skip post-create hooks
+         --force: allow same branch in multiple worktrees (requires --name or --folder)
+         --name <suffix>: custom folder name suffix (e.g., backend, frontend)
+         --folder <name>: custom folder name (replaces default, useful for long branches)
+         --yes: non-interactive mode
+         -e, --editor: open in editor after creation
+         -a, --ai: start AI tool after creation
+
+  editor <branch> [--editor <name>]
+         Open worktree in editor (uses gtr.editor.default or --editor)
+         Special: use '1' to open repo root
+
+  ai <branch> [--ai <name>] [-- args...]
+         Start AI coding tool in worktree (uses gtr.ai.default or --ai)
+         Special: use '1' to open repo root
+
+  go <branch>
+         Print worktree path (tip: use 'gtr cd <branch>' with shell integration)
+         Special: use '1' for repo root
+
+  run <branch> <command...>
+         Execute command in worktree directory
+         Special: use '1' to run in repo root
+
+         Examples:
+           git gtr run feature npm test
+           git gtr run feature-auth git status
+           git gtr run 1 npm run build
+
+  list [--porcelain]
+         List all worktrees
+         Aliases: ls
+
+  rm <branch> [<branch>...] [options]
+         Remove worktree(s) by branch name
+         --delete-branch: also delete the branch
+         --force: force removal (dirty worktree)
+         --yes: skip confirmation
+
+  mv <old> <new> [--force] [--yes]
+         Rename worktree and its branch
+         Aliases: rename
+         --force: force move (locked worktree)
+         --yes: skip confirmation
+         Note: Only renames local branch. Remote branch unchanged.
+
+         Examples:
+           git gtr mv feature-wip feature-auth
+           git gtr rename old-name new-name
+
+  copy <target>... [options] [-- <pattern>...]
+         Copy files from main repo to worktree(s)
+         -n, --dry-run: preview without copying
+         -a, --all: copy to all worktrees
+         --from <source>: copy from different worktree (default: main repo)
+         Patterns after -- override gtr.copy.include config
+
+         Examples:
+           git gtr copy my-feature                       # Uses configured patterns
+           git gtr copy my-feature -- ".env*"            # Explicit pattern
+           git gtr copy my-feature -- ".env*" "*.json"   # Multiple patterns
+           git gtr copy -a -- ".env*"                    # Update all worktrees
+           git gtr copy my-feature -n -- "**/.env*"      # Dry-run preview
+
+────────────────────────────────────────────────────────────────────────────────
+
+SETUP & MAINTENANCE:
+
+  config [list] [--local|--global|--system]
+  config get <key> [--local|--global|--system]
+  config {set|add|unset} <key> [value] [--local|--global]
+         Manage configuration
+         - list: show all gtr.* config values (default when no args)
+         - get: read a config value (merged from all sources by default)
+         - set: set a single value (replaces existing)
+         - add: add a value (for multi-valued configs like hooks, copy patterns)
+         - unset: remove a config value
+         Without scope flag, list/get show merged config from all sources
+         Use --local/--global to target a specific scope for write operations
+
+  doctor
+         Health check (verify git, editors, AI tools)
+
+  adapter
+         List available editor & AI tool adapters
+         Note: Any command in your PATH can be used (e.g., code-insiders, bunx)
+
+  clean [options]
+         Remove stale/prunable worktrees and empty directories
+         --merged: also remove worktrees with merged PRs/MRs
+                   Auto-detects GitHub (gh) or GitLab (glab) from remote URL
+                   Override: git gtr config set gtr.provider gitlab
+         --yes, -y: skip confirmation prompts
+         --dry-run, -n: show what would be removed without removing
+
+  completion <shell>
+         Generate shell completions (bash, zsh, fish)
+         Usage: eval "$(git gtr completion zsh)"
+
+  init <shell>
+         Generate shell integration for cd support (bash, zsh, fish)
+         Usage: eval "$(git gtr init bash)"
+
+  version
+         Show version
+
+────────────────────────────────────────────────────────────────────────────────
+
+WORKFLOW EXAMPLES:
+
+  # One-time repo setup
+  cd ~/GitHub/my-project
+  git gtr config set gtr.editor.default cursor
+  git gtr config set gtr.ai.default claude
+
+  # Daily workflow
+  git gtr new feature/user-auth               # Create worktree (folder: feature-user-auth)
+  git gtr editor feature/user-auth            # Open in editor
+  git gtr ai feature/user-auth                # Start AI tool
+
+  # Run commands in worktree
+  git gtr run feature/user-auth npm test      # Run tests
+  git gtr run feature/user-auth npm run dev   # Start dev server
+
+  # Navigate to worktree directory
+  gtr cd feature/user-auth                  # With shell integration (git gtr init)
+  cd "$(git gtr go feature/user-auth)"      # Without shell integration
+
+  # Override defaults with flags
+  git gtr editor feature/user-auth --editor vscode
+  git gtr ai feature/user-auth --ai aider
+
+  # Chain commands together
+  git gtr new hotfix && git gtr editor hotfix && git gtr ai hotfix
+
+  # Create variant worktrees from current branch (for parallel work)
+  git checkout feature/user-auth
+  git gtr new variant-1 --from-current        # Creates variant-1 from feature/user-auth
+  git gtr new variant-2 --from-current        # Creates variant-2 from feature/user-auth
+
+  # When finished
+  git gtr rm feature/user-auth --delete-branch
+
+  # Check setup and available tools
+  git gtr doctor
+  git gtr adapter
+
+────────────────────────────────────────────────────────────────────────────────
+
+CONFIGURATION OPTIONS:
+
+  gtr.worktrees.dir        Worktrees base directory
+  gtr.worktrees.prefix     Worktree folder prefix (default: "")
+  gtr.defaultBranch        Default branch (default: auto)
+  gtr.editor.default       Default editor
+                           Options: cursor, vscode, zed, idea, pycharm,
+                           webstorm, vim, nvim, emacs, sublime, nano,
+                           atom, none
+  gtr.editor.workspace     Workspace file for VS Code/Cursor
+                           (relative path, auto-detects, or "none")
+  gtr.ai.default           Default AI tool
+                           Options: aider, auggie, claude, codex, continue,
+                           copilot, cursor, gemini, opencode, none
+  gtr.copy.include         Files to copy (multi-valued)
+  gtr.copy.exclude         Files to exclude (multi-valued)
+  gtr.copy.includeDirs     Directories to copy (multi-valued)
+                           Example: node_modules, .venv, vendor
+                           WARNING: May include sensitive files!
+                           Use gtr.copy.excludeDirs to exclude them.
+  gtr.copy.excludeDirs     Directories to exclude (multi-valued)
+                           Supports glob patterns (e.g., "node_modules/.cache", "*/.npm")
+  gtr.hook.postCreate      Post-create hooks (multi-valued)
+  gtr.hook.preRemove       Pre-remove hooks (multi-valued, abort on failure)
+  gtr.hook.postRemove      Post-remove hooks (multi-valued)
+  gtr.hook.postCd          Post-cd hooks (multi-valued, shell integration only)
+
+────────────────────────────────────────────────────────────────────────────────
+
+MORE INFO: https://github.com/coderabbitai/git-worktree-runner
+EOF
+}
\ No newline at end of file
diff --git a/lib/commands/init.sh b/lib/commands/init.sh
new file mode 100644
index 0000000..d7ecea5
--- /dev/null
+++ b/lib/commands/init.sh
@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+
+# Init command (generate shell integration for cd support)
+cmd_init() {
+  local shell="${1:-}"
+
+  case "$shell" in
+    bash)
+      cat <<'BASH'
+# git-gtr shell integration
+# Add to ~/.bashrc:
+#   eval "$(git gtr init bash)"
+
+gtr() {
+  if [ "$#" -gt 0 ] && [ "$1" = "cd" ]; then
+    shift
+    local dir
+    dir="$(command git gtr go "$@")" && cd "$dir" && {
+      local _gtr_hooks _gtr_hook _gtr_seen _gtr_config_file
+      _gtr_hooks=""
+      _gtr_seen=""
+      # Read from git config (local > global > system)
+      _gtr_hooks="$(git config --get-all gtr.hook.postCd 2>/dev/null)" || true
+      # Read from .gtrconfig if it exists
+      _gtr_config_file="$(git rev-parse --show-toplevel 2>/dev/null)/.gtrconfig"
+      if [ -f "$_gtr_config_file" ]; then
+        local _gtr_file_hooks
+        _gtr_file_hooks="$(git config -f "$_gtr_config_file" --get-all hooks.postCd 2>/dev/null)" || true
+        if [ -n "$_gtr_file_hooks" ]; then
+          if [ -n "$_gtr_hooks" ]; then
+            _gtr_hooks="$_gtr_hooks"$'\n'"$_gtr_file_hooks"
+          else
+            _gtr_hooks="$_gtr_file_hooks"
+          fi
+        fi
+      fi
+      if [ -n "$_gtr_hooks" ]; then
+        # Deduplicate while preserving order
+        _gtr_seen=""
+        export WORKTREE_PATH="$dir"
+        export REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+        export BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+        while IFS= read -r _gtr_hook; do
+          [ -z "$_gtr_hook" ] && continue
+          case "$_gtr_seen" in *"|$_gtr_hook|"*) continue ;; esac
+          _gtr_seen="$_gtr_seen|$_gtr_hook|"
+          eval "$_gtr_hook" || echo "gtr: postCd hook failed: $_gtr_hook" >&2
+        done <<< "$_gtr_hooks"
+        unset WORKTREE_PATH REPO_ROOT BRANCH
+      fi
+    }
+  else
+    command git gtr "$@"
+  fi
+}
+
+# Forward completions to gtr wrapper
+if type _git_gtr &>/dev/null; then
+  complete -F _git_gtr gtr
+fi
+BASH
+      ;;
+    zsh)
+      cat <<'ZSH'
+# git-gtr shell integration
+# Add to ~/.zshrc:
+#   eval "$(git gtr init zsh)"
+
+gtr() {
+  if [ "$#" -gt 0 ] && [ "$1" = "cd" ]; then
+    shift
+    local dir
+    dir="$(command git gtr go "$@")" && cd "$dir" && {
+      local _gtr_hooks _gtr_hook _gtr_seen _gtr_config_file
+      _gtr_hooks=""
+      _gtr_seen=""
+      # Read from git config (local > global > system)
+      _gtr_hooks="$(git config --get-all gtr.hook.postCd 2>/dev/null)" || true
+      # Read from .gtrconfig if it exists
+      _gtr_config_file="$(git rev-parse --show-toplevel 2>/dev/null)/.gtrconfig"
+      if [ -f "$_gtr_config_file" ]; then
+        local _gtr_file_hooks
+        _gtr_file_hooks="$(git config -f "$_gtr_config_file" --get-all hooks.postCd 2>/dev/null)" || true
+        if [ -n "$_gtr_file_hooks" ]; then
+          if [ -n "$_gtr_hooks" ]; then
+            _gtr_hooks="$_gtr_hooks"$'\n'"$_gtr_file_hooks"
+          else
+            _gtr_hooks="$_gtr_file_hooks"
+          fi
+        fi
+      fi
+      if [ -n "$_gtr_hooks" ]; then
+        # Deduplicate while preserving order
+        _gtr_seen=""
+        export WORKTREE_PATH="$dir"
+        export REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+        export BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+        while IFS= read -r _gtr_hook; do
+          [ -z "$_gtr_hook" ] && continue
+          case "$_gtr_seen" in *"|$_gtr_hook|"*) continue ;; esac
+          _gtr_seen="$_gtr_seen|$_gtr_hook|"
+          eval "$_gtr_hook" || echo "gtr: postCd hook failed: $_gtr_hook" >&2
+        done <<< "$_gtr_hooks"
+        unset WORKTREE_PATH REPO_ROOT BRANCH
+      fi
+    }
+  else
+    command git gtr "$@"
+  fi
+}
+
+# Forward completions to gtr wrapper
+if (( $+functions[_git-gtr] )); then
+  compdef gtr=git-gtr
+fi
+ZSH
+      ;;
+    fish)
+      cat <<'FISH'
+# git-gtr shell integration
+# Add to ~/.config/fish/config.fish:
+#   git gtr init fish | source
+
+function gtr
+  if test (count $argv) -gt 0; and test "$argv[1]" = "cd"
+    set -l dir (command git gtr go $argv[2..])
+    and cd $dir
+    and begin
+      set -l _gtr_hooks
+      set -l _gtr_seen
+      # Read from git config (local > global > system)
+      set -l _gtr_git_hooks (git config --get-all gtr.hook.postCd 2>/dev/null)
+      # Read from .gtrconfig if it exists
+      set -l _gtr_config_file (git rev-parse --show-toplevel 2>/dev/null)"/.gtrconfig"
+      set -l _gtr_file_hooks
+      if test -f "$_gtr_config_file"
+        set _gtr_file_hooks (git config -f "$_gtr_config_file" --get-all hooks.postCd 2>/dev/null)
+      end
+      # Merge and deduplicate
+      set _gtr_hooks $_gtr_git_hooks $_gtr_file_hooks
+      if test (count $_gtr_hooks) -gt 0
+        set -lx WORKTREE_PATH "$dir"
+        set -lx REPO_ROOT (git rev-parse --show-toplevel 2>/dev/null)
+        set -lx BRANCH (git rev-parse --abbrev-ref HEAD 2>/dev/null)
+        for _gtr_hook in $_gtr_hooks
+          if test -n "$_gtr_hook"
+            if not contains -- "$_gtr_hook" $_gtr_seen
+              set -a _gtr_seen "$_gtr_hook"
+              eval "$_gtr_hook"; or echo "gtr: postCd hook failed: $_gtr_hook" >&2
+            end
+          end
+        end
+      end
+    end
+  else
+    command git gtr $argv
+  end
+end
+
+# Forward completions to gtr wrapper
+complete -c gtr -w git-gtr
+FISH
+      ;;
+    ""|--help|-h)
+      echo "Generate shell integration for git gtr"
+      echo ""
+      echo "Usage: git gtr init <shell>"
+      echo ""
+      echo "This outputs a gtr() shell function that enables:"
+      echo "  gtr cd <branch>    Change directory to worktree"
+      echo "  gtr <command>      Passes through to git gtr"
+      echo ""
+      echo "Shells:"
+      echo "  bash    Generate Bash integration"
+      echo "  zsh     Generate Zsh integration"
+      echo "  fish    Generate Fish integration"
+      echo ""
+      echo "Examples:"
+      echo "  # Bash: add to ~/.bashrc"
+      echo "  eval \"\$(git gtr init bash)\""
+      echo ""
+      echo "  # Zsh: add to ~/.zshrc"
+      echo "  eval \"\$(git gtr init zsh)\""
+      echo ""
+      echo "  # Fish: add to ~/.config/fish/config.fish"
+      echo "  git gtr init fish | source"
+      return 0
+      ;;
+    *)
+      log_error "Unknown shell: $shell"
+      log_error "Supported shells: bash, zsh, fish"
+      log_info "Run 'git gtr init --help' for usage"
+      return 1
+      ;;
+  esac
+}
\ No newline at end of file
diff --git a/lib/commands/list.sh b/lib/commands/list.sh
new file mode 100644
index 0000000..1cd8cca
--- /dev/null
+++ b/lib/commands/list.sh
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+
+# List command
+cmd_list() {
+  local porcelain=0
+
+  # Parse flags
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --porcelain)
+        porcelain=1
+        shift
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  local repo_root base_dir prefix
+  repo_root=$(discover_repo_root) 2>/dev/null || return 0
+  base_dir=$(resolve_base_dir "$repo_root")
+  prefix=$(cfg_default gtr.worktrees.prefix GTR_WORKTREES_PREFIX "")
+
+  # Machine-readable output (porcelain)
+  if [ "$porcelain" -eq 1 ]; then
+    # Output: path<tab>branch<tab>status
+    local branch status
+    branch=$(current_branch "$repo_root")
+    status=$(worktree_status "$repo_root")
+    printf "%s\t%s\t%s\n" "$repo_root" "$branch" "$status"
+
+    if [ -d "$base_dir" ]; then
+      # Find all worktree directories and output: path<tab>branch<tab>status
+      # Exclude the base directory itself to avoid matching when prefix is empty
+      find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | while IFS= read -r dir; do
+        # Skip the base directory itself
+        [ "$dir" = "$base_dir" ] && continue
+        local branch status
+        branch=$(current_branch "$dir")
+        [ -z "$branch" ] && branch="(detached)"
+        status=$(worktree_status "$dir")
+        printf "%s\t%s\t%s\n" "$dir" "$branch" "$status"
+      done | LC_ALL=C sort -k2,2
+    fi
+    return 0
+  fi
+
+  # Human-readable output - table format
+  echo "Git Worktrees"
+  echo ""
+  printf "%-30s %s\n" "BRANCH" "PATH"
+  printf "%-30s %s\n" "------" "----"
+
+  # Always show repo root first
+  local branch
+  branch=$(current_branch "$repo_root")
+  printf "%-30s %s\n" "$branch [main repo]" "$repo_root"
+
+  # Show worktrees sorted by branch name
+  if [ -d "$base_dir" ]; then
+    find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | while IFS= read -r dir; do
+      # Skip the base directory itself
+      [ "$dir" = "$base_dir" ] && continue
+      local branch
+      branch=$(current_branch "$dir")
+      [ -z "$branch" ] && branch="(detached)"
+      printf "%-30s %s\n" "$branch" "$dir"
+    done | LC_ALL=C sort -k1,1
+  fi
+
+  echo ""
+  echo ""
+  echo "Tip: Use 'git gtr list --porcelain' for machine-readable output"
+}
\ No newline at end of file
diff --git a/lib/commands/remove.sh b/lib/commands/remove.sh
new file mode 100644
index 0000000..f1f71ba
--- /dev/null
+++ b/lib/commands/remove.sh
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+
+# Remove command
+cmd_remove() {
+  local delete_branch=0
+  local yes_mode=0
+  local force=0
+  local identifiers=""
+
+  # Parse flags
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --delete-branch)
+        delete_branch=1
+        shift
+        ;;
+      --yes)
+        yes_mode=1
+        shift
+        ;;
+      --force)
+        force=1
+        shift
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        identifiers="$identifiers $1"
+        shift
+        ;;
+    esac
+  done
+
+  if [ -z "$identifiers" ]; then
+    log_error "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
+    exit 1
+  fi
+
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  for identifier in $identifiers; do
+    # Resolve target branch
+    local is_main worktree_path branch_name
+    resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || continue
+    is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch_name="$_ctx_branch"
+
+    # Cannot remove main repository
+    if [ "$is_main" = "1" ]; then
+      log_error "Cannot remove main repository"
+      continue
+    fi
+
+    log_step "Removing worktree: $(basename "$worktree_path")"
+
+    # Run pre-remove hooks (abort on failure unless --force)
+    if ! run_hooks_in preRemove "$worktree_path" \
+      REPO_ROOT="$repo_root" \
+      WORKTREE_PATH="$worktree_path" \
+      BRANCH="$branch_name"; then
+      if [ "$force" -eq 0 ]; then
+        log_error "Pre-remove hook failed for $branch_name. Use --force to skip hooks."
+        continue
+      else
+        log_warn "Pre-remove hook failed, continuing due to --force"
+      fi
+    fi
+
+    # Remove the worktree
+    if ! remove_worktree "$worktree_path" "$force"; then
+      continue
+    fi
+
+    # Handle branch deletion
+    if [ -n "$branch_name" ]; then
+      if [ "$delete_branch" -eq 1 ]; then
+        if [ "$yes_mode" -eq 1 ] || prompt_yes_no "Also delete branch '$branch_name'?"; then
+          if git branch -D "$branch_name" 2>/dev/null; then
+            log_info "Branch deleted: $branch_name"
+          else
+            log_warn "Could not delete branch: $branch_name"
+          fi
+        fi
+      fi
+    fi
+
+    # Run post-remove hooks
+    run_hooks postRemove \
+      REPO_ROOT="$repo_root" \
+      WORKTREE_PATH="$worktree_path" \
+      BRANCH="$branch_name"
+  done
+}
\ No newline at end of file
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
new file mode 100644
index 0000000..3c6f1e0
--- /dev/null
+++ b/lib/commands/rename.sh
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+
+# Rename command (rename worktree and branch)
+cmd_rename() {
+  local old_identifier=""
+  local new_name=""
+  local force=0
+  local yes_mode=0
+
+  # Parse flags and arguments
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --force)
+        force=1
+        shift
+        ;;
+      --yes)
+        yes_mode=1
+        shift
+        ;;
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        if [ -z "$old_identifier" ]; then
+          old_identifier="$1"
+        elif [ -z "$new_name" ]; then
+          new_name="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  # Validate arguments
+  if [ -z "$old_identifier" ] || [ -z "$new_name" ]; then
+    log_error "Usage: git gtr mv <old> <new> [--force] [--yes]"
+    exit 1
+  fi
+
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Resolve old worktree
+  local is_main old_path old_branch
+  resolve_worktree "$old_identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  is_main="$_ctx_is_main" old_path="$_ctx_worktree_path" old_branch="$_ctx_branch"
+
+  # Cannot rename main repository
+  if [ "$is_main" = "1" ]; then
+    log_error "Cannot rename main repository"
+    exit 1
+  fi
+
+  # Sanitize new name and construct new path
+  local new_sanitized new_path
+  new_sanitized=$(sanitize_branch_name "$new_name")
+  new_path="$base_dir/${prefix}${new_sanitized}"
+
+  # Check if new path already exists
+  if [ -d "$new_path" ]; then
+    log_error "Worktree already exists at: $new_path"
+    exit 1
+  fi
+
+  # Check if new branch name already exists
+  if git -C "$repo_root" show-ref --verify --quiet "refs/heads/$new_name"; then
+    log_error "Branch '$new_name' already exists"
+    exit 1
+  fi
+
+  log_step "Renaming worktree"
+  echo "Branch: $old_branch → $new_name"
+  echo "Folder: $(basename "$old_path") → ${prefix}${new_sanitized}"
+
+  # Confirm unless --yes
+  if [ "$yes_mode" -eq 0 ]; then
+    if ! prompt_yes_no "Proceed with rename?"; then
+      log_info "Cancelled"
+      exit 0
+    fi
+  fi
+
+  # Rename the branch first
+  if ! git -C "$repo_root" branch -m "$old_branch" "$new_name"; then
+    log_error "Failed to rename branch"
+    exit 1
+  fi
+
+  # Move the worktree
+  local move_args=()
+  if [ "$force" -eq 1 ]; then
+    move_args+=(--force)
+  fi
+
+  if ! git -C "$repo_root" worktree move "$old_path" "$new_path" "${move_args[@]}"; then
+    # Rollback: rename branch back
+    log_warn "Worktree move failed, rolling back branch rename..."
+    git -C "$repo_root" branch -m "$new_name" "$old_branch" 2>/dev/null || true
+    log_error "Failed to move worktree"
+    exit 1
+  fi
+
+  echo ""
+  log_info "Renamed: $old_branch → $new_name"
+  log_info "Location: $new_path"
+
+  # Check if remote tracking branch exists and warn
+  if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/$old_branch"; then
+    echo ""
+    log_warn "Remote branch 'origin/$old_branch' still exists"
+    log_info "To update remote, run:"
+    echo "  git push origin :$old_branch $new_name"
+  fi
+}
\ No newline at end of file
diff --git a/lib/commands/run.sh b/lib/commands/run.sh
new file mode 100644
index 0000000..86023d0
--- /dev/null
+++ b/lib/commands/run.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Run command (execute command in worktree directory)
+cmd_run() {
+  local identifier=""
+  local -a run_args=()
+
+  # Parse arguments
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -*)
+        log_error "Unknown flag: $1"
+        exit 1
+        ;;
+      *)
+        if [ -z "$identifier" ]; then
+          identifier="$1"
+          shift
+        else
+          run_args=("$@")  # Capture all remaining args as the command
+          break
+        fi
+        ;;
+    esac
+  done
+
+  # Validation
+  if [ -z "$identifier" ]; then
+    log_error "Usage: git gtr run <id|branch> <command...>"
+    exit 1
+  fi
+
+  if [ ${#run_args[@]} -eq 0 ]; then
+    log_error "Usage: git gtr run <id|branch> <command...>"
+    log_error "No command specified"
+    exit 1
+  fi
+
+  resolve_repo_context || exit 1
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
+
+  # Resolve target branch
+  local is_main worktree_path branch
+  resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
+
+  # Human messages to stderr (like cmd_go)
+  if [ "$is_main" = "1" ]; then
+    log_step "Running in: main repo"
+  else
+    log_step "Running in: $branch"
+  fi
+  echo "Command: ${run_args[*]}" >&2
+  echo "" >&2
+
+  # Execute command in worktree directory (exit code propagates)
+  (cd "$worktree_path" && "${run_args[@]}")
+}
\ No newline at end of file
diff --git a/lib/core.sh b/lib/core.sh
index 4663361..54b43ad 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -241,17 +241,14 @@ resolve_target() {
   # Special case: ID 1 is always the repo root
   if [ "$identifier" = "1" ]; then
     path="$repo_root"
-    # Try --show-current (Git 2.22+), fallback to rev-parse for older Git
-    branch=$(git -C "$repo_root" branch --show-current 2>/dev/null)
-    [ -z "$branch" ] && branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null)
+    branch=$(get_current_branch "$repo_root")
     printf "1\t%s\t%s\n" "$path" "$branch"
     return 0
   fi
 
   # For all other identifiers, treat as branch name
   # First check if it's the current branch in repo root (if not ID 1)
-  branch=$(git -C "$repo_root" branch --show-current 2>/dev/null)
-  [ -z "$branch" ] && branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  branch=$(get_current_branch "$repo_root")
   if [ "$branch" = "$identifier" ]; then
     printf "1\t%s\t%s\n" "$repo_root" "$identifier"
     return 0

From 194212b18e3bb9742837f04313deda778173880e Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 17:05:27 -0800
Subject: [PATCH 09/19] refactor: enhance command context handling with
 shellcheck directives

- Added shellcheck disable directives in various command scripts to suppress specific warnings related to variable usage and sourcing.
- Improved clarity and maintainability of command context management by ensuring proper variable handling across multiple command files.
- Streamlined the sourcing of command handlers in `bin/gtr` for better organization and execution flow.
---
 bin/gtr                | 1 +
 lib/adapters.sh        | 1 +
 lib/commands/ai.sh     | 2 ++
 lib/commands/clean.sh  | 1 +
 lib/commands/copy.sh   | 3 +++
 lib/commands/create.sh | 2 ++
 lib/commands/editor.sh | 6 ++++--
 lib/commands/go.sh     | 2 ++
 lib/commands/remove.sh | 2 ++
 lib/commands/rename.sh | 2 ++
 lib/commands/run.sh    | 2 ++
 11 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/bin/gtr b/bin/gtr
index 4eefd26..ce22522 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -32,6 +32,7 @@ resolve_script_dir() {
 
 # Source command handlers
 for _cmd_file in "$GTR_DIR"/lib/commands/*.sh; do
+  # shellcheck disable=SC1090
   . "$_cmd_file"
 done
 unset _cmd_file
diff --git a/lib/adapters.sh b/lib/adapters.sh
index 2e59882..667c5a1 100644
--- a/lib/adapters.sh
+++ b/lib/adapters.sh
@@ -133,6 +133,7 @@ editor_open() {
 
   # Use workspace file if provided and exists
   if [ -n "$workspace" ] && [ -f "$workspace" ]; then
+    # shellcheck disable=SC2034
     target="$workspace"
   fi
 
diff --git a/lib/commands/ai.sh b/lib/commands/ai.sh
index ae3a547..347f1df 100644
--- a/lib/commands/ai.sh
+++ b/lib/commands/ai.sh
@@ -52,11 +52,13 @@ cmd_ai() {
   load_ai_adapter "$ai_tool" || exit 1
 
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
   local worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  # shellcheck disable=SC2154
   worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   log_step "Starting $ai_tool for: $branch"
diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index 4891ee9..a8160c9 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -149,6 +149,7 @@ cmd_clean() {
   fi
 
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   if [ ! -d "$base_dir" ]; then
diff --git a/lib/commands/copy.sh b/lib/commands/copy.sh
index 62aef7c..320f9bd 100644
--- a/lib/commands/copy.sh
+++ b/lib/commands/copy.sh
@@ -55,11 +55,13 @@ cmd_copy() {
 
   # Get repo context
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve source path
   local src_path
   resolve_worktree "$source" "$repo_root" "$base_dir" "$prefix" || exit 1
+  # shellcheck disable=SC2154
   src_path="$_ctx_worktree_path"
 
   # Get patterns (flag > config)
@@ -101,6 +103,7 @@ cmd_copy() {
   for target_id in $targets; do
     local dst_path dst_branch
     resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue
+    # shellcheck disable=SC2154
     dst_path="$_ctx_worktree_path" dst_branch="$_ctx_branch"
 
     # Skip if source == destination
diff --git a/lib/commands/create.sh b/lib/commands/create.sh
index 8ab94be..ea732ae 100644
--- a/lib/commands/create.sh
+++ b/lib/commands/create.sh
@@ -51,6 +51,7 @@ _post_create_next_steps() {
     local resolve_result
     if resolve_result=$(resolve_target "$folder_name" "$repo_root" "$base_dir" "$prefix" 2>/dev/null); then
       unpack_target "$resolve_result"
+      # shellcheck disable=SC2154
       if [ "$_ctx_is_main" = "1" ]; then
         # Collision: folder name matches current branch, use branch name instead
         next_steps_id="$branch_name"
@@ -242,6 +243,7 @@ cmd_create() {
 
   # Get repo info
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Get branch name if not provided
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
index d597297..78661e5 100644
--- a/lib/commands/editor.sh
+++ b/lib/commands/editor.sh
@@ -36,12 +36,14 @@ cmd_editor() {
   fi
 
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
-  local worktree_path branch
+  local worktree_path
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
+  # shellcheck disable=SC2154
+  worktree_path="$_ctx_worktree_path"
 
   if [ "$editor" = "none" ]; then
     open_in_gui "$worktree_path"
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
index 47182ae..ad44a5f 100644
--- a/lib/commands/go.sh
+++ b/lib/commands/go.sh
@@ -9,11 +9,13 @@ cmd_go() {
 
   local identifier="$1"
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
   local is_main worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  # shellcheck disable=SC2154
   is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   # Human messages to stderr so stdout can be used in command substitution
diff --git a/lib/commands/remove.sh b/lib/commands/remove.sh
index f1f71ba..519111c 100644
--- a/lib/commands/remove.sh
+++ b/lib/commands/remove.sh
@@ -39,12 +39,14 @@ cmd_remove() {
   fi
 
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   for identifier in $identifiers; do
     # Resolve target branch
     local is_main worktree_path branch_name
     resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || continue
+    # shellcheck disable=SC2154
     is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch_name="$_ctx_branch"
 
     # Cannot remove main repository
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
index 3c6f1e0..0b69b6e 100644
--- a/lib/commands/rename.sh
+++ b/lib/commands/rename.sh
@@ -40,11 +40,13 @@ cmd_rename() {
   fi
 
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve old worktree
   local is_main old_path old_branch
   resolve_worktree "$old_identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  # shellcheck disable=SC2154
   is_main="$_ctx_is_main" old_path="$_ctx_worktree_path" old_branch="$_ctx_branch"
 
   # Cannot rename main repository
diff --git a/lib/commands/run.sh b/lib/commands/run.sh
index 86023d0..0852a6b 100644
--- a/lib/commands/run.sh
+++ b/lib/commands/run.sh
@@ -37,11 +37,13 @@ cmd_run() {
   fi
 
   resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
   local is_main worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
+  # shellcheck disable=SC2154
   is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   # Human messages to stderr (like cmd_go)

From 289124b742411a9b7afba3feff5d63e53f33521e Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 17:14:11 -0800
Subject: [PATCH 10/19] refactor: enhance testing documentation and command
 help

- Updated CLAUDE.md to reflect the introduction of BATS tests for core functions and clarified the manual testing process.
- Enhanced CONTRIBUTING.md with detailed instructions for running automated tests and manual testing across different platforms.
- Added help command functionality to various command scripts, providing users with guidance on command usage.
- Introduced a new launch.sh script for managing editor and AI tool interactions, improving the overall command structure and user experience.
- Merged copy pattern handling into a single function for better maintainability and clarity in the copy command workflow.
---
 CLAUDE.md                    |  9 +++--
 CONTRIBUTING.md              | 15 ++++++-
 bin/gtr                      |  1 +
 completions/_git-gtr         |  4 +-
 completions/git-gtr.fish     |  1 +
 completions/gtr.bash         |  4 +-
 docs/troubleshooting.md      |  9 +++--
 lib/commands/adapter.sh      | 76 +++++++++++++-----------------------
 lib/commands/ai.sh           |  9 +++--
 lib/commands/clean.sh        |  3 ++
 lib/commands/completion.sh   |  4 ++
 lib/commands/config.sh       |  3 ++
 lib/commands/copy.sh         | 27 +++++--------
 lib/commands/create.sh       | 70 +++------------------------------
 lib/commands/doctor.sh       |  4 ++
 lib/commands/editor.sh       |  3 ++
 lib/commands/go.sh           |  4 ++
 lib/commands/init.sh         |  4 ++
 lib/commands/list.sh         | 10 +++--
 lib/commands/remove.sh       |  3 ++
 lib/commands/rename.sh       |  3 ++
 lib/commands/run.sh          |  3 ++
 lib/copy.sh                  | 23 +++++++++++
 lib/launch.sh                | 52 ++++++++++++++++++++++++
 lib/ui.sh                    |  6 +++
 templates/gtr.config.example |  4 +-
 26 files changed, 204 insertions(+), 150 deletions(-)
 create mode 100644 lib/launch.sh

diff --git a/CLAUDE.md b/CLAUDE.md
index 3cf71c9..ceba77a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,9 +12,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Development/testing**: `./bin/gtr <command>` (direct execution)
 - **User-facing docs**: Always reference `git gtr`, never `./bin/gtr`
 
-## CRITICAL: No Automated Tests
+## Testing
 
-This project has **no test suite**. All testing is manual. After any change, run the relevant smoke tests:
+This project uses **BATS tests** for core functions and **manual smoke tests** for end-to-end workflows. After any change:
+
+1. Run automated tests: `bats tests/`
+2. Run relevant manual smoke tests:
 
 ```bash
 ./bin/gtr new test-feature          # Create worktree
@@ -25,7 +28,7 @@ This project has **no test suite**. All testing is manual. After any change, run
 ./bin/gtr rm test-feature           # Clean up
 ```
 
-For exhaustive testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
+For exhaustive manual testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
 
 **Tip**: Use a disposable repo for testing to avoid polluting your working tree:
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5c0b5ef..33ca58e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -150,7 +150,20 @@ For changes to core functionality (`lib/*.sh`):
 
 ### Testing
 
-Currently, testing is manual. Please test your changes on:
+#### Automated Tests (BATS)
+
+Run the test suite before submitting PRs:
+
+```bash
+bats tests/            # Run all tests
+bats tests/copy_safety.bats  # Run a specific test file
+```
+
+CI runs ShellCheck + BATS automatically on all PRs (`.github/workflows/lint.yml`).
+
+#### Manual Testing
+
+Please also test your changes manually on:
 
 1. **macOS** (if available)
 2. **Linux** (Ubuntu, Fedora, or Arch recommended)
diff --git a/bin/gtr b/bin/gtr
index ce22522..88fb15e 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -29,6 +29,7 @@ resolve_script_dir() {
 . "$GTR_DIR/lib/hooks.sh"
 . "$GTR_DIR/lib/provider.sh"
 . "$GTR_DIR/lib/adapters.sh"
+. "$GTR_DIR/lib/launch.sh"
 
 # Source command handlers
 for _cmd_file in "$GTR_DIR"/lib/commands/*.sh; do
diff --git a/completions/_git-gtr b/completions/_git-gtr
index 935ac5a..aac1d51 100644
--- a/completions/_git-gtr
+++ b/completions/_git-gtr
@@ -172,7 +172,7 @@ _git-gtr() {
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
                 '--system[Use system git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
               ;;
             set|add|unset)
               # Write operations only support --local and --global
@@ -180,7 +180,7 @@ _git-gtr() {
               _arguments \
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
               ;;
           esac
         fi
diff --git a/completions/git-gtr.fish b/completions/git-gtr.fish
index d40a2e2..fd5cc1f 100644
--- a/completions/git-gtr.fish
+++ b/completions/git-gtr.fish
@@ -136,6 +136,7 @@ complete -f -c git -n '__fish_git_gtr_using_command config' -a "
   gtr.worktrees.prefix\t'Worktree folder prefix'
   gtr.defaultBranch\t'Default branch'
   gtr.editor.default\t'Default editor'
+  gtr.editor.workspace\t'Path to workspace file (.code-workspace)'
   gtr.ai.default\t'Default AI tool'
   gtr.provider\t'Hosting provider (github, gitlab)'
   gtr.copy.include\t'Files to copy'
diff --git a/completions/gtr.bash b/completions/gtr.bash
index aeb3dc3..0f41ae8 100644
--- a/completions/gtr.bash
+++ b/completions/gtr.bash
@@ -128,7 +128,7 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global --system" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
             fi
             ;;
           set|add|unset)
@@ -136,7 +136,7 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
             fi
             ;;
         esac
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 83b6394..32d0351 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -165,7 +165,7 @@ git gtr config get gtr.copy.exclude
 git-worktree-runner/
 ├── bin/
 │   ├── git-gtr         # Git subcommand entry point (wrapper)
-│   └── gtr             # Core implementation (1000+ lines)
+│   └── gtr             # Entry point (~105 lines, sources lib/*.sh)
 ├── lib/                 # Core libraries
 │   ├── core.sh         # Git worktree operations
 │   ├── config.sh       # Configuration management
@@ -211,9 +211,10 @@ git-worktree-runner/
 
 ### Testing Approach
 
-- Core functionality tested across macOS, Linux, WSL2
-- Manual testing with Cursor, VS Code, Aider, Claude Code
-- Used in production for parallel agent workflows
+- **Automated tests**: BATS test suite (`tests/`) covers core functions
+- **CI**: ShellCheck linting + BATS tests run on all PRs
+- **Manual testing**: End-to-end workflows tested across macOS, Linux, WSL2
+- **Production use**: Battle-tested with Cursor, VS Code, Aider, Claude Code
 - Community testing appreciated - please report issues!
 
 ### Experimental Features
diff --git a/lib/commands/adapter.sh b/lib/commands/adapter.sh
index 217456e..f2ea3f6 100644
--- a/lib/commands/adapter.sh
+++ b/lib/commands/adapter.sh
@@ -1,87 +1,67 @@
 #!/usr/bin/env bash
 
 # Adapter command (list available adapters)
-cmd_adapter() {
-  echo "Available Adapters"
-  echo ""
 
-  # Editor adapters
-  echo "Editor Adapters:"
+# Print adapter listing for a given type
+# Usage: _print_adapter_list <label> <registry> <subdir> <can_func> <load_func>
+_print_adapter_list() {
+  local label="$1" registry="$2" subdir="$3" can_func="$4" load_func="$5"
+
+  echo "$label:"
   echo ""
   printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
   printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
 
-  # Registry-defined editor adapters
-  local listed_editors=" " line adapter_name
+  # Registry-defined adapters
+  local listed=" " line adapter_name
   while IFS= read -r line; do
     [ -z "$line" ] && continue
     adapter_name="${line%%|*}"
-    listed_editors="$listed_editors$adapter_name "
-    _load_from_editor_registry "$line"
-    if editor_can_open 2>/dev/null; then
+    listed="$listed$adapter_name "
+    "$load_func" "$line"
+    if $can_func 2>/dev/null; then
       printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
     else
       printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
     fi
   done <<EOF
-$_EDITOR_REGISTRY
+$registry
 EOF
 
-  # File-only editor adapters (custom ones not in registry)
+  # File-only adapters (custom ones not in registry)
   local adapter_file
-  for adapter_file in "$GTR_DIR"/adapters/editor/*.sh; do
+  for adapter_file in "$GTR_DIR/adapters/$subdir"/*.sh; do
     [ -f "$adapter_file" ] || continue
     adapter_name=$(basename "$adapter_file" .sh)
-    case "$listed_editors" in *" $adapter_name "*) continue ;; esac
+    case "$listed" in *" $adapter_name "*) continue ;; esac
     # shellcheck disable=SC1090
     . "$adapter_file"
-    if editor_can_open 2>/dev/null; then
+    if $can_func 2>/dev/null; then
       printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
     else
       printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
     fi
   done
+}
 
+cmd_adapter() {
+  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    show_command_help
+  fi
+
+  echo "Available Adapters"
   echo ""
+
+  _print_adapter_list "Editor Adapters" "$_EDITOR_REGISTRY" "editor" "editor_can_open" "_load_from_editor_registry"
+
   echo ""
-  echo "AI Tool Adapters:"
   echo ""
-  printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
-  printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
-
-  # Registry-defined AI adapters
-  local listed_ais=" "
-  while IFS= read -r line; do
-    [ -z "$line" ] && continue
-    adapter_name="${line%%|*}"
-    listed_ais="$listed_ais$adapter_name "
-    _load_from_ai_registry "$line"
-    if ai_can_start 2>/dev/null; then
-      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
-    else
-      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
-    fi
-  done <<EOF
-$_AI_REGISTRY
-EOF
 
-  # File-only AI adapters (custom ones not in registry)
-  for adapter_file in "$GTR_DIR"/adapters/ai/*.sh; do
-    [ -f "$adapter_file" ] || continue
-    adapter_name=$(basename "$adapter_file" .sh)
-    case "$listed_ais" in *" $adapter_name "*) continue ;; esac
-    # shellcheck disable=SC1090
-    . "$adapter_file"
-    if ai_can_start 2>/dev/null; then
-      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
-    else
-      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
-    fi
-  done
+  _print_adapter_list "AI Tool Adapters" "$_AI_REGISTRY" "ai" "ai_can_start" "_load_from_ai_registry"
 
   echo ""
   echo ""
   echo "Tip: Set defaults with:"
   echo "   git gtr config set gtr.editor.default <name>"
   echo "   git gtr config set gtr.ai.default <name>"
-}
\ No newline at end of file
+}
diff --git a/lib/commands/ai.sh b/lib/commands/ai.sh
index 347f1df..b709a76 100644
--- a/lib/commands/ai.sh
+++ b/lib/commands/ai.sh
@@ -18,6 +18,9 @@ cmd_ai() {
         ai_args=("$@")
         break
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
@@ -48,13 +51,13 @@ cmd_ai() {
     exit 1
   fi
 
-  # Load AI adapter
-  load_ai_adapter "$ai_tool" || exit 1
-
   resolve_repo_context || exit 1
   # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
+  # Load AI adapter (after context — fail fast on bad repo first)
+  load_ai_adapter "$ai_tool" || exit 1
+
   # Resolve target branch
   local worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index a8160c9..f1fca22 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -131,6 +131,9 @@ cmd_clean() {
         dry_run=1
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
diff --git a/lib/commands/completion.sh b/lib/commands/completion.sh
index 9e95de9..0ca04c9 100644
--- a/lib/commands/completion.sh
+++ b/lib/commands/completion.sh
@@ -2,6 +2,10 @@
 
 # Completion command (generate shell completions)
 cmd_completion() {
+  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    show_command_help
+  fi
+
   local shell="${1:-}"
 
   case "$shell" in
diff --git a/lib/commands/config.sh b/lib/commands/config.sh
index 2fefb7e..1a459f0 100644
--- a/lib/commands/config.sh
+++ b/lib/commands/config.sh
@@ -21,6 +21,9 @@ cmd_config() {
         scope="system"
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       get|set|unset|add|list)
         action="$1"
         shift
diff --git a/lib/commands/copy.sh b/lib/commands/copy.sh
index 320f9bd..92d3734 100644
--- a/lib/commands/copy.sh
+++ b/lib/commands/copy.sh
@@ -36,6 +36,9 @@ cmd_copy() {
         done
         break
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
@@ -64,21 +67,14 @@ cmd_copy() {
   # shellcheck disable=SC2154
   src_path="$_ctx_worktree_path"
 
-  # Get patterns (flag > config)
+  # Get patterns (flag > config + .worktreeinclude)
+  local excludes
   if [ -z "$patterns" ]; then
-    patterns=$(cfg_get_all gtr.copy.include copy.include)
-    # Also check .worktreeinclude
-    if [ -f "$repo_root/.worktreeinclude" ]; then
-      local file_patterns
-      file_patterns=$(parse_pattern_file "$repo_root/.worktreeinclude")
-      if [ -n "$file_patterns" ]; then
-        if [ -n "$patterns" ]; then
-          patterns="$patterns"$'\n'"$file_patterns"
-        else
-          patterns="$file_patterns"
-        fi
-      fi
-    fi
+    merge_copy_patterns "$repo_root"
+    # shellcheck disable=SC2154
+    patterns="$_ctx_copy_includes" excludes="$_ctx_copy_excludes"
+  else
+    excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
   fi
 
   if [ -z "$patterns" ]; then
@@ -86,9 +82,6 @@ cmd_copy() {
     exit 1
   fi
 
-  local excludes
-  excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
-
   # Build target list for --all mode
   if [ "$all_mode" -eq 1 ]; then
     targets=$(list_worktree_branches "$base_dir" "$prefix")
diff --git a/lib/commands/create.sh b/lib/commands/create.sh
index ea732ae..b40fb44 100644
--- a/lib/commands/create.sh
+++ b/lib/commands/create.sh
@@ -7,21 +7,9 @@ _post_create_copy() {
   local repo_root="$1"
   local worktree_path="$2"
 
-  local includes excludes file_includes
-  includes=$(cfg_get_all gtr.copy.include copy.include)
-  excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
-
-  # Read .worktreeinclude file if exists
-  file_includes=$(parse_pattern_file "$repo_root/.worktreeinclude")
-
-  # Merge patterns (newline-separated)
-  if [ -n "$file_includes" ]; then
-    if [ -n "$includes" ]; then
-      includes="$includes"$'\n'"$file_includes"
-    else
-      includes="$file_includes"
-    fi
-  fi
+  merge_copy_patterns "$repo_root"
+  # shellcheck disable=SC2154
+  local includes="$_ctx_copy_includes" excludes="$_ctx_copy_excludes"
 
   if [ -n "$includes" ]; then
     log_step "Copying files..."
@@ -94,55 +82,6 @@ _create_resolve_from_ref() {
 
   printf "%s" "$from_ref"
 }
-
-# Config default helpers — single source of truth for editor/AI config keys
-_cfg_editor_default() {
-  cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor
-}
-
-_cfg_ai_default() {
-  cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai
-}
-
-# Open a worktree in an editor (shared by _auto_launch_editor and cmd_editor)
-# Usage: _open_editor <editor_name> <worktree_path>
-# Returns: 0 on success, 1 on adapter load failure
-_open_editor() {
-  local editor="$1" worktree_path="$2"
-  load_editor_adapter "$editor" || return 1
-  local workspace_file
-  workspace_file=$(resolve_workspace_file "$worktree_path")
-  log_step "Opening in $editor..."
-  editor_open "$worktree_path" "$workspace_file"
-}
-
-# Auto-launch editor for a worktree
-_auto_launch_editor() {
-  local worktree_path="$1"
-  local editor
-  editor=$(_cfg_editor_default)
-  if [ "$editor" != "none" ]; then
-    _open_editor "$editor" "$worktree_path"
-  else
-    open_in_gui "$worktree_path"
-    log_info "Opened in file browser (no editor configured)"
-  fi
-}
-
-# Auto-launch AI tool for a worktree
-_auto_launch_ai() {
-  local worktree_path="$1"
-  local ai_tool
-  ai_tool=$(_cfg_ai_default)
-  if [ "$ai_tool" = "none" ]; then
-    log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
-  else
-    load_ai_adapter "$ai_tool" || return 1
-    log_step "Starting $ai_tool..."
-    ai_start "$worktree_path"
-  fi
-}
-
 cmd_create() {
   local branch_name=""
   local from_ref=""
@@ -209,6 +148,9 @@ cmd_create() {
         start_ai=1
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
diff --git a/lib/commands/doctor.sh b/lib/commands/doctor.sh
index d627e62..2afa813 100644
--- a/lib/commands/doctor.sh
+++ b/lib/commands/doctor.sh
@@ -2,6 +2,10 @@
 
 # Doctor command (health check)
 cmd_doctor() {
+  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    show_command_help
+  fi
+
   echo "Running git gtr health check..."
   echo ""
 
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
index 78661e5..a0aec88 100644
--- a/lib/commands/editor.sh
+++ b/lib/commands/editor.sh
@@ -12,6 +12,9 @@ cmd_editor() {
         editor="$2"
         shift 2
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
index ad44a5f..cf939e8 100644
--- a/lib/commands/go.sh
+++ b/lib/commands/go.sh
@@ -2,6 +2,10 @@
 
 # Go command (navigate to worktree - prints path for shell integration)
 cmd_go() {
+  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    show_command_help
+  fi
+
   if [ $# -ne 1 ]; then
     log_error "Usage: git gtr go <id|branch>"
     exit 1
diff --git a/lib/commands/init.sh b/lib/commands/init.sh
index d7ecea5..f582aa7 100644
--- a/lib/commands/init.sh
+++ b/lib/commands/init.sh
@@ -2,6 +2,10 @@
 
 # Init command (generate shell integration for cd support)
 cmd_init() {
+  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    show_command_help
+  fi
+
   local shell="${1:-}"
 
   case "$shell" in
diff --git a/lib/commands/list.sh b/lib/commands/list.sh
index 1cd8cca..ec5bbcf 100644
--- a/lib/commands/list.sh
+++ b/lib/commands/list.sh
@@ -11,16 +11,18 @@ cmd_list() {
         porcelain=1
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       *)
         shift
         ;;
     esac
   done
 
-  local repo_root base_dir prefix
-  repo_root=$(discover_repo_root) 2>/dev/null || return 0
-  base_dir=$(resolve_base_dir "$repo_root")
-  prefix=$(cfg_default gtr.worktrees.prefix GTR_WORKTREES_PREFIX "")
+  resolve_repo_context || exit 1
+  # shellcheck disable=SC2154
+  local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Machine-readable output (porcelain)
   if [ "$porcelain" -eq 1 ]; then
diff --git a/lib/commands/remove.sh b/lib/commands/remove.sh
index 519111c..239d5ec 100644
--- a/lib/commands/remove.sh
+++ b/lib/commands/remove.sh
@@ -22,6 +22,9 @@ cmd_remove() {
         force=1
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
index 0b69b6e..98527ee 100644
--- a/lib/commands/rename.sh
+++ b/lib/commands/rename.sh
@@ -18,6 +18,9 @@ cmd_rename() {
         yes_mode=1
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
diff --git a/lib/commands/run.sh b/lib/commands/run.sh
index 0852a6b..838cb49 100644
--- a/lib/commands/run.sh
+++ b/lib/commands/run.sh
@@ -8,6 +8,9 @@ cmd_run() {
   # Parse arguments
   while [ $# -gt 0 ]; do
     case "$1" in
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
diff --git a/lib/copy.sh b/lib/copy.sh
index 9ed56dd..5d3f9c1 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -48,6 +48,29 @@ parse_pattern_file() {
   grep -v '^#' "$file_path" 2>/dev/null | grep -v '^[[:space:]]*$' || true
 }
 
+# Merge copy patterns from config and .worktreeinclude file
+# Usage: merge_copy_patterns repo_root
+# Sets: _ctx_copy_includes, _ctx_copy_excludes (newline-separated patterns)
+merge_copy_patterns() {
+  local repo_root="$1"
+
+  _ctx_copy_includes=$(cfg_get_all gtr.copy.include copy.include)
+  _ctx_copy_excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
+
+  # Read .worktreeinclude file if exists
+  local file_includes
+  file_includes=$(parse_pattern_file "$repo_root/.worktreeinclude")
+
+  # Merge file patterns into includes
+  if [ -n "$file_includes" ]; then
+    if [ -n "$_ctx_copy_includes" ]; then
+      _ctx_copy_includes="$_ctx_copy_includes"$'\n'"$file_includes"
+    else
+      _ctx_copy_includes="$file_includes"
+    fi
+  fi
+}
+
 # Copy a single file to destination, handling exclusion, path preservation, and dry-run
 # Usage: _copy_pattern_file file dst_root excludes preserve_paths dry_run
 # Returns: 0 if file was copied (or would be in dry-run), 1 if skipped/failed
diff --git a/lib/launch.sh b/lib/launch.sh
new file mode 100644
index 0000000..0998482
--- /dev/null
+++ b/lib/launch.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Launch helpers for editors and AI tools
+# Orchestrates config resolution, adapter loading, and tool invocation
+# Used by: cmd_create, cmd_editor, cmd_ai, cmd_doctor
+
+# Config default helpers — single source of truth for editor/AI config keys
+_cfg_editor_default() {
+  cfg_default gtr.editor.default GTR_EDITOR_DEFAULT "none" defaults.editor
+}
+
+_cfg_ai_default() {
+  cfg_default gtr.ai.default GTR_AI_DEFAULT "none" defaults.ai
+}
+
+# Open a worktree in an editor (shared by _auto_launch_editor and cmd_editor)
+# Usage: _open_editor <editor_name> <worktree_path>
+# Returns: 0 on success, 1 on adapter load failure
+_open_editor() {
+  local editor="$1" worktree_path="$2"
+  load_editor_adapter "$editor" || return 1
+  local workspace_file
+  workspace_file=$(resolve_workspace_file "$worktree_path")
+  log_step "Opening in $editor..."
+  editor_open "$worktree_path" "$workspace_file"
+}
+
+# Auto-launch editor for a worktree
+_auto_launch_editor() {
+  local worktree_path="$1"
+  local editor
+  editor=$(_cfg_editor_default)
+  if [ "$editor" != "none" ]; then
+    _open_editor "$editor" "$worktree_path"
+  else
+    open_in_gui "$worktree_path"
+    log_info "Opened in file browser (no editor configured)"
+  fi
+}
+
+# Auto-launch AI tool for a worktree
+_auto_launch_ai() {
+  local worktree_path="$1"
+  local ai_tool
+  ai_tool=$(_cfg_ai_default)
+  if [ "$ai_tool" = "none" ]; then
+    log_warn "No AI tool configured. Set with: git gtr config set gtr.ai.default claude"
+  else
+    load_ai_adapter "$ai_tool" || return 1
+    log_step "Starting $ai_tool..."
+    ai_start "$worktree_path"
+  fi
+}
diff --git a/lib/ui.sh b/lib/ui.sh
index 7e2d700..b3278df 100644
--- a/lib/ui.sh
+++ b/lib/ui.sh
@@ -21,6 +21,12 @@ log_question() {
   printf "[?] %s" "$*"
 }
 
+# Show help and exit (for --help flag in subcommands)
+show_command_help() {
+  cmd_help
+  exit 0
+}
+
 # Prompt for yes/no confirmation
 # Usage: prompt_yes_no "Question text" [default]
 # Returns: 0 for yes, 1 for no
diff --git a/templates/gtr.config.example b/templates/gtr.config.example
index 888feaf..3566c6e 100644
--- a/templates/gtr.config.example
+++ b/templates/gtr.config.example
@@ -36,9 +36,9 @@
 # === AI Tool Settings ===
 
 # Default AI coding tool
-# Options: aider, or none
+# Options: aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode, none
 # Default: none
-# gtr.ai.default = aider
+# gtr.ai.default = claude
 
 # === File Copying ===
 

From 41c1488f3484b934da47ba74588fb6ed225fe939 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 17:37:12 -0800
Subject: [PATCH 11/19] refactor: enhance argument parsing and command
 completion

- Introduced a shared argument parser in `lib/args.sh` to streamline command argument handling across various commands.
- Updated command scripts to utilize the new parser, improving clarity and maintainability by reducing repetitive code.
- Enhanced completion scripts for Bash, Zsh, and Fish to reflect updated command options and improve user experience.
- Added integration tests for the argument parser to ensure functionality and reliability in command execution.
---
 bin/gtr                          |   1 +
 completions/_git-gtr             |  10 +-
 completions/git-gtr.fish         |  37 +-
 completions/gtr.bash             |  11 +-
 lib/adapters.sh                  |   2 +
 lib/args.sh                      | 125 ++++++
 lib/commands/adapter.sh          |   4 +-
 lib/commands/ai.sh               |  43 +-
 lib/commands/clean.sh            |  43 +-
 lib/commands/copy.sh             |  85 ++--
 lib/commands/create.sh           | 116 ++----
 lib/commands/doctor.sh           |   8 +-
 lib/commands/editor.sh           |  34 +-
 lib/commands/go.sh               |  13 +-
 lib/commands/list.sh             |  21 +-
 lib/commands/remove.sh           |  57 +--
 lib/commands/rename.sh           |  47 +--
 lib/commands/run.sh              |  18 +-
 lib/copy.sh                      |   8 +-
 lib/core.sh                      |   9 +
 lib/launch.sh                    |   7 +-
 scripts/generate-completions.sh  | 687 +++++++++++++++++++++++++++++++
 tests/integration_lifecycle.bats | 118 ++++++
 tests/parse_args.bats            |  96 +++++
 tests/test_helper.bash           |  60 ++-
 25 files changed, 1293 insertions(+), 367 deletions(-)
 create mode 100644 lib/args.sh
 create mode 100755 scripts/generate-completions.sh
 create mode 100644 tests/integration_lifecycle.bats
 create mode 100644 tests/parse_args.bats

diff --git a/bin/gtr b/bin/gtr
index 88fb15e..f88a08c 100755
--- a/bin/gtr
+++ b/bin/gtr
@@ -22,6 +22,7 @@ resolve_script_dir() {
 
 # Source library files
 . "$GTR_DIR/lib/ui.sh"
+. "$GTR_DIR/lib/args.sh"
 . "$GTR_DIR/lib/config.sh"
 . "$GTR_DIR/lib/platform.sh"
 . "$GTR_DIR/lib/core.sh"
diff --git a/completions/_git-gtr b/completions/_git-gtr
index aac1d51..5639273 100644
--- a/completions/_git-gtr
+++ b/completions/_git-gtr
@@ -1,4 +1,6 @@
 #compdef _git-gtr git-gtr gtr
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
 #
 # Zsh completion for git gtr (Git Worktree Runner)
 #
@@ -119,10 +121,10 @@ _git-gtr() {
   elif (( CURRENT >= 5 )); then
     case "$words[3]" in
       editor)
-        _arguments '--editor[Editor to use]:editor:(cursor vscode zed idea pycharm webstorm vim nvim emacs sublime nano atom none)'
+        _arguments '--editor[Editor to use]:editor:(atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed)'
         ;;
       ai)
-        _arguments '--ai[AI tool to use]:tool:(aider auggie claude codex continue copilot cursor gemini opencode none)'
+        _arguments '--ai[AI tool to use]:tool:(aider auggie claude codex continue copilot cursor gemini none opencode)'
         ;;
       rm)
         _arguments \
@@ -172,7 +174,7 @@ _git-gtr() {
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
                 '--system[Use system git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider)'
               ;;
             set|add|unset)
               # Write operations only support --local and --global
@@ -180,7 +182,7 @@ _git-gtr() {
               _arguments \
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider)'
               ;;
           esac
         fi
diff --git a/completions/git-gtr.fish b/completions/git-gtr.fish
index fd5cc1f..7dd300e 100644
--- a/completions/git-gtr.fish
+++ b/completions/git-gtr.fish
@@ -1,3 +1,6 @@
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
 # Fish completion for git gtr
 #
 # This completion integrates with fish's completion system by registering completions
@@ -88,10 +91,10 @@ complete -c git -n '__fish_git_gtr_using_command list' -l porcelain -d 'Machine-
 complete -c git -n '__fish_git_gtr_using_command ls' -l porcelain -d 'Machine-readable output'
 
 # Editor command options
-complete -c git -n '__fish_git_gtr_using_command editor' -l editor -d 'Editor to use' -r -a 'cursor vscode zed idea pycharm webstorm vim nvim emacs sublime nano atom none'
+complete -c git -n '__fish_git_gtr_using_command editor' -l editor -d 'Editor to use' -r -a 'atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed'
 
 # AI command options
-complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a 'aider auggie claude codex continue copilot cursor gemini opencode none'
+complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a 'aider auggie claude codex continue copilot cursor gemini none opencode'
 
 # Clean command options
 complete -c git -n '__fish_git_gtr_using_command clean' -l merged -d 'Remove worktrees with merged PRs/MRs'
@@ -132,21 +135,21 @@ complete -f -c git -n '__fish_git_gtr_using_command config' -l global -d 'Use gl
 # --system only for read operations (list, get) - write requires root
 complete -f -c git -n '__fish_git_gtr_using_command config; and __fish_git_gtr_config_is_read' -l system -d 'Use system git config'
 complete -f -c git -n '__fish_git_gtr_using_command config' -a "
-  gtr.worktrees.dir\t'Worktrees base directory'
-  gtr.worktrees.prefix\t'Worktree folder prefix'
-  gtr.defaultBranch\t'Default branch'
-  gtr.editor.default\t'Default editor'
-  gtr.editor.workspace\t'Path to workspace file (.code-workspace)'
-  gtr.ai.default\t'Default AI tool'
-  gtr.provider\t'Hosting provider (github, gitlab)'
-  gtr.copy.include\t'Files to copy'
-  gtr.copy.exclude\t'Files to exclude'
-  gtr.copy.includeDirs\t'Directories to copy (e.g., node_modules)'
-  gtr.copy.excludeDirs\t'Directories to exclude'
-  gtr.hook.postCreate\t'Post-create hook'
-  gtr.hook.preRemove\t'Pre-remove hook (abort on failure)'
-  gtr.hook.postRemove\t'Post-remove hook'
-  gtr.hook.postCd\t'Post-cd hook (shell integration only)'
+  gtr.copy.include	'Files to copy'
+  gtr.copy.exclude	'Files to exclude'
+  gtr.copy.includeDirs	'Directories to copy (e.g., node_modules)'
+  gtr.copy.excludeDirs	'Directories to exclude'
+  gtr.hook.postCreate	'Post-create hook'
+  gtr.hook.preRemove	'Pre-remove hook (abort on failure)'
+  gtr.hook.postRemove	'Post-remove hook'
+  gtr.hook.postCd	'Post-cd hook (shell integration only)'
+  gtr.editor.default	'Default editor'
+  gtr.editor.workspace	'Path to workspace file (.code-workspace)'
+  gtr.ai.default	'Default AI tool'
+  gtr.worktrees.dir	'Worktrees base directory'
+  gtr.worktrees.prefix	'Worktree folder prefix'
+  gtr.defaultBranch	'Default branch'
+  gtr.provider	'Hosting provider (github, gitlab)'
 "
 
 # Helper function to get branch names and special '1' for main repo
diff --git a/completions/gtr.bash b/completions/gtr.bash
index 0f41ae8..bd92f30 100644
--- a/completions/gtr.bash
+++ b/completions/gtr.bash
@@ -1,4 +1,7 @@
 #!/bin/bash
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
 # Bash completion for git gtr
 #
 # Prerequisites:
@@ -52,7 +55,7 @@ _git_gtr() {
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--editor" -- "$cur"))
       elif [ "$prev" = "--editor" ]; then
-        COMPREPLY=($(compgen -W "cursor vscode zed idea pycharm webstorm vim nvim emacs sublime nano atom none" -- "$cur"))
+        COMPREPLY=($(compgen -W "atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed" -- "$cur"))
       else
         local branches all_options
         branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
@@ -64,7 +67,7 @@ _git_gtr() {
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--ai" -- "$cur"))
       elif [ "$prev" = "--ai" ]; then
-        COMPREPLY=($(compgen -W "aider auggie claude codex continue copilot cursor gemini opencode none" -- "$cur"))
+        COMPREPLY=($(compgen -W "aider auggie claude codex continue copilot cursor gemini none opencode" -- "$cur"))
       else
         local branches all_options
         branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
@@ -128,7 +131,7 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global --system" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider" -- "$cur"))
             fi
             ;;
           set|add|unset)
@@ -136,7 +139,7 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider" -- "$cur"))
             fi
             ;;
         esac
diff --git a/lib/adapters.sh b/lib/adapters.sh
index 667c5a1..9d59757 100644
--- a/lib/adapters.sh
+++ b/lib/adapters.sh
@@ -96,8 +96,10 @@ _load_from_ai_registry() {
   if [ -n "$info_lines_raw" ]; then
     local old_ifs="$IFS"
     IFS=';'
+    set -f  # Disable globbing during split
     # shellcheck disable=SC2086
     set -- $info_lines_raw
+    set +f
     _AI_INFO_LINES=("$@")
     IFS="$old_ifs"
   fi
diff --git a/lib/args.sh b/lib/args.sh
new file mode 100644
index 0000000..6443668
--- /dev/null
+++ b/lib/args.sh
@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Shared argument parser for gtr commands
+# Depends on: ui.sh (log_error, show_command_help)
+#
+# Usage:
+#   parse_args "<spec>" "$@"
+#
+# Spec format (one flag per line):
+#   --force                    # boolean flag → _arg_force=1
+#   --from: value              # value flag → _arg_from="<val>"
+#   --dry-run|-n               # aliases → _arg_dry_run=1
+#   --editor|-e                # short alias → _arg_editor=1
+#
+# Output variables:
+#   _pa_positional[]   — positional arguments (array)
+#   _pa_passthrough[]  — arguments after -- (array)
+#   _arg_<name>        — one per declared flag (hyphens → underscores)
+declare -a _pa_positional _pa_passthrough
+
+# Try to match a flag against the spec. Sets _arg_<name> and _pa_shift_count.
+# Returns 0 if matched, 1 if no match.
+_pa_match_flag() {
+  local spec="$1" flag="$2" next_val="${3:-}"
+
+  _pa_shift_count=0
+
+  local line
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+
+    # Check if spec line ends with ": value"
+    local has_value=0
+    case "$line" in
+      *": value")
+        has_value=1
+        line="${line%: value}"
+        ;;
+    esac
+
+    # Check if $flag matches any alternative in the pattern
+    local alt matched=0
+    local IFS_save="$IFS"
+    IFS="|"
+    for alt in $line; do
+      if [ "$flag" = "$alt" ]; then
+        matched=1
+        break
+      fi
+    done
+    IFS="$IFS_save"
+
+    if [ "$matched" = "1" ]; then
+      # Derive variable name from the first (canonical) pattern
+      local canonical="${line%%|*}"
+      canonical="${canonical#--}"
+      canonical="${canonical#-}"
+      canonical="${canonical//-/_}"
+
+      if [ "$has_value" = "1" ]; then
+        if [ -z "$next_val" ]; then
+          log_error "$flag requires a value"
+          exit 1
+        fi
+        eval "_arg_${canonical}=\"\$next_val\""
+        _pa_shift_count=2
+      else
+        eval "_arg_${canonical}=1"
+        _pa_shift_count=1
+      fi
+      return 0
+    fi
+  done <<EOF
+$spec
+EOF
+
+  return 1
+}
+
+# Main parser. Call from command functions as: parse_args "<spec>" "$@"
+parse_args() {
+  local _pa_spec="$1"
+  shift
+
+  _pa_positional=()
+  _pa_passthrough=()
+
+  # Reset all _arg_ variables from the spec to empty
+  local _pa_line
+  while IFS= read -r _pa_line; do
+    [ -z "$_pa_line" ] && continue
+    local _pa_clean="${_pa_line%: value}"
+    local _pa_canonical="${_pa_clean%%|*}"
+    _pa_canonical="${_pa_canonical#--}"
+    _pa_canonical="${_pa_canonical#-}"
+    _pa_canonical="${_pa_canonical//-/_}"
+    eval "_arg_${_pa_canonical}=''"
+  done <<EOF
+$_pa_spec
+EOF
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -h|--help)
+        show_command_help
+        ;;
+      --)
+        shift
+        _pa_passthrough=("$@")
+        break
+        ;;
+      -*)
+        if _pa_match_flag "$_pa_spec" "$@"; then
+          shift "$_pa_shift_count"
+        else
+          log_error "Unknown flag: $1"
+          exit 1
+        fi
+        ;;
+      *)
+        _pa_positional+=("$1")
+        shift
+        ;;
+    esac
+  done
+}
diff --git a/lib/commands/adapter.sh b/lib/commands/adapter.sh
index f2ea3f6..92ce70f 100644
--- a/lib/commands/adapter.sh
+++ b/lib/commands/adapter.sh
@@ -45,9 +45,7 @@ EOF
 }
 
 cmd_adapter() {
-  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
-    show_command_help
-  fi
+  parse_args "" "$@"
 
   echo "Available Adapters"
   echo ""
diff --git a/lib/commands/ai.sh b/lib/commands/ai.sh
index b709a76..0d14cfc 100644
--- a/lib/commands/ai.sh
+++ b/lib/commands/ai.sh
@@ -1,38 +1,13 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # AI command
 cmd_ai() {
-  local identifier=""
-  local ai_tool=""
-  local -a ai_args=()
+  parse_args "--ai: value" "$@"
 
-  # Parse arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --ai)
-        ai_tool="$2"
-        shift 2
-        ;;
-      --)
-        shift
-        ai_args=("$@")
-        break
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$identifier" ]; then
-          identifier="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
+  local identifier="${_pa_positional[0]:-}"
+  local ai_tool="${_arg_ai:-}"
+  local -a ai_args=("${_pa_passthrough[@]}")
 
   if [ -z "$identifier" ]; then
     log_error "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
@@ -52,7 +27,7 @@ cmd_ai() {
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Load AI adapter (after context — fail fast on bad repo first)
@@ -61,12 +36,12 @@ cmd_ai() {
   # Resolve target branch
   local worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   log_step "Starting $ai_tool for: $branch"
-  echo "Directory: $worktree_path"
-  echo "Branch: $branch"
+  log_info "Directory: $worktree_path"
+  log_info "Branch: $branch"
 
   ai_start "$worktree_path" "${ai_args[@]}"
 }
\ No newline at end of file
diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index f1fca22..3a5761a 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Clean command (remove prunable worktrees)
 # Remove worktrees whose PRs/MRs are merged (handles squash merges)
@@ -112,37 +113,15 @@ _clean_merged() {
 }
 
 cmd_clean() {
-  local merged_mode=0
-  local yes_mode=0
-  local dry_run=0
-
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --merged)
-        merged_mode=1
-        shift
-        ;;
-      --yes|-y)
-        yes_mode=1
-        shift
-        ;;
-      --dry-run|-n)
-        dry_run=1
-        shift
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        shift
-        ;;
-    esac
-  done
+  local _spec
+  _spec="--merged
+--yes|-y
+--dry-run|-n"
+  parse_args "$_spec" "$@"
+
+  local merged_mode="${_arg_merged:-0}"
+  local yes_mode="${_arg_yes:-0}"
+  local dry_run="${_arg_dry_run:-0}"
 
   log_step "Cleaning up stale worktrees..."
 
@@ -152,7 +131,7 @@ cmd_clean() {
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   if [ ! -d "$base_dir" ]; then
diff --git a/lib/commands/copy.sh b/lib/commands/copy.sh
index 92d3734..20d86a0 100644
--- a/lib/commands/copy.sh
+++ b/lib/commands/copy.sh
@@ -1,77 +1,52 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Copy command (copy files between worktrees)
 cmd_copy() {
-  local source="1"  # Default: main repo
-  local targets=""
-  local patterns=""
-  local all_mode=0
-  local dry_run=0
+  local _spec
+  _spec="--from: value
+--dry-run|-n
+--all|-a"
+  parse_args "$_spec" "$@"
+
+  local source="${_arg_from:-1}"  # Default: main repo
+  local -a targets=("${_pa_positional[@]}")
+  local all_mode="${_arg_all:-0}"
+  local dry_run="${_arg_dry_run:-0}"
 
-  # Parse arguments (patterns come after -- separator, like git pathspec)
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --from)
-        source="$2"
-        shift 2
-        ;;
-      -n|--dry-run)
-        dry_run=1
-        shift
-        ;;
-      -a|--all)
-        all_mode=1
-        shift
-        ;;
-      --)
-        shift
-        # Remaining args are patterns (like git pathspec)
-        while [ $# -gt 0 ]; do
-          if [ -n "$patterns" ]; then
-            patterns="$patterns"$'\n'"$1"
-          else
-            patterns="$1"
-          fi
-          shift
-        done
-        break
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        targets="$targets $1"
-        shift
-        ;;
-    esac
+  # Convert passthrough args (after --) to newline-separated patterns
+  local patterns=""
+  local _p
+  for _p in "${_pa_passthrough[@]}"; do
+    if [ -n "$patterns" ]; then
+      patterns="$patterns"$'\n'"$_p"
+    else
+      patterns="$_p"
+    fi
   done
 
   # Validation
-  if [ "$all_mode" -eq 0 ] && [ -z "$targets" ]; then
+  if [ "$all_mode" -eq 0 ] && [ ${#targets[@]} -eq 0 ]; then
     log_error "Usage: git gtr copy <target>... [-n] [-a] [--from <source>] [-- <pattern>...]"
     exit 1
   fi
 
   # Get repo context
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve source path
   local src_path
   resolve_worktree "$source" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   src_path="$_ctx_worktree_path"
 
   # Get patterns (flag > config + .worktreeinclude)
   local excludes
   if [ -z "$patterns" ]; then
     merge_copy_patterns "$repo_root"
-    # shellcheck disable=SC2154
+  
     patterns="$_ctx_copy_includes" excludes="$_ctx_copy_excludes"
   else
     excludes=$(cfg_get_all gtr.copy.exclude copy.exclude)
@@ -84,19 +59,23 @@ cmd_copy() {
 
   # Build target list for --all mode
   if [ "$all_mode" -eq 1 ]; then
-    targets=$(list_worktree_branches "$base_dir" "$prefix")
-    if [ -z "$targets" ]; then
+    local all_branches
+    all_branches=$(list_worktree_branches "$base_dir" "$prefix")
+    if [ -z "$all_branches" ]; then
       log_error "No worktrees found"
       exit 1
     fi
+    while IFS= read -r _branch; do
+      [ -n "$_branch" ] && targets+=("$_branch")
+    done <<< "$all_branches"
   fi
 
   # Process each target
   local copied_any=0
-  for target_id in $targets; do
+  for target_id in "${targets[@]}"; do
     local dst_path dst_branch
     resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue
-    # shellcheck disable=SC2154
+  
     dst_path="$_ctx_worktree_path" dst_branch="$_ctx_branch"
 
     # Skip if source == destination
diff --git a/lib/commands/create.sh b/lib/commands/create.sh
index b40fb44..8411666 100644
--- a/lib/commands/create.sh
+++ b/lib/commands/create.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Create command
 # Copy files and directories to newly created worktree
@@ -8,7 +9,7 @@ _post_create_copy() {
   local worktree_path="$2"
 
   merge_copy_patterns "$repo_root"
-  # shellcheck disable=SC2154
+
   local includes="$_ctx_copy_includes" excludes="$_ctx_copy_excludes"
 
   if [ -n "$includes" ]; then
@@ -39,7 +40,7 @@ _post_create_next_steps() {
     local resolve_result
     if resolve_result=$(resolve_target "$folder_name" "$repo_root" "$base_dir" "$prefix" 2>/dev/null); then
       unpack_target "$resolve_result"
-      # shellcheck disable=SC2154
+    
       if [ "$_ctx_is_main" = "1" ]; then
         # Collision: folder name matches current branch, use branch name instead
         next_steps_id="$branch_name"
@@ -83,87 +84,34 @@ _create_resolve_from_ref() {
   printf "%s" "$from_ref"
 }
 cmd_create() {
-  local branch_name=""
-  local from_ref=""
-  local from_current=0
-  local track_mode="auto"
-  local skip_copy=0
-  local skip_fetch=0
-  local skip_hooks=0
-  local yes_mode=0
-  local force=0
-  local custom_name=""
-  local folder_override=""
-  local open_editor=0
-  local start_ai=0
-
-  # Parse flags and arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --from)
-        from_ref="$2"
-        shift 2
-        ;;
-      --from-current)
-        from_current=1
-        shift
-        ;;
-      --track)
-        track_mode="$2"
-        shift 2
-        ;;
-      --no-copy)
-        skip_copy=1
-        shift
-        ;;
-      --no-fetch)
-        skip_fetch=1
-        shift
-        ;;
-      --no-hooks)
-        skip_hooks=1
-        shift
-        ;;
-      --yes)
-        yes_mode=1
-        shift
-        ;;
-      --force)
-        force=1
-        shift
-        ;;
-      --name)
-        custom_name="$2"
-        shift 2
-        ;;
-      --folder)
-        folder_override="$2"
-        shift 2
-        ;;
-      --editor|-e)
-        open_editor=1
-        shift
-        ;;
-      --ai|-a)
-        start_ai=1
-        shift
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        # Positional argument: treat as branch name
-        if [ -z "$branch_name" ]; then
-          branch_name="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
+  local _spec
+  _spec="--from: value
+--from-current
+--track: value
+--no-copy
+--no-fetch
+--no-hooks
+--yes
+--force
+--name: value
+--folder: value
+--editor|-e
+--ai|-a"
+  parse_args "$_spec" "$@"
+
+  local branch_name="${_pa_positional[0]:-}"
+  local from_ref="${_arg_from:-}"
+  local from_current="${_arg_from_current:-0}"
+  local track_mode="${_arg_track:-auto}"
+  local skip_copy="${_arg_no_copy:-0}"
+  local skip_fetch="${_arg_no_fetch:-0}"
+  local skip_hooks="${_arg_no_hooks:-0}"
+  local yes_mode="${_arg_yes:-0}"
+  local force="${_arg_force:-0}"
+  local custom_name="${_arg_name:-}"
+  local folder_override="${_arg_folder:-}"
+  local open_editor="${_arg_editor:-0}"
+  local start_ai="${_arg_ai:-0}"
 
   # Validate flag combinations
   if [ -n "$folder_override" ] && [ -n "$custom_name" ]; then
@@ -185,7 +133,7 @@ cmd_create() {
 
   # Get repo info
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Get branch name if not provided
diff --git a/lib/commands/doctor.sh b/lib/commands/doctor.sh
index 2afa813..e435ce4 100644
--- a/lib/commands/doctor.sh
+++ b/lib/commands/doctor.sh
@@ -2,9 +2,7 @@
 
 # Doctor command (health check)
 cmd_doctor() {
-  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
-    show_command_help
-  fi
+  parse_args "" "$@"
 
   echo "Running git gtr health check..."
   echo ""
@@ -33,7 +31,9 @@ cmd_doctor() {
 
     if [ -d "$base_dir" ]; then
       local count
-      count=$(find "$base_dir" -maxdepth 1 -type d -name "${prefix}*" 2>/dev/null | wc -l | tr -d ' ')
+      count=$(git worktree list --porcelain 2>/dev/null | grep -c '^worktree ' || true)
+      count=$((count - 1))  # Exclude main worktree
+      [ "$count" -lt 0 ] && count=0
       echo "[OK] Worktrees directory: $base_dir ($count worktrees)"
     else
       echo "[i] Worktrees directory: $base_dir (not created yet)"
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
index a0aec88..5706a50 100644
--- a/lib/commands/editor.sh
+++ b/lib/commands/editor.sh
@@ -1,32 +1,12 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Editor command
 cmd_editor() {
-  local identifier=""
-  local editor=""
-
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --editor)
-        editor="$2"
-        shift 2
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$identifier" ]; then
-          identifier="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
+  parse_args "--editor: value" "$@"
+
+  local identifier="${_pa_positional[0]:-}"
+  local editor="${_arg_editor:-}"
 
   if [ -z "$identifier" ]; then
     log_error "Usage: git gtr editor <id|branch> [--editor <name>]"
@@ -39,13 +19,13 @@ cmd_editor() {
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
   local worktree_path
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   worktree_path="$_ctx_worktree_path"
 
   if [ "$editor" = "none" ]; then
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
index cf939e8..d0b189f 100644
--- a/lib/commands/go.sh
+++ b/lib/commands/go.sh
@@ -1,25 +1,24 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Go command (navigate to worktree - prints path for shell integration)
 cmd_go() {
-  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
-    show_command_help
-  fi
+  parse_args "" "$@"
 
-  if [ $# -ne 1 ]; then
+  if [ ${#_pa_positional[@]} -ne 1 ]; then
     log_error "Usage: git gtr go <id|branch>"
     exit 1
   fi
 
-  local identifier="$1"
+  local identifier="${_pa_positional[0]}"
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
   local is_main worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   # Human messages to stderr so stdout can be used in command substitution
diff --git a/lib/commands/list.sh b/lib/commands/list.sh
index ec5bbcf..2f1313b 100644
--- a/lib/commands/list.sh
+++ b/lib/commands/list.sh
@@ -1,27 +1,14 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # List command
 cmd_list() {
-  local porcelain=0
+  parse_args "--porcelain" "$@"
 
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --porcelain)
-        porcelain=1
-        shift
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      *)
-        shift
-        ;;
-    esac
-  done
+  local porcelain="${_arg_porcelain:-0}"
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Machine-readable output (porcelain)
diff --git a/lib/commands/remove.sh b/lib/commands/remove.sh
index 239d5ec..f555787 100644
--- a/lib/commands/remove.sh
+++ b/lib/commands/remove.sh
@@ -1,55 +1,32 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Remove command
 cmd_remove() {
-  local delete_branch=0
-  local yes_mode=0
-  local force=0
-  local identifiers=""
+  local _spec
+  _spec="--delete-branch
+--yes
+--force"
+  parse_args "$_spec" "$@"
 
-  # Parse flags
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --delete-branch)
-        delete_branch=1
-        shift
-        ;;
-      --yes)
-        yes_mode=1
-        shift
-        ;;
-      --force)
-        force=1
-        shift
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        identifiers="$identifiers $1"
-        shift
-        ;;
-    esac
-  done
+  local delete_branch="${_arg_delete_branch:-0}"
+  local yes_mode="${_arg_yes:-0}"
+  local force="${_arg_force:-0}"
 
-  if [ -z "$identifiers" ]; then
+  if [ ${#_pa_positional[@]} -eq 0 ]; then
     log_error "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
     exit 1
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
-  for identifier in $identifiers; do
+  for identifier in "${_pa_positional[@]}"; do
     # Resolve target branch
     local is_main worktree_path branch_name
     resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || continue
-    # shellcheck disable=SC2154
+  
     is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch_name="$_ctx_branch"
 
     # Cannot remove main repository
@@ -91,10 +68,12 @@ cmd_remove() {
       fi
     fi
 
-    # Run post-remove hooks
-    run_hooks postRemove \
+    # Run post-remove hooks (don't abort on failure — worktree already removed)
+    if ! run_hooks postRemove \
       REPO_ROOT="$repo_root" \
       WORKTREE_PATH="$worktree_path" \
-      BRANCH="$branch_name"
+      BRANCH="$branch_name"; then
+      log_warn "Post-remove hook failed for $branch_name"
+    fi
   done
 }
\ No newline at end of file
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
index 98527ee..ae3dff4 100644
--- a/lib/commands/rename.sh
+++ b/lib/commands/rename.sh
@@ -1,40 +1,17 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Rename command (rename worktree and branch)
 cmd_rename() {
-  local old_identifier=""
-  local new_name=""
-  local force=0
-  local yes_mode=0
-
-  # Parse flags and arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --force)
-        force=1
-        shift
-        ;;
-      --yes)
-        yes_mode=1
-        shift
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$old_identifier" ]; then
-          old_identifier="$1"
-        elif [ -z "$new_name" ]; then
-          new_name="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
+  local _spec
+  _spec="--force
+--yes"
+  parse_args "$_spec" "$@"
+
+  local old_identifier="${_pa_positional[0]:-}"
+  local new_name="${_pa_positional[1]:-}"
+  local force="${_arg_force:-0}"
+  local yes_mode="${_arg_yes:-0}"
 
   # Validate arguments
   if [ -z "$old_identifier" ] || [ -z "$new_name" ]; then
@@ -43,13 +20,13 @@ cmd_rename() {
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve old worktree
   local is_main old_path old_branch
   resolve_worktree "$old_identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   is_main="$_ctx_is_main" old_path="$_ctx_worktree_path" old_branch="$_ctx_branch"
 
   # Cannot rename main repository
diff --git a/lib/commands/run.sh b/lib/commands/run.sh
index 838cb49..a19120c 100644
--- a/lib/commands/run.sh
+++ b/lib/commands/run.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # Run command (execute command in worktree directory)
 cmd_run() {
@@ -11,7 +12,20 @@ cmd_run() {
       -h|--help)
         show_command_help
         ;;
+      --)
+        shift
+        if [ -z "$identifier" ]; then
+          log_error "Usage: git gtr run <id|branch> [--] <command...>"
+          exit 1
+        fi
+        run_args=("$@")
+        break
+        ;;
       -*)
+        if [ -n "$identifier" ]; then
+          run_args=("$@")  # Flag-like args are part of the command
+          break
+        fi
         log_error "Unknown flag: $1"
         exit 1
         ;;
@@ -40,13 +54,13 @@ cmd_run() {
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Resolve target branch
   local is_main worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   # Human messages to stderr (like cmd_go)
diff --git a/lib/copy.sh b/lib/copy.sh
index 5d3f9c1..2cf9363 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 # File copying utilities with pattern matching
 
+# --- Context Globals Contract ---
+# merge_copy_patterns() -> _ctx_copy_includes  _ctx_copy_excludes
+declare _ctx_copy_includes _ctx_copy_excludes
+
 # Check if a path/pattern is unsafe (absolute or contains directory traversal)
 # Usage: _is_unsafe_path "pattern"
 # Returns: 0 if unsafe, 1 if safe
@@ -171,7 +175,7 @@ copy_patterns() {
           copied_count=$((copied_count + 1))
         fi
       done <<EOF
-$(find . -path "./$pattern" -type f 2>/dev/null)
+$(find . -path "./$pattern" -type f 2>/dev/null || true)
 EOF
     else
       # Use native Bash glob expansion (supports ** if available)
@@ -339,7 +343,7 @@ EOF
         log_warn "Failed to copy directory $dir_path"
       fi
     done <<EOF
-$(if [[ "$pattern" == */* ]]; then find . -type d -path "./$pattern" 2>/dev/null; else find . -type d -name "$pattern" 2>/dev/null; fi)
+$(if [[ "$pattern" == */* ]]; then find . -type d -path "./$pattern" 2>/dev/null; else find . -type d -name "$pattern" 2>/dev/null; fi || true)
 EOF
   done <<EOF
 $dir_patterns
diff --git a/lib/core.sh b/lib/core.sh
index 54b43ad..d60b8d3 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -1,6 +1,15 @@
 #!/usr/bin/env bash
 # Core git worktree operations
 
+# --- Context Globals Contract ---
+# Resolver functions set these globals as a return mechanism (Bash lacks multi-return).
+# Callers should copy into locals immediately after calling the resolver.
+#
+# resolve_repo_context() -> _ctx_repo_root  _ctx_base_dir  _ctx_prefix
+# resolve_worktree()     -> _ctx_is_main    _ctx_worktree_path  _ctx_branch
+declare _ctx_repo_root _ctx_base_dir _ctx_prefix
+declare _ctx_is_main _ctx_worktree_path _ctx_branch
+
 # Discover the root of the current git repository
 # Returns: absolute path to repo root
 # Exit code: 0 on success, 1 if not in a git repo
diff --git a/lib/launch.sh b/lib/launch.sh
index 0998482..517e5d8 100644
--- a/lib/launch.sh
+++ b/lib/launch.sh
@@ -32,8 +32,11 @@ _auto_launch_editor() {
   if [ "$editor" != "none" ]; then
     _open_editor "$editor" "$worktree_path"
   else
-    open_in_gui "$worktree_path"
-    log_info "Opened in file browser (no editor configured)"
+    if ! open_in_gui "$worktree_path"; then
+      log_warn "Could not open file browser"
+    else
+      log_info "Opened in file browser (no editor configured)"
+    fi
   fi
 }
 
diff --git a/scripts/generate-completions.sh b/scripts/generate-completions.sh
new file mode 100755
index 0000000..07c1a0d
--- /dev/null
+++ b/scripts/generate-completions.sh
@@ -0,0 +1,687 @@
+#!/usr/bin/env bash
+# Generate shell completion files from adapter registries and config key maps.
+# Sources of truth: _EDITOR_REGISTRY, _AI_REGISTRY (lib/adapters.sh), _CFG_KEY_MAP (lib/config.sh)
+#
+# Usage:
+#   ./scripts/generate-completions.sh          # Regenerate all completion files
+#   ./scripts/generate-completions.sh --check  # Verify files are up to date (for CI)
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# ── Data extraction ──────────────────────────────────────────────────────────
+
+# Extract adapter names from a registry variable (pipe-delimited, name is first field)
+_names_from_registry() {
+  local registry="$1"
+  local line
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    printf "%s\n" "${line%%|*}"
+  done <<EOF
+$registry
+EOF
+}
+
+# Source just the registry variables (no side effects — we only need the data)
+# Stub out all functions these files define to avoid dependency issues
+log_error() { :; }; log_info() { :; }; log_warn() { :; }; log_step() { :; }
+cfg_default() { :; }; cfg_get() { :; }; cfg_get_all() { :; }; cfg_get_file() { :; }
+cfg_map_to_file_key() { :; }; cfg_map_from_file_key() { :; }; _cfg_is_known_key() { :; }
+show_command_help() { :; }; _cfg_editor_default() { echo "none"; }; _cfg_ai_default() { echo "none"; }
+command() { :; }; _gtrconfig_path() { :; }
+discover_repo_root() { :; }; resolve_base_dir() { :; }
+
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/adapters.sh" 2>/dev/null || true
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/config.sh" 2>/dev/null || true
+
+# Collect editor names: registry + custom files, sorted, deduplicated
+get_editor_names() {
+  local names
+  names=$(_names_from_registry "$_EDITOR_REGISTRY")
+
+  # Add custom adapter file names
+  local f name
+  for f in "$SCRIPT_DIR"/adapters/editor/*.sh; do
+    [ -f "$f" ] || continue
+    name=$(basename "$f" .sh)
+    names="$names"$'\n'"$name"
+  done
+
+  # Sort, deduplicate, add "none" sentinel
+  printf "%s\nnone\n" "$names" | sort -u | tr '\n' ' ' | sed 's/ *$//'
+}
+
+# Collect AI tool names: registry + custom files, sorted, deduplicated
+get_ai_names() {
+  local names
+  names=$(_names_from_registry "$_AI_REGISTRY")
+
+  local f name
+  for f in "$SCRIPT_DIR"/adapters/ai/*.sh; do
+    [ -f "$f" ] || continue
+    name=$(basename "$f" .sh)
+    names="$names"$'\n'"$name"
+  done
+
+  printf "%s\nnone\n" "$names" | sort -u | tr '\n' ' ' | sed 's/ *$//'
+}
+
+# Collect config keys from _CFG_KEY_MAP (left side of each pair)
+get_config_keys() {
+  local pair keys=""
+  for pair in "${_CFG_KEY_MAP[@]}"; do
+    keys="$keys ${pair%%|*}"
+  done
+  echo "$keys" | xargs  # trim whitespace
+}
+
+# ── Resolve data ─────────────────────────────────────────────────────────────
+
+EDITORS=$(get_editor_names)
+AI_TOOLS=$(get_ai_names)
+CONFIG_KEYS=$(get_config_keys)
+
+# ── Generators ───────────────────────────────────────────────────────────────
+
+generate_bash() {
+  cat <<'HEADER'
+#!/bin/bash
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
+# Bash completion for git gtr
+#
+# Prerequisites:
+#   - bash-completion v2+ must be installed
+#   - Git's bash completion must be enabled
+#
+# This completion integrates with git's completion system by defining a _git_<subcommand>
+# function, which git's completion framework automatically discovers and calls when
+# completing "git gtr ..." commands.
+#
+# Installation:
+#   Add to your ~/.bashrc:
+#     source /path/to/git-worktree-runner/completions/gtr.bash
+
+_git_gtr() {
+  local cur prev words cword
+  _init_completion || return
+
+  # words array for git subcommand: [git, gtr, <actual_command>, ...]
+  # cword is the index of current word being completed
+
+  # If we're completing the first argument after 'git gtr'
+  if [ "$cword" -eq 2 ]; then
+    COMPREPLY=($(compgen -W "new go run copy editor ai rm mv rename ls list clean doctor adapter config completion init help version" -- "$cur"))
+    return 0
+  fi
+
+  local cmd="${words[2]}"
+
+  # Commands that take branch names or '1' for main repo
+  case "$cmd" in
+    go|run|rm|mv|rename)
+      if [ "$cword" -eq 3 ]; then
+        # Complete with branch names and special ID '1' for main repo
+        local branches all_options
+        branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
+        all_options="1 $branches"
+        COMPREPLY=($(compgen -W "$all_options" -- "$cur"))
+      elif [[ "$cur" == -* ]]; then
+        case "$cmd" in
+          rm)
+            COMPREPLY=($(compgen -W "--delete-branch --force --yes" -- "$cur"))
+            ;;
+          mv|rename)
+            COMPREPLY=($(compgen -W "--force --yes" -- "$cur"))
+            ;;
+        esac
+      fi
+      ;;
+    editor)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "--editor" -- "$cur"))
+      elif [ "$prev" = "--editor" ]; then
+HEADER
+  printf '        COMPREPLY=($(compgen -W "%s" -- "$cur"))\n' "$EDITORS"
+  cat <<'MIDDLE1'
+      else
+        local branches all_options
+        branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
+        all_options="1 $branches"
+        COMPREPLY=($(compgen -W "$all_options" -- "$cur"))
+      fi
+      ;;
+    ai)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "--ai" -- "$cur"))
+      elif [ "$prev" = "--ai" ]; then
+MIDDLE1
+  printf '        COMPREPLY=($(compgen -W "%s" -- "$cur"))\n' "$AI_TOOLS"
+  cat <<'MIDDLE2'
+      else
+        local branches all_options
+        branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
+        all_options="1 $branches"
+        COMPREPLY=($(compgen -W "$all_options" -- "$cur"))
+      fi
+      ;;
+    ls|list)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "--porcelain" -- "$cur"))
+      fi
+      ;;
+    clean)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "--merged --yes -y --dry-run -n" -- "$cur"))
+      fi
+      ;;
+    copy)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "-n --dry-run -a --all --from" -- "$cur"))
+      else
+        # Complete with branch names and special ID '1' for main repo
+        local branches all_options
+        branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
+        all_options="1 $branches"
+        COMPREPLY=($(compgen -W "$all_options" -- "$cur"))
+      fi
+      ;;
+    new)
+      # Complete flags
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "--from --from-current --track --no-copy --no-fetch --no-hooks --force --name --folder --yes --editor -e --ai -a" -- "$cur"))
+      elif [ "$prev" = "--track" ]; then
+        COMPREPLY=($(compgen -W "auto remote local none" -- "$cur"))
+      fi
+      ;;
+    completion|init)
+      # Complete with shell names
+      if [ "$cword" -eq 3 ]; then
+        COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur"))
+      fi
+      ;;
+    config)
+      # Find action by scanning all config args (handles flexible flag positioning)
+      local config_action=""
+      local i
+      for (( i=3; i < cword; i++ )); do
+        case "${words[i]}" in
+          list|get|set|add|unset) config_action="${words[i]}" ;;
+        esac
+      done
+
+      if [ -z "$config_action" ]; then
+        # Still need to complete action or scope
+        COMPREPLY=($(compgen -W "list get set add unset --local --global --system" -- "$cur"))
+      else
+        # Have action, complete based on it
+        case "$config_action" in
+          list|get)
+            # Read operations support all scopes including --system
+            if [[ "$cur" == -* ]]; then
+              COMPREPLY=($(compgen -W "--local --global --system" -- "$cur"))
+            else
+MIDDLE2
+  printf '              COMPREPLY=($(compgen -W "%s" -- "$cur"))\n' "$CONFIG_KEYS"
+  cat <<'MIDDLE3'
+            fi
+            ;;
+          set|add|unset)
+            # Write operations only support --local and --global (--system requires root)
+            if [[ "$cur" == -* ]]; then
+              COMPREPLY=($(compgen -W "--local --global" -- "$cur"))
+            else
+MIDDLE3
+  printf '              COMPREPLY=($(compgen -W "%s" -- "$cur"))\n' "$CONFIG_KEYS"
+  cat <<'FOOTER'
+            fi
+            ;;
+        esac
+      fi
+      ;;
+  esac
+}
+FOOTER
+}
+
+generate_zsh() {
+  cat <<'HEADER'
+#compdef _git-gtr git-gtr gtr
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
+# Zsh completion for git gtr (Git Worktree Runner)
+#
+# SETUP: For completions to work with `git gtr`, add this to ~/.zshrc
+# BEFORE any existing compinit call:
+#
+#   eval "$(git gtr completion zsh)"
+#
+# This registers gtr as a git subcommand and sets up the completion path.
+# Run `git gtr completion --help` for more details.
+#
+# WHY: Zsh needs to know `gtr` is a valid git subcommand BEFORE completion
+# triggers. The zstyle registration below only runs when this file is loaded,
+# but autoloading happens AFTER completion - a timing issue. The `completion`
+# command outputs the zstyle before compinit, solving this.
+
+_git-gtr() {
+  # Normalize invocation so we always see: [git, gtr, <command>, ...]
+  # Handles: `git gtr`, `gtr`, and `git-gtr` invocations
+  if [[ $words[1] != git ]]; then
+    # Handle both `gtr ...` and `git-gtr ...`
+    words=(git gtr "${words[@]:1}")
+    (( CURRENT += 1 ))
+  fi
+
+  local -a commands
+  commands=(
+    'new:Create a new worktree'
+    'go:Navigate to worktree'
+    'run:Execute command in worktree'
+    'copy:Copy files between worktrees'
+    'rm:Remove worktree(s)'
+    'mv:Rename worktree and branch'
+    'rename:Rename worktree and branch'
+    'editor:Open worktree in editor'
+    'ai:Start AI coding tool'
+    'ls:List all worktrees'
+    'list:List all worktrees'
+    'clean:Remove stale worktrees'
+    'doctor:Health check'
+    'adapter:List available adapters'
+    'config:Manage configuration'
+    'completion:Generate shell completions'
+    'init:Generate shell integration for cd support'
+    'version:Show version'
+    'help:Show help'
+  )
+
+  local -a branches all_options
+  # Get branch names
+  branches=(${(f)"$(git branch --format='%(refname:short)' 2>/dev/null)"})
+  # Add special ID '1' for main repo
+  all_options=("1" "${branches[@]}")
+
+  # Early handler for `new` command - handle all positions
+  if (( CURRENT >= 4 )) && [[ $words[3] == new ]]; then
+    _arguments \
+      '1:branch name:' \
+      '--from[Base ref]:ref:' \
+      '--from-current[Create from current branch]' \
+      '--track[Track mode]:mode:(auto remote local none)' \
+      '--no-copy[Skip file copying]' \
+      '--no-fetch[Skip git fetch]' \
+      '--no-hooks[Skip post-create hooks]' \
+      '--force[Allow same branch in multiple worktrees]' \
+      '--name[Custom folder name suffix]:name:' \
+      '--folder[Custom folder name (replaces default)]:folder:' \
+      '--yes[Non-interactive mode]' \
+      '--editor[Open in editor after creation]' \
+      '-e[Open in editor after creation]' \
+      '--ai[Start AI tool after creation]' \
+      '-a[Start AI tool after creation]'
+    return
+  fi
+
+  # Early handler for `clean` command
+  if (( CURRENT >= 4 )) && [[ $words[3] == clean ]]; then
+    _arguments \
+      '--merged[Remove worktrees with merged PRs/MRs]' \
+      '--yes[Skip confirmation prompts]' \
+      '-y[Skip confirmation prompts]' \
+      '--dry-run[Show what would be removed]' \
+      '-n[Show what would be removed]'
+    return
+  fi
+
+  # Early handler for `list/ls` command - add --porcelain
+  if (( CURRENT >= 4 )) && [[ $words[3] == (list|ls) ]]; then
+    _arguments '--porcelain[Machine-readable output]'
+    return
+  fi
+
+  # Complete the gtr subcommand (new, go, editor, etc.)
+  if (( CURRENT == 3 )); then
+    _describe 'commands' commands
+  # Complete arguments to the subcommand
+  elif (( CURRENT == 4 )); then
+    case "$words[3]" in
+      go|run|rm|mv|rename|copy)
+        _describe 'branch names' all_options
+        ;;
+      editor)
+        _describe 'branch names' all_options
+        ;;
+      ai)
+        _describe 'branch names' all_options
+        ;;
+      config)
+        # Complete action or scope flags
+        _values 'config action' list get set add unset --local --global --system
+        ;;
+      completion|init)
+        # Complete shell names
+        _values 'shell' bash zsh fish
+        ;;
+    esac
+  # Complete subsequent arguments
+  elif (( CURRENT >= 5 )); then
+    case "$words[3]" in
+      editor)
+HEADER
+  printf "        _arguments '--editor[Editor to use]:editor:(%s)'\n" "$EDITORS"
+  cat <<'MIDDLE1'
+        ;;
+      ai)
+MIDDLE1
+  printf "        _arguments '--ai[AI tool to use]:tool:(%s)'\n" "$AI_TOOLS"
+  cat <<'MIDDLE2'
+        ;;
+      rm)
+        _arguments \
+          '--delete-branch[Delete branch]' \
+          '--force[Force removal even if dirty]' \
+          '--yes[Non-interactive mode]'
+        ;;
+      mv|rename)
+        _arguments \
+          '--force[Force move even if locked]' \
+          '--yes[Skip confirmation]'
+        ;;
+      copy)
+        _arguments \
+          '-n[Dry-run preview]' \
+          '--dry-run[Preview without copying]' \
+          '-a[Copy to all worktrees]' \
+          '--all[Copy to all worktrees]' \
+          '--from[Source worktree]:source:->worktrees' \
+          '*:target:->worktrees'
+        case "$state" in
+          worktrees) _describe 'branch names' all_options ;;
+        esac
+        ;;
+      config)
+        # Find action by scanning all config args (handles flexible flag positioning)
+        # Use offset 3 to start from words[4] (first arg after 'config')
+        # Zsh uses 0-based offset: ${array[@]:3} = elements starting from 4th position
+        local config_action=""
+        local arg
+        for arg in "${words[@]:3}"; do
+          case "$arg" in
+            list|get|set|add|unset)
+              [[ -z "$config_action" ]] && config_action="$arg"
+              ;;
+          esac
+        done
+
+        if [[ -z "$config_action" ]]; then
+          # Still need action or scope
+          _values 'config action' list get set add unset --local --global --system
+        else
+          case "$config_action" in
+            list|get)
+              # Read operations support all scopes including --system
+              _arguments \
+                '--local[Use local git config]' \
+                '--global[Use global git config]' \
+                '--system[Use system git config]' \
+MIDDLE2
+  printf "                '*:config key:(%s)'\n" "$CONFIG_KEYS"
+  cat <<'MIDDLE3'
+              ;;
+            set|add|unset)
+              # Write operations only support --local and --global
+              # (--system may require root or appropriate file permissions)
+              _arguments \
+                '--local[Use local git config]' \
+                '--global[Use global git config]' \
+MIDDLE3
+  printf "                '*:config key:(%s)'\n" "$CONFIG_KEYS"
+  cat <<'FOOTER'
+              ;;
+          esac
+        fi
+        ;;
+    esac
+  fi
+}
+
+_git-gtr "$@"
+FOOTER
+}
+
+generate_fish() {
+  cat <<'HEADER'
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
+# Fish completion for git gtr
+#
+# This completion integrates with fish's completion system by registering completions
+# for the "git" command with custom predicates that detect "git gtr" usage.
+#
+# Installation:
+#   Symlink to fish's completions directory:
+#     ln -s /path/to/git-worktree-runner/completions/git-gtr.fish ~/.config/fish/completions/
+#   Then reload fish:
+#     exec fish
+
+# Helper function to check if we're in 'git gtr' context
+function __fish_git_gtr_needs_command
+  set -l cmd (commandline -opc)
+  if [ (count $cmd) -eq 2 -a "$cmd[1]" = "git" -a "$cmd[2]" = "gtr" ]
+    return 0
+  end
+  return 1
+end
+
+function __fish_git_gtr_using_command
+  set -l cmd (commandline -opc)
+  if [ (count $cmd) -ge 3 -a "$cmd[1]" = "git" -a "$cmd[2]" = "gtr" ]
+    for i in $argv
+      if [ "$cmd[3]" = "$i" ]
+        return 0
+      end
+    end
+  end
+  return 1
+end
+
+# Commands
+complete -f -c git -n '__fish_git_gtr_needs_command' -a new -d 'Create a new worktree'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a go -d 'Navigate to worktree'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a run -d 'Execute command in worktree'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a rm -d 'Remove worktree(s)'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a mv -d 'Rename worktree and branch'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a rename -d 'Rename worktree and branch'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a copy -d 'Copy files between worktrees'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a editor -d 'Open worktree in editor'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a ai -d 'Start AI coding tool'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a ls -d 'List all worktrees'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a list -d 'List all worktrees'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a clean -d 'Remove stale worktrees'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a doctor -d 'Health check'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a adapter -d 'List available adapters'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a config -d 'Manage configuration'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a completion -d 'Generate shell completions'
+complete -f -c git -n '__fish_git_gtr_using_command completion' -a 'bash zsh fish' -d 'Shell type'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a init -d 'Generate shell integration for cd support'
+complete -f -c git -n '__fish_git_gtr_using_command init' -a 'bash zsh fish' -d 'Shell type'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a version -d 'Show version'
+complete -f -c git -n '__fish_git_gtr_needs_command' -a help -d 'Show help'
+
+# New command options
+complete -c git -n '__fish_git_gtr_using_command new' -l from -d 'Base ref' -r
+complete -c git -n '__fish_git_gtr_using_command new' -l from-current -d 'Create from current branch'
+complete -c git -n '__fish_git_gtr_using_command new' -l track -d 'Track mode' -r -a 'auto remote local none'
+complete -c git -n '__fish_git_gtr_using_command new' -l no-copy -d 'Skip file copying'
+complete -c git -n '__fish_git_gtr_using_command new' -l no-fetch -d 'Skip git fetch'
+complete -c git -n '__fish_git_gtr_using_command new' -l no-hooks -d 'Skip post-create hooks'
+complete -c git -n '__fish_git_gtr_using_command new' -l force -d 'Allow same branch in multiple worktrees'
+complete -c git -n '__fish_git_gtr_using_command new' -l name -d 'Custom folder name suffix' -r
+complete -c git -n '__fish_git_gtr_using_command new' -l folder -d 'Custom folder name (replaces default)' -r
+complete -c git -n '__fish_git_gtr_using_command new' -l yes -d 'Non-interactive mode'
+complete -c git -n '__fish_git_gtr_using_command new' -s e -l editor -d 'Open in editor after creation'
+complete -c git -n '__fish_git_gtr_using_command new' -s a -l ai -d 'Start AI tool after creation'
+
+# Remove command options
+complete -c git -n '__fish_git_gtr_using_command rm' -l delete-branch -d 'Delete branch'
+complete -c git -n '__fish_git_gtr_using_command rm' -l force -d 'Force removal even if dirty'
+complete -c git -n '__fish_git_gtr_using_command rm' -l yes -d 'Non-interactive mode'
+
+# Rename command options
+complete -c git -n '__fish_git_gtr_using_command mv' -l force -d 'Force move even if locked'
+complete -c git -n '__fish_git_gtr_using_command mv' -l yes -d 'Skip confirmation'
+complete -c git -n '__fish_git_gtr_using_command rename' -l force -d 'Force move even if locked'
+complete -c git -n '__fish_git_gtr_using_command rename' -l yes -d 'Skip confirmation'
+
+# Copy command options
+complete -c git -n '__fish_git_gtr_using_command copy' -s n -l dry-run -d 'Preview without copying'
+complete -c git -n '__fish_git_gtr_using_command copy' -s a -l all -d 'Copy to all worktrees'
+complete -c git -n '__fish_git_gtr_using_command copy' -l from -d 'Source worktree' -r
+
+# List command options
+complete -c git -n '__fish_git_gtr_using_command list' -l porcelain -d 'Machine-readable output'
+complete -c git -n '__fish_git_gtr_using_command ls' -l porcelain -d 'Machine-readable output'
+
+# Editor command options
+HEADER
+  printf "complete -c git -n '__fish_git_gtr_using_command editor' -l editor -d 'Editor to use' -r -a '%s'\n" "$EDITORS"
+  cat <<'MIDDLE1'
+
+# AI command options
+MIDDLE1
+  printf "complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a '%s'\n" "$AI_TOOLS"
+  cat <<'MIDDLE2'
+
+# Clean command options
+complete -c git -n '__fish_git_gtr_using_command clean' -l merged -d 'Remove worktrees with merged PRs/MRs'
+complete -c git -n '__fish_git_gtr_using_command clean' -l yes -d 'Skip confirmation prompts'
+complete -c git -n '__fish_git_gtr_using_command clean' -s y -d 'Skip confirmation prompts'
+complete -c git -n '__fish_git_gtr_using_command clean' -l dry-run -d 'Show what would be removed'
+complete -c git -n '__fish_git_gtr_using_command clean' -s n -d 'Show what would be removed'
+
+# Config command
+complete -f -c git -n '__fish_git_gtr_using_command config' -a 'list get set add unset'
+
+# Helper to check if config action is a read operation (list or get)
+function __fish_git_gtr_config_is_read
+  set -l cmd (commandline -opc)
+  for i in $cmd
+    if test "$i" = "list" -o "$i" = "get"
+      return 0
+    end
+  end
+  return 1
+end
+
+# Helper to check if config action is a write operation (set, add, unset)
+function __fish_git_gtr_config_is_write
+  set -l cmd (commandline -opc)
+  for i in $cmd
+    if test "$i" = "set" -o "$i" = "add" -o "$i" = "unset"
+      return 0
+    end
+  end
+  return 1
+end
+
+# Scope flags for config command
+# --local and --global available for all operations
+complete -f -c git -n '__fish_git_gtr_using_command config' -l local -d 'Use local git config'
+complete -f -c git -n '__fish_git_gtr_using_command config' -l global -d 'Use global git config'
+# --system only for read operations (list, get) - write requires root
+complete -f -c git -n '__fish_git_gtr_using_command config; and __fish_git_gtr_config_is_read' -l system -d 'Use system git config'
+MIDDLE2
+
+  # Config keys with descriptions (fish-specific tab-separated format)
+  printf "complete -f -c git -n '__fish_git_gtr_using_command config' -a \"\n"
+  local key
+  for key in $CONFIG_KEYS; do
+    local desc
+    case "$key" in
+      gtr.worktrees.dir)    desc="Worktrees base directory" ;;
+      gtr.worktrees.prefix) desc="Worktree folder prefix" ;;
+      gtr.defaultBranch)    desc="Default branch" ;;
+      gtr.editor.default)   desc="Default editor" ;;
+      gtr.editor.workspace) desc="Path to workspace file (.code-workspace)" ;;
+      gtr.ai.default)       desc="Default AI tool" ;;
+      gtr.provider)         desc="Hosting provider (github, gitlab)" ;;
+      gtr.copy.include)     desc="Files to copy" ;;
+      gtr.copy.exclude)     desc="Files to exclude" ;;
+      gtr.copy.includeDirs) desc="Directories to copy (e.g., node_modules)" ;;
+      gtr.copy.excludeDirs) desc="Directories to exclude" ;;
+      gtr.hook.postCreate)  desc="Post-create hook" ;;
+      gtr.hook.preRemove)   desc="Pre-remove hook (abort on failure)" ;;
+      gtr.hook.postRemove)  desc="Post-remove hook" ;;
+      gtr.hook.postCd)      desc="Post-cd hook (shell integration only)" ;;
+      *)                    desc="$key" ;;
+    esac
+    printf "  %s\t'%s'\n" "$key" "$desc"
+  done
+  printf "\"\n"
+
+  cat <<'FOOTER'
+
+# Helper function to get branch names and special '1' for main repo
+function __gtr_worktree_branches
+  # Special ID for main repo
+  echo '1'
+  # Get branch names
+  git branch --format='%(refname:short)' 2>/dev/null
+end
+
+# Complete branch names for commands that need them
+complete -f -c git -n '__fish_git_gtr_using_command go' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command run' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command copy' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command editor' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command ai' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command rm' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command mv' -a '(__gtr_worktree_branches)'
+complete -f -c git -n '__fish_git_gtr_using_command rename' -a '(__gtr_worktree_branches)'
+FOOTER
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+if [ "${1:-}" = "--check" ]; then
+  tmpdir=$(mktemp -d)
+  trap 'rm -rf "$tmpdir"' EXIT
+
+  generate_bash > "$tmpdir/gtr.bash"
+  generate_zsh > "$tmpdir/_git-gtr"
+  generate_fish > "$tmpdir/git-gtr.fish"
+
+  stale=0
+  for file in gtr.bash _git-gtr git-gtr.fish; do
+    if ! diff -q "$SCRIPT_DIR/completions/$file" "$tmpdir/$file" >/dev/null 2>&1; then
+      echo "STALE: completions/$file" >&2
+      diff -u "$SCRIPT_DIR/completions/$file" "$tmpdir/$file" >&2 || true
+      stale=1
+    fi
+  done
+
+  if [ "$stale" -eq 1 ]; then
+    echo "" >&2
+    echo "Run ./scripts/generate-completions.sh to update" >&2
+    exit 1
+  fi
+  echo "All completion files are up to date"
+  exit 0
+fi
+
+# Generate and write completion files
+generate_bash > "$SCRIPT_DIR/completions/gtr.bash"
+generate_zsh  > "$SCRIPT_DIR/completions/_git-gtr"
+generate_fish > "$SCRIPT_DIR/completions/git-gtr.fish"
+
+echo "Generated completion files:"
+echo "  completions/gtr.bash"
+echo "  completions/_git-gtr"
+echo "  completions/git-gtr.fish"
diff --git a/tests/integration_lifecycle.bats b/tests/integration_lifecycle.bats
new file mode 100644
index 0000000..c0e19e1
--- /dev/null
+++ b/tests/integration_lifecycle.bats
@@ -0,0 +1,118 @@
+#!/usr/bin/env bats
+# Integration tests for the core worktree lifecycle: create → list → resolve → remove
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_libs
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+@test "create_worktree produces expected directory" {
+  local default_branch
+  default_branch=$(git rev-parse --abbrev-ref HEAD)
+  local base_dir="${TEST_REPO}-worktrees"
+
+  local wt_path
+  wt_path=$(create_worktree "$base_dir" "" "test-feature" "$default_branch" "auto" "1" "0" "" "")
+  [ -d "$wt_path" ]
+
+  # Verify branch in worktree matches
+  local branch
+  branch=$(git -C "$wt_path" rev-parse --abbrev-ref HEAD)
+  [ "$branch" = "test-feature" ]
+}
+
+@test "list_worktree_branches shows created worktree" {
+  local default_branch
+  default_branch=$(git rev-parse --abbrev-ref HEAD)
+  local base_dir="${TEST_REPO}-worktrees"
+
+  create_worktree "$base_dir" "" "test-list" "$default_branch" "auto" "1" "0" "" "" >/dev/null
+  local branches
+  branches=$(list_worktree_branches "$base_dir" "")
+  [[ "$branches" == *"test-list"* ]]
+}
+
+@test "resolve_target finds worktree by branch name" {
+  local default_branch
+  default_branch=$(git rev-parse --abbrev-ref HEAD)
+  local base_dir="${TEST_REPO}-worktrees"
+
+  create_worktree "$base_dir" "" "find-me" "$default_branch" "auto" "1" "0" "" "" >/dev/null
+
+  local result
+  result=$(resolve_target "find-me" "$TEST_REPO" "$base_dir" "")
+  unpack_target "$result"
+  [ "$_ctx_is_main" = "0" ]
+  [ "$_ctx_branch" = "find-me" ]
+  [ -d "$_ctx_worktree_path" ]
+}
+
+@test "resolve_target ID 1 returns main repo" {
+  local base_dir="${TEST_REPO}-worktrees"
+  local result
+  result=$(resolve_target "1" "$TEST_REPO" "$base_dir" "")
+  unpack_target "$result"
+  [ "$_ctx_is_main" = "1" ]
+  [ "$_ctx_worktree_path" = "$TEST_REPO" ]
+}
+
+@test "resolve_target handles slashed branch names" {
+  local default_branch
+  default_branch=$(git rev-parse --abbrev-ref HEAD)
+  local base_dir="${TEST_REPO}-worktrees"
+
+  create_worktree "$base_dir" "" "feature/auth" "$default_branch" "auto" "1" "0" "" "" >/dev/null
+
+  local result
+  result=$(resolve_target "feature/auth" "$TEST_REPO" "$base_dir" "")
+  unpack_target "$result"
+  [ "$_ctx_is_main" = "0" ]
+  [ "$_ctx_branch" = "feature/auth" ]
+  # Directory name should be sanitized (slashes → hyphens)
+  [[ "$_ctx_worktree_path" == *"feature-auth"* ]]
+}
+
+@test "remove_worktree deletes directory" {
+  local default_branch
+  default_branch=$(git rev-parse --abbrev-ref HEAD)
+  local base_dir="${TEST_REPO}-worktrees"
+
+  local wt_path
+  wt_path=$(create_worktree "$base_dir" "" "to-remove" "$default_branch" "auto" "1" "0" "" "")
+  [ -d "$wt_path" ]
+
+  remove_worktree "$wt_path" "0"
+  [ ! -d "$wt_path" ]
+}
+
+@test "full lifecycle: create → resolve → remove" {
+  local default_branch
+  default_branch=$(git rev-parse --abbrev-ref HEAD)
+  local base_dir="${TEST_REPO}-worktrees"
+
+  # Create
+  local wt_path
+  wt_path=$(create_worktree "$base_dir" "" "lifecycle" "$default_branch" "auto" "1" "0" "" "")
+  [ -d "$wt_path" ]
+
+  # Resolve
+  local result
+  result=$(resolve_target "lifecycle" "$TEST_REPO" "$base_dir" "")
+  unpack_target "$result"
+  [ "$_ctx_is_main" = "0" ]
+  [ "$_ctx_worktree_path" = "$wt_path" ]
+
+  # Remove
+  remove_worktree "$wt_path" "0"
+  [ ! -d "$wt_path" ]
+
+  # Verify resolve fails after removal
+  run resolve_target "lifecycle" "$TEST_REPO" "$base_dir" ""
+  [ "$status" -ne 0 ]
+}
diff --git a/tests/parse_args.bats b/tests/parse_args.bats
new file mode 100644
index 0000000..506c787
--- /dev/null
+++ b/tests/parse_args.bats
@@ -0,0 +1,96 @@
+#!/usr/bin/env bats
+# Tests for the shared argument parser (lib/args.sh)
+
+load test_helper
+
+setup() {
+  source "$PROJECT_ROOT/lib/args.sh"
+}
+
+@test "boolean flag sets _arg variable to 1" {
+  parse_args "--force" --force
+  [ "$_arg_force" = "1" ]
+}
+
+@test "value flag sets _arg variable to the value" {
+  parse_args "--from: value" --from origin/main
+  [ "$_arg_from" = "origin/main" ]
+}
+
+@test "short alias maps to same variable as long form" {
+  parse_args "--dry-run|-n" -n
+  [ "$_arg_dry_run" = "1" ]
+}
+
+@test "long form also works with alias spec" {
+  parse_args "--dry-run|-n" --dry-run
+  [ "$_arg_dry_run" = "1" ]
+}
+
+@test "positional args collected in _pa_positional" {
+  parse_args "--force" my-branch --force
+  [ "${_pa_positional[0]}" = "my-branch" ]
+  [ "$_arg_force" = "1" ]
+}
+
+@test "multiple positional args collected in order" {
+  parse_args "" foo bar baz
+  [ ${#_pa_positional[@]} -eq 3 ]
+  [ "${_pa_positional[0]}" = "foo" ]
+  [ "${_pa_positional[1]}" = "bar" ]
+  [ "${_pa_positional[2]}" = "baz" ]
+}
+
+@test "-- stops parsing and collects passthrough args" {
+  parse_args "--ai: value" my-branch --ai claude -- --verbose --model opus
+  [ "${_pa_positional[0]}" = "my-branch" ]
+  [ "$_arg_ai" = "claude" ]
+  [ ${#_pa_passthrough[@]} -eq 3 ]
+  [ "${_pa_passthrough[0]}" = "--verbose" ]
+  [ "${_pa_passthrough[1]}" = "--model" ]
+  [ "${_pa_passthrough[2]}" = "opus" ]
+}
+
+@test "unknown flag exits with error" {
+  run parse_args "--force" --badarg
+  [ "$status" -eq 1 ]
+}
+
+@test "empty spec still rejects unknown flags" {
+  run parse_args "" --something
+  [ "$status" -eq 1 ]
+}
+
+@test "hyphens in flag names become underscores in variable" {
+  parse_args "--from-current" --from-current
+  [ "$_arg_from_current" = "1" ]
+}
+
+@test "multiline spec with mixed flag types" {
+  local spec
+  spec="--from: value
+--from-current
+--no-copy
+--editor|-e"
+  parse_args "$spec" --from main --no-copy -e my-branch
+
+  [ "$_arg_from" = "main" ]
+  [ "$_arg_from_current" = "" ]
+  [ "$_arg_no_copy" = "1" ]
+  [ "$_arg_editor" = "1" ]
+  [ "${_pa_positional[0]}" = "my-branch" ]
+}
+
+@test "flags without values are reset to empty on each parse" {
+  parse_args "--force" --force
+  [ "$_arg_force" = "1" ]
+
+  # Parse again without the flag
+  parse_args "--force" my-branch
+  [ "$_arg_force" = "" ]
+}
+
+@test "value flag without argument exits with error" {
+  run parse_args "--from: value" --from
+  [ "$status" -eq 1 ]
+}
diff --git a/tests/test_helper.bash b/tests/test_helper.bash
index e7a1ffe..0c1d264 100644
--- a/tests/test_helper.bash
+++ b/tests/test_helper.bash
@@ -9,9 +9,67 @@ log_info() { :; }
 log_warn() { :; }
 log_error() { :; }
 log_step() { :; }
-export -f log_info log_warn log_error log_step
+# show_command_help is called by parse_args on -h/--help — stub exits 0
+show_command_help() { exit 0; }
+export -f log_info log_warn log_error log_step show_command_help
 
 # Stubs for config.sh functions (tests that need real config should source it explicitly)
 cfg_default() { printf "%s" "${3:-}"; }
 cfg_get_all() { :; }
 export -f cfg_default cfg_get_all
+
+# ── Integration test helpers ─────────────────────────────────────────────────
+
+# Set up a disposable git repo for integration tests
+# Sets: TEST_REPO, TEST_WORKTREES_DIR
+setup_integration_repo() {
+  TEST_REPO=$(mktemp -d)
+  TEST_WORKTREES_DIR="${TEST_REPO}-worktrees"
+  git -C "$TEST_REPO" init --quiet
+  git -C "$TEST_REPO" config user.name "Test User"
+  git -C "$TEST_REPO" config user.email "test@example.com"
+  git -C "$TEST_REPO" commit --allow-empty -m "init" --quiet
+  export GTR_DIR="$PROJECT_ROOT"
+  cd "$TEST_REPO" || return 1
+}
+
+# Clean up: remove worktrees first, then temp dirs
+teardown_integration_repo() {
+  cd / 2>/dev/null || true
+  if [ -d "$TEST_REPO" ]; then
+    # Remove worktrees properly before deleting
+    git -C "$TEST_REPO" worktree list --porcelain 2>/dev/null | while IFS= read -r line; do
+      case "$line" in
+        "worktree "*)
+          local wt_path="${line#worktree }"
+          [ "$wt_path" = "$TEST_REPO" ] && continue
+          git -C "$TEST_REPO" worktree remove --force "$wt_path" 2>/dev/null || true
+          ;;
+      esac
+    done
+    rm -rf "$TEST_REPO" "$TEST_WORKTREES_DIR"
+  fi
+}
+
+# Source the full library chain (without running main)
+source_gtr_libs() {
+  export GTR_DIR="$PROJECT_ROOT"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/ui.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/args.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/config.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/platform.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/core.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/copy.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/hooks.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/provider.sh"
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/adapters.sh"
+}

From 8a8d7bebe3eafbb769f011ca148a7fd72711842e Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 17:40:10 -0800
Subject: [PATCH 12/19] fix: use prefix variable in doctor to resolve
 ShellCheck SC2034

---
 lib/commands/doctor.sh | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/commands/doctor.sh b/lib/commands/doctor.sh
index e435ce4..98aa624 100644
--- a/lib/commands/doctor.sh
+++ b/lib/commands/doctor.sh
@@ -38,6 +38,9 @@ cmd_doctor() {
     else
       echo "[i] Worktrees directory: $base_dir (not created yet)"
     fi
+    if [ -n "$prefix" ]; then
+      echo "[i] Worktree prefix: $prefix"
+    fi
   else
     echo "[x] Not in a git repository"
     issues=$((issues + 1))

From 847965ede42f5f7cd2e8ad43caeff85fd4da605d Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 17:56:52 -0800
Subject: [PATCH 13/19] refactor: enhance adapter and configuration management

- Updated `lib/adapters.sh` to improve documentation and structure for editor and AI tool registries, clarifying the format and loading process.
- Introduced new helper functions in `lib/config.sh` for deduplicating and formatting configuration entries, enhancing the `cfg_list` functionality.
- Added tests for adapter and configuration functionalities in `tests/adapters.bats` and `tests/config.bats`, ensuring robust validation of registry lookups and configuration mappings.
- Improved error handling and output formatting in the configuration listing process, streamlining user interaction and enhancing clarity.
---
 lib/adapters.sh     |  29 ++++++--
 lib/config.sh       | 160 +++++++++++++++++++++-----------------------
 lib/copy.sh         | 143 +++++++++++++++++----------------------
 lib/core.sh         | 107 +++++++++++++++--------------
 tests/adapters.bats | 112 +++++++++++++++++++++++++++++++
 tests/config.bats   | 127 +++++++++++++++++++++++++++++++++++
 tests/provider.bats |  54 +++++++++++++++
 7 files changed, 509 insertions(+), 223 deletions(-)
 create mode 100644 tests/adapters.bats
 create mode 100644 tests/config.bats
 create mode 100644 tests/provider.bats

diff --git a/lib/adapters.sh b/lib/adapters.sh
index 9d59757..d40ca36 100644
--- a/lib/adapters.sh
+++ b/lib/adapters.sh
@@ -2,10 +2,20 @@
 # Adapter loading infrastructure — registries, builders, generic fallbacks, and loaders
 # shellcheck disable=SC2329 # Functions defined inside adapter builders are invoked indirectly
 
-# Adapter registries — declarative definitions for standard adapters
-# Custom adapters (nano, claude, cursor-ai) remain as override files in adapters/
-# Format — editor: name|cmd|type|err_msg|flags (comma-separated: workspace, background)
-# Format — ai:     name|cmd|err_msg|info_lines (semicolon-separated)
+# ── Editor Registry ────────────────────────────────────────────────────
+# Declarative definitions for standard editor adapters.
+# Custom adapters (nano) remain as override files in adapters/editor/.
+#
+# Format: name|cmd|type|err_msg|flags
+#   name    — adapter name (used in --editor flag, config, completions)
+#   cmd     — executable to check/invoke (must be in PATH)
+#   type    — "standard" (GUI, opens directory) or "terminal" (runs in current tty)
+#   err_msg — user-facing message when cmd is not found
+#   flags   — comma-separated modifiers (optional):
+#               "workspace" — pass .code-workspace file instead of directory
+#               "background" — launch with & (for terminal editors that fork)
+#
+# Loading: file override (adapters/editor/<name>.sh) → registry → generic PATH fallback
 _EDITOR_REGISTRY="
 atom|atom|standard|Atom not found. Install from https://atom.io|
 cursor|cursor|standard|Cursor not found. Install from https://cursor.com or enable the shell command.|workspace
@@ -20,6 +30,17 @@ webstorm|webstorm|standard|WebStorm 'webstorm' command not found. Enable shell l
 zed|zed|standard|Zed not found. Install from https://zed.dev|
 "
 
+# ── AI Tool Registry ──────────────────────────────────────────────────
+# Declarative definitions for standard AI coding tool adapters.
+# Custom adapters (claude, cursor) remain as override files in adapters/ai/.
+#
+# Format: name|cmd|err_msg|info_lines
+#   name       — adapter name (used in --ai flag, config, completions)
+#   cmd        — executable to check/invoke (must be in PATH)
+#   err_msg    — user-facing message when cmd is not found
+#   info_lines — semicolon-separated additional help lines shown on error
+#
+# Loading: file override (adapters/ai/<name>.sh) → registry → generic PATH fallback
 _AI_REGISTRY="
 aider|aider|Aider not found. Install with: pip install aider-chat|See https://aider.chat for more information
 auggie|auggie|Auggie CLI not found. Install with: npm install -g @augmentcode/auggie|See https://www.augmentcode.com/product/CLI for more information
diff --git a/lib/config.sh b/lib/config.sh
index 3ba06e4..369304d 100644
--- a/lib/config.sh
+++ b/lib/config.sh
@@ -239,6 +239,79 @@ cfg_unset() {
   git config $flag --unset-all "$1" 2>/dev/null || true
 }
 
+# ── cfg_list helpers ──────────────────────────────────────────────────
+# Module-level state for cfg_list auto-mode deduplication.
+# Reset by cfg_list() at the start of each "auto" invocation.
+_cfg_list_seen=""
+_cfg_list_result=""
+
+# Add a config entry, deduplicating by key+value combo.
+# Uses Unit Separator ($'\x1f') as delimiter to avoid collision with any value content.
+# Usage: _cfg_list_add_entry <origin> <key> <value>
+_cfg_list_add_entry() {
+  local origin="$1" entry_key="$2" entry_value="$3"
+  local id=$'\x1f'"${entry_key}=${entry_value}"$'\x1f'
+
+  # Use [[ ]] for literal string matching (no glob interpretation)
+  if [[ "$_cfg_list_seen" == *"$id"* ]]; then
+    return 0
+  fi
+
+  _cfg_list_seen="${_cfg_list_seen}${id}"
+  _cfg_list_result="${_cfg_list_result}${entry_key}"$'\x1f'"${entry_value}"$'\x1f'"${origin}"$'\n'
+}
+
+# Parse git config --get-regexp output and add each entry with an origin label.
+# Usage: _cfg_list_parse_entries <origin> <get-regexp-output>
+_cfg_list_parse_entries() {
+  local origin="$1" entries="$2"
+  local line key value
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    key="${line%% *}"
+    if [[ "$line" == *" "* ]]; then
+      value="${line#* }"
+    else
+      value=""
+    fi
+    _cfg_list_add_entry "$origin" "$key" "$value"
+  done <<< "$entries"
+}
+
+# Format cfg_list output with alignment.
+# Detects auto-mode (Unit Separator delimited with origin) vs scoped (space delimited).
+# Usage: _cfg_list_format <output>
+_cfg_list_format() {
+  local output="$1"
+  if [ -z "$output" ]; then
+    echo "No gtr configuration found"
+    return 0
+  fi
+
+  printf '%s\n' "$output" | while IFS= read -r line; do
+    [ -z "$line" ] && continue
+
+    local key value origin rest
+    if [[ "$line" == *$'\x1f'* ]]; then
+      # Auto-mode format: key<US>value<US>origin
+      key="${line%%$'\x1f'*}"
+      rest="${line#*$'\x1f'}"
+      value="${rest%%$'\x1f'*}"
+      origin="${rest#*$'\x1f'}"
+      printf "%-35s = %-25s [%s]\n" "$key" "$value" "$origin"
+    else
+      # Scoped format: key value (no origin)
+      key="${line%% *}"
+      if [[ "$line" == *" "* ]]; then
+        value="${line#* }"
+      else
+        value=""
+      fi
+      printf "%-35s = %s\n" "$key" "$value"
+    fi
+  done
+}
+
 # List all gtr.* config values
 # Usage: cfg_list [scope]
 # scope: auto (default), local, global, system
@@ -262,52 +335,11 @@ cfg_list() {
       output=$(git config --system --get-regexp '^gtr\.' 2>/dev/null || true)
       ;;
     auto)
-      # Merge all sources with origin labels
-      # Deduplicates by key+value combo, preserving all multi-values from highest priority source
-      local seen_keys=""
-      local result=""
+      # Reset module-level state for this invocation
+      _cfg_list_seen=""
+      _cfg_list_result=""
       local key value line
 
-      # Set up cleanup trap for helper functions (protects against early exit/return)
-      trap 'unset -f _cfg_list_add_entry _cfg_list_parse_entries 2>/dev/null' RETURN
-
-      # Helper function to add entries with origin (inline to avoid Bash 3.2 nameref issues)
-      # Uses Unit Separator ($'\x1f') as delimiter to avoid conflicts with any values
-      _cfg_list_add_entry() {
-        local origin="$1"
-        local entry_key="$2"
-        local entry_value="$3"
-
-        # For multi-valued keys: check if key+value combo already seen
-        # This allows multiple values for the same key from the same source
-        # Use Unit Separator as delimiter in seen_keys to avoid collision with any value content
-        local id=$'\x1f'"${entry_key}=${entry_value}"$'\x1f'
-        # Use [[ ]] for literal string matching (no glob interpretation)
-        if [[ "$seen_keys" == *"$id"* ]]; then
-          return 0
-        fi
-
-        seen_keys="${seen_keys}${id}"
-        # Use Unit Separator ($'\x1f') as delimiter - won't appear in normal values
-        result="${result}${entry_key}"$'\x1f'"${entry_value}"$'\x1f'"${origin}"$'\n'
-      }
-
-      # Parse get-regexp output and add each entry with an origin label
-      _cfg_list_parse_entries() {
-        local origin="$1"
-        local entries="$2"
-        while IFS= read -r line; do
-          [ -z "$line" ] && continue
-          key="${line%% *}"
-          if [[ "$line" == *" "* ]]; then
-            value="${line#* }"
-          else
-            value=""
-          fi
-          _cfg_list_add_entry "$origin" "$key" "$value"
-        done <<< "$entries"
-      }
-
       # Process in priority order: local > .gtrconfig > global > system
       _cfg_list_parse_entries "local" \
         "$(git config --local --get-regexp '^gtr\.' 2>/dev/null || true)"
@@ -334,52 +366,16 @@ cfg_list() {
       _cfg_list_parse_entries "system" \
         "$(git config --system --get-regexp '^gtr\.' 2>/dev/null || true)"
 
-      # Clean up helper functions and clear trap (trap handles early exit cases)
-      unset -f _cfg_list_add_entry _cfg_list_parse_entries
-      trap - RETURN
-
-      output="$result"
+      output="$_cfg_list_result"
       ;;
     *)
-      # Unknown scope - warn and fall back to auto
       log_warn "Unknown scope '$scope', using 'auto'"
       cfg_list "auto"
       return $?
       ;;
   esac
 
-  # Format and display output
-  if [ -z "$output" ]; then
-    echo "No gtr configuration found"
-    return 0
-  fi
-
-  # Format output with alignment
-  # Use printf '%s\n' instead of echo for safety with special characters
-  printf '%s\n' "$output" | while IFS= read -r line; do
-    [ -z "$line" ] && continue
-
-    local key value origin rest
-    # Check if line uses Unit Separator delimiter (auto mode with origin)
-    if [[ "$line" == *$'\x1f'* ]]; then
-      # Format: key<US>value<US>origin
-      key="${line%%$'\x1f'*}"
-      rest="${line#*$'\x1f'}"
-      value="${rest%%$'\x1f'*}"
-      origin="${rest#*$'\x1f'}"
-      printf "%-35s = %-25s [%s]\n" "$key" "$value" "$origin"
-    else
-      # Format: key value (no origin, for scoped queries)
-      key="${line%% *}"
-      # Handle empty values (no space in line means value is empty)
-      if [[ "$line" == *" "* ]]; then
-        value="${line#* }"
-      else
-        value=""
-      fi
-      printf "%-35s = %s\n" "$key" "$value"
-    fi
-  done
+  _cfg_list_format "$output"
 }
 
 # Get config value with environment variable fallback
diff --git a/lib/copy.sh b/lib/copy.sh
index 2cf9363..0543139 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -208,6 +208,65 @@ EOF
   return 0
 }
 
+# Remove excluded subdirectories from a copied directory.
+# Supports patterns like "node_modules/.cache", "*/.cache", "node_modules/*", "*/.*"
+# Usage: _apply_directory_excludes <dest_parent> <dir_path> <excludes>
+_apply_directory_excludes() {
+  local dest_parent="$1" dir_path="$2" excludes="$3"
+
+  [ -z "$excludes" ] && return 0
+
+  local exclude_pattern
+  while IFS= read -r exclude_pattern; do
+    [ -z "$exclude_pattern" ] && continue
+
+    if _is_unsafe_path "$exclude_pattern"; then
+      log_warn "Skipping unsafe exclude pattern: $exclude_pattern"
+      continue
+    fi
+
+    # Only process patterns with directory separators
+    case "$exclude_pattern" in
+      */*)
+        local pattern_prefix="${exclude_pattern%%/*}"
+        local pattern_suffix="${exclude_pattern#*/}"
+
+        # Intentional glob pattern matching for directory prefix
+        # shellcheck disable=SC2254
+        case "$dir_path" in
+          $pattern_prefix)
+            local exclude_old_pwd
+            exclude_old_pwd=$(pwd)
+            cd "$dest_parent/$dir_path" 2>/dev/null || continue
+
+            local exclude_shopt_save
+            exclude_shopt_save="$(shopt -p dotglob 2>/dev/null || true)"
+            shopt -s dotglob 2>/dev/null || true
+
+            local removed_any=0
+            for matched_path in $pattern_suffix; do
+              if [ -e "$matched_path" ]; then
+                if rm -rf "$matched_path" 2>/dev/null; then
+                  removed_any=1
+                fi
+              fi
+            done
+
+            eval "$exclude_shopt_save" 2>/dev/null || true
+            cd "$exclude_old_pwd" || true
+
+            if [ "$removed_any" -eq 1 ]; then
+              log_info "Excluded subdirectory $exclude_pattern"
+            fi
+            ;;
+        esac
+        ;;
+    esac
+  done <<EOF
+$excludes
+EOF
+}
+
 # Copy directories matching patterns (typically git-ignored directories like node_modules)
 # Usage: copy_directories src_root dst_root dir_patterns excludes
 # dir_patterns: newline-separated directory names to copy (e.g., "node_modules", ".venv")
@@ -224,18 +283,15 @@ copy_directories() {
     return 0
   fi
 
-  # Change to source directory
   local old_pwd
   old_pwd=$(pwd)
   cd "$src_root" || return 1
 
   local copied_count=0
 
-  # Process each directory pattern
   while IFS= read -r pattern; do
     [ -z "$pattern" ] && continue
 
-    # Security: reject absolute paths and parent directory traversal
     if _is_unsafe_path "$pattern"; then
       log_warn "Skipping unsafe pattern: $pattern"
       continue
@@ -245,100 +301,21 @@ copy_directories() {
     # Use -path for patterns with slashes (e.g., vendor/bundle), -name for basenames
     while IFS= read -r dir_path; do
       [ -z "$dir_path" ] && continue
-
-      # Remove leading ./
       dir_path="${dir_path#./}"
 
-      # Skip if excluded
       is_excluded "$dir_path" "$excludes" && continue
-
-      # Ensure source directory exists
       [ ! -d "$dir_path" ] && continue
 
-      # Determine destination
       local dest_dir="$dst_root/$dir_path"
       local dest_parent
       dest_parent=$(dirname "$dest_dir")
-
-      # Create parent directory
       mkdir -p "$dest_parent"
 
       # Copy directory (cp -RP preserves symlinks as symlinks)
       if cp -RP "$dir_path" "$dest_parent/" 2>/dev/null; then
         log_info "Copied directory $dir_path"
         copied_count=$((copied_count + 1))
-
-        # Remove excluded subdirectories after copying
-        if [ -n "$excludes" ]; then
-          while IFS= read -r exclude_pattern; do
-            [ -z "$exclude_pattern" ] && continue
-
-            # Security: reject absolute paths and parent directory traversal in excludes
-            if _is_unsafe_path "$exclude_pattern"; then
-              log_warn "Skipping unsafe exclude pattern: $exclude_pattern"
-              continue
-            fi
-
-            # Check if pattern applies to this copied directory
-            # Supports patterns like:
-            #   "node_modules/.cache" - exact path
-            #   "*/.cache" - wildcard prefix (matches any directory)
-            #   "node_modules/*" - wildcard suffix (matches all subdirectories)
-            #   "*/.*" - both (matches all hidden subdirectories in any directory)
-
-            # Only process patterns with directory separators
-            case "$exclude_pattern" in
-              */*)
-                # Extract prefix (before first /) and suffix (after first /)
-                local pattern_prefix="${exclude_pattern%%/*}"
-                local pattern_suffix="${exclude_pattern#*/}"
-
-                # Check if our copied directory matches the prefix pattern
-                # Intentional glob pattern matching for directory prefix
-                # shellcheck disable=SC2254
-                case "$dir_path" in
-                  $pattern_prefix)
-                    # Match! Remove matching subdirectories using suffix pattern
-
-                    # Save current directory
-                    local exclude_old_pwd
-                    exclude_old_pwd=$(pwd)
-
-                    # Change to destination directory for glob expansion
-                    cd "$dest_parent/$dir_path" 2>/dev/null || continue
-
-                    # Enable dotglob to match hidden files with wildcards
-                    local exclude_shopt_save
-                    exclude_shopt_save="$(shopt -p dotglob 2>/dev/null || true)"
-                    shopt -s dotglob 2>/dev/null || true
-
-                    # Expand glob pattern and remove matched paths
-                    local removed_any=0
-                    for matched_path in $pattern_suffix; do
-                      # Check if glob matched anything (avoid literal pattern if no match)
-                      if [ -e "$matched_path" ]; then
-                        if rm -rf "$matched_path" 2>/dev/null; then
-                          removed_any=1
-                        fi
-                      fi
-                    done
-
-                    # Restore shell options and directory
-                    eval "$exclude_shopt_save" 2>/dev/null || true
-                    cd "$exclude_old_pwd" || true
-
-                    # Log only if we actually removed something
-                    if [ "$removed_any" -eq 1 ]; then
-                      log_info "Excluded subdirectory $exclude_pattern"
-                    fi
-                    ;;
-                esac
-                ;;
-            esac
-          done <<EOF
-$excludes
-EOF
-        fi
+        _apply_directory_excludes "$dest_parent" "$dir_path" "$excludes"
       else
         log_warn "Failed to copy directory $dir_path"
       fi
diff --git a/lib/core.sh b/lib/core.sh
index d60b8d3..8455637 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -306,6 +306,25 @@ resolve_worktree() {
   unpack_target "$target"
 }
 
+# Try to create a worktree, handling the common log/add/report pattern.
+# Usage: _try_worktree_add <path> <step_msg> <ok_msg> <force_flag> [git_worktree_add_args...]
+# Prints worktree path on success; returns 1 on failure (caller handles error).
+# Note: step_msg may be empty to skip the log_step call.
+_try_worktree_add() {
+  local wt_path="$1" step_msg="$2" ok_msg="$3" force_flag="$4"
+  shift 4
+
+  [ -n "$step_msg" ] && log_step "$step_msg"
+
+  # shellcheck disable=SC2086
+  if git worktree add $force_flag "$wt_path" "$@" >&2; then
+    log_info "$ok_msg"
+    printf "%s" "$wt_path"
+    return 0
+  fi
+  return 1
+}
+
 # Create a new git worktree
 # Usage: create_worktree base_dir prefix branch_name from_ref track_mode [skip_fetch] [force] [custom_name] [folder_override]
 # track_mode: auto, remote, local, or none
@@ -374,80 +393,60 @@ create_worktree() {
 
   case "$track_mode" in
     remote)
-      # Force use of remote branch
       if [ "$remote_exists" -eq 1 ]; then
-        log_step "Creating worktree from remote branch origin/$branch_name"
-        if git worktree add $force_flag "$worktree_path" -b "$branch_name" "origin/$branch_name" >&2 || \
-           git worktree add $force_flag "$worktree_path" "$branch_name" >&2; then
-          log_info "Worktree created tracking origin/$branch_name"
-          printf "%s" "$worktree_path"
-          return 0
-        fi
-      else
-        log_error "Remote branch origin/$branch_name does not exist"
-        return 1
+        # Try creating with -b first (new local branch tracking remote), fallback to direct checkout
+        _try_worktree_add "$worktree_path" \
+          "Creating worktree from remote branch origin/$branch_name" \
+          "Worktree created tracking origin/$branch_name" \
+          "$force_flag" -b "$branch_name" "origin/$branch_name" && return 0
+        _try_worktree_add "$worktree_path" "" \
+          "Worktree created tracking origin/$branch_name" \
+          "$force_flag" "$branch_name" && return 0
       fi
+      log_error "Remote branch origin/$branch_name does not exist"
+      return 1
       ;;
 
     local)
-      # Force use of local branch
       if [ "$local_exists" -eq 1 ]; then
-        log_step "Creating worktree from local branch $branch_name"
-        if git worktree add $force_flag "$worktree_path" "$branch_name" >&2; then
-          log_info "Worktree created with local branch $branch_name"
-          printf "%s" "$worktree_path"
-          return 0
-        fi
-      else
-        log_error "Local branch $branch_name does not exist"
-        return 1
+        _try_worktree_add "$worktree_path" \
+          "Creating worktree from local branch $branch_name" \
+          "Worktree created with local branch $branch_name" \
+          "$force_flag" "$branch_name" && return 0
       fi
+      log_error "Local branch $branch_name does not exist"
+      return 1
       ;;
 
     none)
-      # Create new branch from from_ref
-      log_step "Creating new branch $branch_name from $from_ref"
-      if git worktree add $force_flag "$worktree_path" -b "$branch_name" "$from_ref" >&2; then
-        log_info "Worktree created with new branch $branch_name"
-        printf "%s" "$worktree_path"
-        return 0
-      else
-        log_error "Failed to create worktree with new branch"
-        return 1
-      fi
+      _try_worktree_add "$worktree_path" \
+        "Creating new branch $branch_name from $from_ref" \
+        "Worktree created with new branch $branch_name" \
+        "$force_flag" -b "$branch_name" "$from_ref" && return 0
+      log_error "Failed to create worktree with new branch"
+      return 1
       ;;
 
     auto|*)
-      # Auto-detect best option with proper tracking
       if [ "$remote_exists" -eq 1 ] && [ "$local_exists" -eq 0 ]; then
-        # Remote exists, no local branch - create local with tracking
+        # Remote exists, no local branch — create local tracking branch first
         log_step "Branch '$branch_name' exists on remote"
-
-        # Create tracking branch first for explicit upstream configuration
         if git branch --track "$branch_name" "origin/$branch_name" >/dev/null 2>&1; then
           log_info "Created local branch tracking origin/$branch_name"
         fi
-
-        # Now add worktree using the tracking branch
-        if git worktree add $force_flag "$worktree_path" "$branch_name" >&2; then
-          log_info "Worktree created tracking origin/$branch_name"
-          printf "%s" "$worktree_path"
-          return 0
-        fi
+        _try_worktree_add "$worktree_path" "" \
+          "Worktree created tracking origin/$branch_name" \
+          "$force_flag" "$branch_name" && return 0
       elif [ "$local_exists" -eq 1 ]; then
-        log_step "Using existing local branch $branch_name"
-        if git worktree add $force_flag "$worktree_path" "$branch_name" >&2; then
-          log_info "Worktree created with local branch $branch_name"
-          printf "%s" "$worktree_path"
-          return 0
-        fi
+        _try_worktree_add "$worktree_path" \
+          "Using existing local branch $branch_name" \
+          "Worktree created with local branch $branch_name" \
+          "$force_flag" "$branch_name" && return 0
       else
-        log_step "Creating new branch $branch_name from $from_ref"
-        if git worktree add $force_flag "$worktree_path" -b "$branch_name" "$from_ref" >&2; then
-          log_info "Worktree created with new branch $branch_name"
-          printf "%s" "$worktree_path"
-          return 0
-        fi
+        _try_worktree_add "$worktree_path" \
+          "Creating new branch $branch_name from $from_ref" \
+          "Worktree created with new branch $branch_name" \
+          "$force_flag" -b "$branch_name" "$from_ref" && return 0
       fi
       ;;
   esac
diff --git a/tests/adapters.bats b/tests/adapters.bats
new file mode 100644
index 0000000..3b96cdf
--- /dev/null
+++ b/tests/adapters.bats
@@ -0,0 +1,112 @@
+#!/usr/bin/env bats
+# Tests for lib/adapters.sh — registry lookup, name listing
+load test_helper
+
+setup() {
+  # Adapters source needs stubs for additional functions it may reference
+  resolve_workspace_file() { :; }
+  export -f resolve_workspace_file
+  source "$PROJECT_ROOT/lib/adapters.sh"
+}
+
+# ── _registry_lookup ─────────────────────────────────────────────────────────
+
+@test "_registry_lookup finds vscode entry" {
+  result=$(_registry_lookup "$_EDITOR_REGISTRY" "vscode")
+  [[ "$result" == "vscode|code|"* ]]
+}
+
+@test "_registry_lookup finds vim entry" {
+  result=$(_registry_lookup "$_EDITOR_REGISTRY" "vim")
+  [[ "$result" == "vim|vim|terminal|"* ]]
+}
+
+@test "_registry_lookup finds aider AI entry" {
+  result=$(_registry_lookup "$_AI_REGISTRY" "aider")
+  [[ "$result" == "aider|aider|"* ]]
+}
+
+@test "_registry_lookup returns 1 for unknown editor" {
+  run _registry_lookup "$_EDITOR_REGISTRY" "nonexistent"
+  [ "$status" -eq 1 ]
+}
+
+@test "_registry_lookup returns 1 for unknown AI tool" {
+  run _registry_lookup "$_AI_REGISTRY" "nonexistent"
+  [ "$status" -eq 1 ]
+}
+
+@test "_registry_lookup matches exact names only" {
+  # "code" is the *command* for vscode, not the *name* — should not match
+  run _registry_lookup "$_EDITOR_REGISTRY" "code"
+  [ "$status" -eq 1 ]
+}
+
+# ── _list_registry_names ─────────────────────────────────────────────────────
+
+@test "_list_registry_names includes expected editors" {
+  result=$(_list_registry_names "$_EDITOR_REGISTRY")
+  [[ "$result" == *"vscode"* ]]
+  [[ "$result" == *"vim"* ]]
+  [[ "$result" == *"cursor"* ]]
+  [[ "$result" == *"emacs"* ]]
+}
+
+@test "_list_registry_names includes expected AI tools" {
+  result=$(_list_registry_names "$_AI_REGISTRY")
+  [[ "$result" == *"aider"* ]]
+  [[ "$result" == *"copilot"* ]]
+  [[ "$result" == *"gemini"* ]]
+}
+
+@test "_list_registry_names returns comma-separated format" {
+  result=$(_list_registry_names "$_EDITOR_REGISTRY")
+  # Should contain commas between names
+  [[ "$result" == *", "* ]]
+}
+
+# ── _load_from_editor_registry ───────────────────────────────────────────────
+
+@test "_load_from_editor_registry parses vscode entry correctly" {
+  local entry
+  entry=$(_registry_lookup "$_EDITOR_REGISTRY" "vscode")
+  _load_from_editor_registry "$entry"
+  [ "$_EDITOR_CMD" = "code" ]
+  [ "$_EDITOR_WORKSPACE" -eq 1 ]
+}
+
+@test "_load_from_editor_registry parses vim as terminal type" {
+  local entry
+  entry=$(_registry_lookup "$_EDITOR_REGISTRY" "vim")
+  _load_from_editor_registry "$entry"
+  [ "$_EDITOR_CMD" = "vim" ]
+  # Terminal editors get editor_open defined
+  declare -f editor_can_open >/dev/null
+}
+
+@test "_load_from_editor_registry parses emacs with background flag" {
+  local entry
+  entry=$(_registry_lookup "$_EDITOR_REGISTRY" "emacs")
+  _load_from_editor_registry "$entry"
+  [ "$_EDITOR_CMD" = "emacs" ]
+  [ "$_EDITOR_BACKGROUND" -eq 1 ]
+}
+
+# ── _load_from_ai_registry ──────────────────────────────────────────────────
+
+@test "_load_from_ai_registry parses aider entry correctly" {
+  local entry
+  entry=$(_registry_lookup "$_AI_REGISTRY" "aider")
+  _load_from_ai_registry "$entry"
+  [ "$_AI_CMD" = "aider" ]
+  declare -f ai_can_start >/dev/null
+}
+
+@test "_load_from_ai_registry parses codex with multiple info lines" {
+  local entry
+  entry=$(_registry_lookup "$_AI_REGISTRY" "codex")
+  _load_from_ai_registry "$entry"
+  [ "$_AI_CMD" = "codex" ]
+  # codex has semicolon-separated info lines (e.g., "Or: brew install codex;See https://...")
+  [ "${#_AI_INFO_LINES[@]}" -ge 2 ]
+}
diff --git a/tests/config.bats b/tests/config.bats
new file mode 100644
index 0000000..e8abb5f
--- /dev/null
+++ b/tests/config.bats
@@ -0,0 +1,127 @@
+#!/usr/bin/env bats
+# Tests for lib/config.sh — key mapping, cfg_list helpers, formatting
+load test_helper
+
+setup() {
+  source "$PROJECT_ROOT/lib/config.sh"
+}
+
+# ── Key mapping ──────────────────────────────────────────────────────────────
+
+@test "cfg_map_to_file_key maps gtr.copy.include to copy.include" {
+  result=$(cfg_map_to_file_key "gtr.copy.include")
+  [ "$result" = "copy.include" ]
+}
+
+@test "cfg_map_to_file_key maps gtr.editor.default to defaults.editor" {
+  result=$(cfg_map_to_file_key "gtr.editor.default")
+  [ "$result" = "defaults.editor" ]
+}
+
+@test "cfg_map_to_file_key returns empty for unknown key" {
+  result=$(cfg_map_to_file_key "gtr.nonexistent")
+  [ -z "$result" ]
+}
+
+@test "cfg_map_from_file_key maps copy.include to gtr.copy.include" {
+  result=$(cfg_map_from_file_key "copy.include")
+  [ "$result" = "gtr.copy.include" ]
+}
+
+@test "cfg_map_from_file_key maps defaults.editor to gtr.editor.default" {
+  result=$(cfg_map_from_file_key "defaults.editor")
+  [ "$result" = "gtr.editor.default" ]
+}
+
+@test "cfg_map_from_file_key passes through gtr.* keys" {
+  result=$(cfg_map_from_file_key "gtr.copy.include")
+  [ "$result" = "gtr.copy.include" ]
+}
+
+@test "cfg_map_from_file_key returns empty for unknown non-gtr key" {
+  result=$(cfg_map_from_file_key "totally.unknown")
+  [ -z "$result" ]
+}
+
+@test "round-trip: all _CFG_KEY_MAP entries are bidirectional" {
+  for pair in "${_CFG_KEY_MAP[@]}"; do
+    local gtr_key="${pair%%|*}"
+    local file_key="${pair#*|}"
+
+    local mapped_file
+    mapped_file=$(cfg_map_to_file_key "$gtr_key")
+    [ "$mapped_file" = "$file_key" ]
+
+    local mapped_gtr
+    mapped_gtr=$(cfg_map_from_file_key "$file_key")
+    [ "$mapped_gtr" = "$gtr_key" ]
+  done
+}
+
+# ── Known key detection ──────────────────────────────────────────────────────
+
+@test "_cfg_is_known_key returns 0 for gtr.copy.include" {
+  _cfg_is_known_key "gtr.copy.include"
+}
+
+@test "_cfg_is_known_key returns 0 for gtr.hook.postCd" {
+  _cfg_is_known_key "gtr.hook.postCd"
+}
+
+@test "_cfg_is_known_key returns 1 for unknown key" {
+  ! _cfg_is_known_key "gtr.nonexistent"
+}
+
+# ── cfg_list deduplication ───────────────────────────────────────────────────
+
+@test "_cfg_list_add_entry adds entry to result" {
+  _cfg_list_seen=""
+  _cfg_list_result=""
+  _cfg_list_add_entry "local" "gtr.editor.default" "vscode"
+  [[ "$_cfg_list_result" == *"gtr.editor.default"* ]]
+  [[ "$_cfg_list_result" == *"vscode"* ]]
+  [[ "$_cfg_list_result" == *"local"* ]]
+}
+
+@test "_cfg_list_add_entry deduplicates same key+value" {
+  _cfg_list_seen=""
+  _cfg_list_result=""
+  _cfg_list_add_entry "local" "gtr.editor.default" "vscode"
+  _cfg_list_add_entry "global" "gtr.editor.default" "vscode"
+  # Should only appear once (local takes priority)
+  local count
+  count=$(printf '%s' "$_cfg_list_result" | grep -c "gtr.editor.default" || true)
+  [ "$count" -eq 1 ]
+}
+
+@test "_cfg_list_add_entry allows same key with different values" {
+  _cfg_list_seen=""
+  _cfg_list_result=""
+  _cfg_list_add_entry "local" "gtr.copy.include" ".env*"
+  _cfg_list_add_entry "local" "gtr.copy.include" "*.config.js"
+  local count
+  count=$(printf '%s' "$_cfg_list_result" | grep -c "gtr.copy.include" || true)
+  [ "$count" -eq 2 ]
+}
+
+# ── cfg_list formatting ─────────────────────────────────────────────────────
+
+@test "_cfg_list_format shows message for empty output" {
+  result=$(_cfg_list_format "")
+  [ "$result" = "No gtr configuration found" ]
+}
+
+@test "_cfg_list_format formats scoped output (space-delimited)" {
+  result=$(_cfg_list_format "gtr.editor.default vscode")
+  [[ "$result" == *"gtr.editor.default"* ]]
+  [[ "$result" == *"= vscode"* ]]
+}
+
+@test "_cfg_list_format formats auto output (unit-separator-delimited)" {
+  local us=$'\x1f'
+  local input="gtr.editor.default${us}vscode${us}local"
+  result=$(_cfg_list_format "$input")
+  [[ "$result" == *"gtr.editor.default"* ]]
+  [[ "$result" == *"vscode"* ]]
+  [[ "$result" == *"[local]"* ]]
+}
diff --git a/tests/provider.bats b/tests/provider.bats
new file mode 100644
index 0000000..3491e80
--- /dev/null
+++ b/tests/provider.bats
@@ -0,0 +1,54 @@
+#!/usr/bin/env bats
+# Tests for lib/provider.sh — hostname extraction and provider detection
+load test_helper
+
+setup() {
+  source "$PROJECT_ROOT/lib/provider.sh"
+}
+
+# ── extract_hostname ─────────────────────────────────────────────────────────
+
+@test "extract_hostname from SSH shorthand" {
+  result=$(extract_hostname "git@github.com:user/repo.git")
+  [ "$result" = "github.com" ]
+}
+
+@test "extract_hostname from HTTPS URL" {
+  result=$(extract_hostname "https://github.com/user/repo.git")
+  [ "$result" = "github.com" ]
+}
+
+@test "extract_hostname from SSH scheme URL" {
+  result=$(extract_hostname "ssh://git@github.com/user/repo.git")
+  [ "$result" = "github.com" ]
+}
+
+@test "extract_hostname from GitLab SSH shorthand" {
+  result=$(extract_hostname "git@gitlab.com:group/repo.git")
+  [ "$result" = "gitlab.com" ]
+}
+
+@test "extract_hostname from GitLab HTTPS" {
+  result=$(extract_hostname "https://gitlab.com/group/subgroup/repo.git")
+  [ "$result" = "gitlab.com" ]
+}
+
+@test "extract_hostname from self-hosted SSH" {
+  result=$(extract_hostname "git@git.example.com:org/repo.git")
+  [ "$result" = "git.example.com" ]
+}
+
+@test "extract_hostname from HTTPS with port" {
+  result=$(extract_hostname "https://git.example.com:8443/org/repo.git")
+  [ "$result" = "git.example.com" ]
+}
+
+@test "extract_hostname fails on bare path" {
+  run extract_hostname "/local/path"
+  [ "$status" -ne 0 ]
+}
+
+@test "extract_hostname fails on empty input" {
+  run extract_hostname ""
+  [ "$status" -ne 0 ]
+}

From 2fcf30268240facd2f8e15fc6457e9134735d40a Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 18:00:13 -0800
Subject: [PATCH 14/19] fix: improve error handling in launch and command
 scripts

- Enhanced error handling in `lib/launch.sh` to log warnings when failing to open the editor or start the AI tool.
- Updated `lib/commands/clean.sh` to ensure the current branch retrieval does not fail the script execution.
- Improved user feedback in `lib/commands/editor.sh` by logging warnings when the file browser fails to open.
- Added local variables in `lib/commands/copy.sh` for better clarity and maintainability.
---
 lib/commands/clean.sh  | 2 +-
 lib/commands/copy.sh   | 2 ++
 lib/commands/editor.sh | 7 +++++--
 lib/launch.sh          | 4 ++--
 4 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index 3a5761a..7bb724c 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -48,7 +48,7 @@ _clean_merged() {
     [ -d "$dir" ] || continue
 
     local branch
-    branch=$(current_branch "$dir")
+    branch=$(current_branch "$dir") || true
 
     if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
       log_warn "Skipping $dir (detached HEAD)"
diff --git a/lib/commands/copy.sh b/lib/commands/copy.sh
index 20d86a0..077eecb 100644
--- a/lib/commands/copy.sh
+++ b/lib/commands/copy.sh
@@ -65,6 +65,7 @@ cmd_copy() {
       log_error "No worktrees found"
       exit 1
     fi
+    local _branch
     while IFS= read -r _branch; do
       [ -n "$_branch" ] && targets+=("$_branch")
     done <<< "$all_branches"
@@ -72,6 +73,7 @@ cmd_copy() {
 
   # Process each target
   local copied_any=0
+  local target_id
   for target_id in "${targets[@]}"; do
     local dst_path dst_branch
     resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
index 5706a50..19682b7 100644
--- a/lib/commands/editor.sh
+++ b/lib/commands/editor.sh
@@ -29,8 +29,11 @@ cmd_editor() {
   worktree_path="$_ctx_worktree_path"
 
   if [ "$editor" = "none" ]; then
-    open_in_gui "$worktree_path"
-    log_info "Opened in file browser"
+    if ! open_in_gui "$worktree_path"; then
+      log_warn "Could not open file browser"
+    else
+      log_info "Opened in file browser"
+    fi
   else
     _open_editor "$editor" "$worktree_path" || exit 1
   fi
diff --git a/lib/launch.sh b/lib/launch.sh
index 517e5d8..3204620 100644
--- a/lib/launch.sh
+++ b/lib/launch.sh
@@ -30,7 +30,7 @@ _auto_launch_editor() {
   local editor
   editor=$(_cfg_editor_default)
   if [ "$editor" != "none" ]; then
-    _open_editor "$editor" "$worktree_path"
+    _open_editor "$editor" "$worktree_path" || log_warn "Failed to open editor"
   else
     if ! open_in_gui "$worktree_path"; then
       log_warn "Could not open file browser"
@@ -50,6 +50,6 @@ _auto_launch_ai() {
   else
     load_ai_adapter "$ai_tool" || return 1
     log_step "Starting $ai_tool..."
-    ai_start "$worktree_path"
+    ai_start "$worktree_path" || log_warn "Failed to start AI tool"
   fi
 }

From 1a4b73a8bec62c1ea7e04afdba89254180cf78e1 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 18:11:40 -0800
Subject: [PATCH 15/19] refactor: remove unused functions and improve command
 clarity

- Removed the unused helper function `__fish_git_gtr_config_is_write` from `completions/git-gtr.fish` and `scripts/generate-completions.sh` to streamline the code.
- Deleted the `copy_file` function from `lib/copy.sh` as it was redundant and not utilized in the current codebase.
- Eliminated the `list_worktrees` function from `lib/core.sh` to enhance clarity and maintainability of the code.
---
 completions/git-gtr.fish        | 11 -----------
 lib/commands/ai.sh              |  2 +-
 lib/commands/clean.sh           | 31 +++++++++++++++++++++----------
 lib/commands/copy.sh            |  2 +-
 lib/commands/create.sh          |  4 +++-
 lib/commands/editor.sh          |  2 +-
 lib/commands/go.sh              |  2 +-
 lib/commands/list.sh            |  2 +-
 lib/commands/remove.sh          |  2 +-
 lib/commands/rename.sh          |  2 +-
 lib/commands/run.sh             |  2 +-
 lib/copy.sh                     | 17 -----------------
 lib/core.sh                     |  5 -----
 scripts/generate-completions.sh | 11 -----------
 14 files changed, 32 insertions(+), 63 deletions(-)

diff --git a/completions/git-gtr.fish b/completions/git-gtr.fish
index 7dd300e..f58df20 100644
--- a/completions/git-gtr.fish
+++ b/completions/git-gtr.fish
@@ -117,17 +117,6 @@ function __fish_git_gtr_config_is_read
   return 1
 end
 
-# Helper to check if config action is a write operation (set, add, unset)
-function __fish_git_gtr_config_is_write
-  set -l cmd (commandline -opc)
-  for i in $cmd
-    if test "$i" = "set" -o "$i" = "add" -o "$i" = "unset"
-      return 0
-    end
-  end
-  return 1
-end
-
 # Scope flags for config command
 # --local and --global available for all operations
 complete -f -c git -n '__fish_git_gtr_using_command config' -l local -d 'Use local git config'
diff --git a/lib/commands/ai.sh b/lib/commands/ai.sh
index 0d14cfc..6594806 100644
--- a/lib/commands/ai.sh
+++ b/lib/commands/ai.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # AI command
+# shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_ai() {
   parse_args "--ai: value" "$@"
 
diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index 7bb724c..b2a3cb7 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Clean command (remove prunable worktrees)
 # Remove worktrees whose PRs/MRs are merged (handles squash merges)
@@ -83,17 +82,28 @@ _clean_merged() {
         removed=$((removed + 1))
       elif [ "$yes_mode" -eq 1 ] || prompt_yes_no "Remove worktree and delete branch '$branch'?"; then
         log_step "Removing worktree: $branch"
-        local remove_output
-        if remove_output=$(git worktree remove "$dir" 2>&1); then
-          # Also delete the local branch
+
+        # Run pre-remove hooks (skip worktree on failure)
+        if ! run_hooks_in preRemove "$dir" \
+          REPO_ROOT="$repo_root" \
+          WORKTREE_PATH="$dir" \
+          BRANCH="$branch"; then
+          log_warn "Pre-remove hook failed for $branch, skipping"
+          skipped=$((skipped + 1))
+          continue
+        fi
+
+        if remove_worktree "$dir" 0; then
+          # Delete the local branch (safe: already merged)
           git branch -d "$branch" 2>/dev/null || git branch -D "$branch" 2>/dev/null || true
-          log_info "Removed: $branch"
           removed=$((removed + 1))
-        else
-          if [ -n "$remove_output" ]; then
-            log_error "Failed to remove worktree: $remove_output"
-          else
-            log_error "Failed to remove worktree: $branch"
+
+          # Run post-remove hooks (worktree already removed, don't abort)
+          if ! run_hooks postRemove \
+            REPO_ROOT="$repo_root" \
+            WORKTREE_PATH="$dir" \
+            BRANCH="$branch"; then
+            log_warn "Post-remove hook failed for $branch"
           fi
         fi
       else
@@ -112,6 +122,7 @@ _clean_merged() {
   fi
 }
 
+# shellcheck disable=SC2154  # _arg_* set by parse_args, _ctx_* set by resolve_*
 cmd_clean() {
   local _spec
   _spec="--merged
diff --git a/lib/commands/copy.sh b/lib/commands/copy.sh
index 077eecb..84e6748 100644
--- a/lib/commands/copy.sh
+++ b/lib/commands/copy.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Copy command (copy files between worktrees)
+# shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*/merge_copy_patterns
 cmd_copy() {
   local _spec
   _spec="--from: value
diff --git a/lib/commands/create.sh b/lib/commands/create.sh
index 8411666..69b1632 100644
--- a/lib/commands/create.sh
+++ b/lib/commands/create.sh
@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Create command
 # Copy files and directories to newly created worktree
 # Usage: _post_create_copy repo_root worktree_path
+# shellcheck disable=SC2154  # _ctx_copy_* set by merge_copy_patterns
 _post_create_copy() {
   local repo_root="$1"
   local worktree_path="$2"
@@ -30,6 +30,7 @@ _post_create_copy() {
 
 # Show next steps after worktree creation (resolves collision for --folder overrides)
 # Usage: _post_create_next_steps branch_name folder_name folder_override repo_root base_dir prefix
+# shellcheck disable=SC2154  # _ctx_is_main set by resolve_target/unpack_target
 _post_create_next_steps() {
   local branch_name="$1" folder_name="$2" folder_override="$3"
   local repo_root="$4" base_dir="$5" prefix="$6"
@@ -83,6 +84,7 @@ _create_resolve_from_ref() {
 
   printf "%s" "$from_ref"
 }
+# shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_create() {
   local _spec
   _spec="--from: value
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
index 19682b7..22ed002 100644
--- a/lib/commands/editor.sh
+++ b/lib/commands/editor.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Editor command
+# shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_editor() {
   parse_args "--editor: value" "$@"
 
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
index d0b189f..7deb00e 100644
--- a/lib/commands/go.sh
+++ b/lib/commands/go.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Go command (navigate to worktree - prints path for shell integration)
+# shellcheck disable=SC2154  # _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_go() {
   parse_args "" "$@"
 
diff --git a/lib/commands/list.sh b/lib/commands/list.sh
index 2f1313b..749c158 100644
--- a/lib/commands/list.sh
+++ b/lib/commands/list.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # List command
+# shellcheck disable=SC2154  # _arg_* set by parse_args, _ctx_* set by resolve_*
 cmd_list() {
   parse_args "--porcelain" "$@"
 
diff --git a/lib/commands/remove.sh b/lib/commands/remove.sh
index f555787..8e76bcc 100644
--- a/lib/commands/remove.sh
+++ b/lib/commands/remove.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Remove command
+# shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_remove() {
   local _spec
   _spec="--delete-branch
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
index ae3dff4..248ef11 100644
--- a/lib/commands/rename.sh
+++ b/lib/commands/rename.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Rename command (rename worktree and branch)
+# shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_rename() {
   local _spec
   _spec="--force
diff --git a/lib/commands/run.sh b/lib/commands/run.sh
index a19120c..7c1eea4 100644
--- a/lib/commands/run.sh
+++ b/lib/commands/run.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2154
 
 # Run command (execute command in worktree directory)
+# shellcheck disable=SC2154  # _ctx_* set by resolve_*
 cmd_run() {
   local identifier=""
   local -a run_args=()
diff --git a/lib/copy.sh b/lib/copy.sh
index 0543139..1281270 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -334,20 +334,3 @@ EOF
 
   return 0
 }
-
-# Copy a single file, creating directories as needed
-# Usage: copy_file src_file dst_file
-copy_file() {
-  local src="$1"
-  local dst="$2"
-  local dst_dir
-
-  dst_dir=$(dirname "$dst")
-  mkdir -p "$dst_dir"
-
-  if cp "$src" "$dst" 2>/dev/null; then
-    return 0
-  else
-    return 1
-  fi
-}
diff --git a/lib/core.sh b/lib/core.sh
index 8455637..b813fdc 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -485,11 +485,6 @@ remove_worktree() {
   fi
 }
 
-# List all worktrees
-list_worktrees() {
-  git worktree list
-}
-
 # Resolve common repo context used by most cmd_* handlers.
 # Sets globals: _ctx_repo_root, _ctx_base_dir, _ctx_prefix
 # Usage: resolve_repo_context || exit 1
diff --git a/scripts/generate-completions.sh b/scripts/generate-completions.sh
index 07c1a0d..e4a5d68 100755
--- a/scripts/generate-completions.sh
+++ b/scripts/generate-completions.sh
@@ -580,17 +580,6 @@ function __fish_git_gtr_config_is_read
   return 1
 end
 
-# Helper to check if config action is a write operation (set, add, unset)
-function __fish_git_gtr_config_is_write
-  set -l cmd (commandline -opc)
-  for i in $cmd
-    if test "$i" = "set" -o "$i" = "add" -o "$i" = "unset"
-      return 0
-    end
-  end
-  return 1
-end
-
 # Scope flags for config command
 # --local and --global available for all operations
 complete -f -c git -n '__fish_git_gtr_using_command config' -l local -d 'Use local git config'

From e512a1046d5f653c0e010c1fe3132580831416f2 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 18:16:29 -0800
Subject: [PATCH 16/19] refactor: simplify worktree management by removing
 force flag handling

- Updated the `_try_worktree_add` and `create_worktree` functions to eliminate the use of a separate force flag, replacing it with an array for force arguments.
- Improved clarity in the command usage documentation and streamlined the logic for adding and removing worktrees.
- Enhanced maintainability by reducing complexity in the argument handling for worktree operations.
---
 lib/core.sh | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/lib/core.sh b/lib/core.sh
index b813fdc..ea2d34c 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -307,17 +307,16 @@ resolve_worktree() {
 }
 
 # Try to create a worktree, handling the common log/add/report pattern.
-# Usage: _try_worktree_add <path> <step_msg> <ok_msg> <force_flag> [git_worktree_add_args...]
+# Usage: _try_worktree_add <path> <step_msg> <ok_msg> [git_worktree_add_args...]
 # Prints worktree path on success; returns 1 on failure (caller handles error).
 # Note: step_msg may be empty to skip the log_step call.
 _try_worktree_add() {
-  local wt_path="$1" step_msg="$2" ok_msg="$3" force_flag="$4"
-  shift 4
+  local wt_path="$1" step_msg="$2" ok_msg="$3"
+  shift 3
 
   [ -n "$step_msg" ] && log_step "$step_msg"
 
-  # shellcheck disable=SC2086
-  if git worktree add $force_flag "$wt_path" "$@" >&2; then
+  if git worktree add "$wt_path" "$@" >&2; then
     log_info "$ok_msg"
     printf "%s" "$wt_path"
     return 0
@@ -364,10 +363,10 @@ create_worktree() {
   fi
 
   worktree_path="$base_dir/${prefix}${sanitized_name}"
-  local force_flag=""
+  local force_args=()
 
   if [ "$force" -eq 1 ]; then
-    force_flag="--force"
+    force_args=(--force)
   fi
 
   # Check if worktree already exists
@@ -398,10 +397,10 @@ create_worktree() {
         _try_worktree_add "$worktree_path" \
           "Creating worktree from remote branch origin/$branch_name" \
           "Worktree created tracking origin/$branch_name" \
-          "$force_flag" -b "$branch_name" "origin/$branch_name" && return 0
+          "${force_args[@]}" -b "$branch_name" "origin/$branch_name" && return 0
         _try_worktree_add "$worktree_path" "" \
           "Worktree created tracking origin/$branch_name" \
-          "$force_flag" "$branch_name" && return 0
+          "${force_args[@]}" "$branch_name" && return 0
       fi
       log_error "Remote branch origin/$branch_name does not exist"
       return 1
@@ -412,7 +411,7 @@ create_worktree() {
         _try_worktree_add "$worktree_path" \
           "Creating worktree from local branch $branch_name" \
           "Worktree created with local branch $branch_name" \
-          "$force_flag" "$branch_name" && return 0
+          "${force_args[@]}" "$branch_name" && return 0
       fi
       log_error "Local branch $branch_name does not exist"
       return 1
@@ -422,7 +421,7 @@ create_worktree() {
       _try_worktree_add "$worktree_path" \
         "Creating new branch $branch_name from $from_ref" \
         "Worktree created with new branch $branch_name" \
-        "$force_flag" -b "$branch_name" "$from_ref" && return 0
+        "${force_args[@]}" -b "$branch_name" "$from_ref" && return 0
       log_error "Failed to create worktree with new branch"
       return 1
       ;;
@@ -436,17 +435,17 @@ create_worktree() {
         fi
         _try_worktree_add "$worktree_path" "" \
           "Worktree created tracking origin/$branch_name" \
-          "$force_flag" "$branch_name" && return 0
+          "${force_args[@]}" "$branch_name" && return 0
       elif [ "$local_exists" -eq 1 ]; then
         _try_worktree_add "$worktree_path" \
           "Using existing local branch $branch_name" \
           "Worktree created with local branch $branch_name" \
-          "$force_flag" "$branch_name" && return 0
+          "${force_args[@]}" "$branch_name" && return 0
       else
         _try_worktree_add "$worktree_path" \
           "Creating new branch $branch_name from $from_ref" \
           "Worktree created with new branch $branch_name" \
-          "$force_flag" -b "$branch_name" "$from_ref" && return 0
+          "${force_args[@]}" -b "$branch_name" "$from_ref" && return 0
       fi
       ;;
   esac
@@ -466,13 +465,13 @@ remove_worktree() {
     return 1
   fi
 
-  local force_flag=""
+  local force_args=()
   if [ "$force" -eq 1 ]; then
-    force_flag="--force"
+    force_args=(--force)
   fi
 
   local remove_output
-  if remove_output=$(git worktree remove $force_flag "$worktree_path" 2>&1); then
+  if remove_output=$(git worktree remove "${force_args[@]}" "$worktree_path" 2>&1); then
     log_info "Worktree removed: $worktree_path"
     return 0
   else

From 7fdcadf1e1268d937ffa4059e702fa1dd69424aa Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 19:20:58 -0800
Subject: [PATCH 17/19] refactor: update shebang and improve pattern matching
 in scripts

- Changed the shebang in `gtr.bash` and `generate-completions.sh` to use `/usr/bin/env bash` for better portability.
- Refactored pattern matching logic in `copy.sh` to utilize a case statement, enhancing readability and maintainability.
- Added a local variable declaration in `create.sh` for improved clarity in the command execution flow.
- Updated conditional checks in `go.sh` and `run.sh` to use quotes around array length checks, preventing potential errors.
---
 completions/gtr.bash            | 2 +-
 lib/commands/create.sh          | 1 +
 lib/commands/go.sh              | 2 +-
 lib/commands/rename.sh          | 2 +-
 lib/commands/run.sh             | 2 +-
 lib/copy.sh                     | 2 +-
 scripts/generate-completions.sh | 2 +-
 7 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/completions/gtr.bash b/completions/gtr.bash
index bd92f30..84a25ee 100644
--- a/completions/gtr.bash
+++ b/completions/gtr.bash
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
 # Re-generate with: ./scripts/generate-completions.sh
 #
diff --git a/lib/commands/create.sh b/lib/commands/create.sh
index 69b1632..f325e79 100644
--- a/lib/commands/create.sh
+++ b/lib/commands/create.sh
@@ -169,6 +169,7 @@ cmd_create() {
   echo "Branch: $branch_name"
 
   # Create the worktree
+  local worktree_path
   if ! worktree_path=$(create_worktree "$base_dir" "$prefix" "$branch_name" "$from_ref" "$track_mode" "$skip_fetch" "$force" "$custom_name" "$folder_override"); then
     exit 1
   fi
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
index 7deb00e..354552d 100644
--- a/lib/commands/go.sh
+++ b/lib/commands/go.sh
@@ -5,7 +5,7 @@
 cmd_go() {
   parse_args "" "$@"
 
-  if [ ${#_pa_positional[@]} -ne 1 ]; then
+  if [ "${#_pa_positional[@]}" -ne 1 ]; then
     log_error "Usage: git gtr go <id|branch>"
     exit 1
   fi
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
index 248ef11..2f0a6d8 100644
--- a/lib/commands/rename.sh
+++ b/lib/commands/rename.sh
@@ -76,7 +76,7 @@ cmd_rename() {
     move_args+=(--force)
   fi
 
-  if ! git -C "$repo_root" worktree move "$old_path" "$new_path" "${move_args[@]}"; then
+  if ! git -C "$repo_root" worktree move "${move_args[@]}" "$old_path" "$new_path"; then
     # Rollback: rename branch back
     log_warn "Worktree move failed, rolling back branch rename..."
     git -C "$repo_root" branch -m "$new_name" "$old_branch" 2>/dev/null || true
diff --git a/lib/commands/run.sh b/lib/commands/run.sh
index 7c1eea4..ed45146 100644
--- a/lib/commands/run.sh
+++ b/lib/commands/run.sh
@@ -47,7 +47,7 @@ cmd_run() {
     exit 1
   fi
 
-  if [ ${#run_args[@]} -eq 0 ]; then
+  if [ "${#run_args[@]}" -eq 0 ]; then
     log_error "Usage: git gtr run <id|branch> <command...>"
     log_error "No command specified"
     exit 1
diff --git a/lib/copy.sh b/lib/copy.sh
index 1281270..fa095c1 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -320,7 +320,7 @@ copy_directories() {
         log_warn "Failed to copy directory $dir_path"
       fi
     done <<EOF
-$(if [[ "$pattern" == */* ]]; then find . -type d -path "./$pattern" 2>/dev/null; else find . -type d -name "$pattern" 2>/dev/null; fi || true)
+$(case "$pattern" in */*) find . -type d -path "./$pattern" 2>/dev/null ;; *) find . -type d -name "$pattern" 2>/dev/null ;; esac)
 EOF
   done <<EOF
 $dir_patterns
diff --git a/scripts/generate-completions.sh b/scripts/generate-completions.sh
index e4a5d68..4701112 100755
--- a/scripts/generate-completions.sh
+++ b/scripts/generate-completions.sh
@@ -88,7 +88,7 @@ CONFIG_KEYS=$(get_config_keys)
 
 generate_bash() {
   cat <<'HEADER'
-#!/bin/bash
+#!/usr/bin/env bash
 # AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
 # Re-generate with: ./scripts/generate-completions.sh
 #

From 4e3f724dd3ed1273457cff8927be027b7d6d2cab Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 20:34:07 -0800
Subject: [PATCH 18/19] refactor: enhance testing and command structure

- Updated CLAUDE.md to clarify testing procedures, including automated BATS tests and manual smoke tests.
- Introduced new functions in `lib/args.sh` for validating positional arguments, improving error handling in command scripts.
- Refactored `lib/copy.sh` to streamline file copying logic with a new `_expand_and_copy_pattern` function, enhancing maintainability.
- Improved `create_worktree` and related functions in `lib/core.sh` for better folder name resolution and branch checking.
- Added comprehensive tests for new and existing functionalities, ensuring robust validation of command behaviors and error handling.
---
 CLAUDE.md                         |  46 +++++++---
 lib/args.sh                       |  10 +++
 lib/commands/ai.sh                |   8 +-
 lib/commands/clean.sh             | 108 ++++++++++++-----------
 lib/commands/editor.sh            |   8 +-
 lib/commands/go.sh                |   6 +-
 lib/commands/remove.sh            |   7 +-
 lib/commands/rename.sh            |  12 +--
 lib/copy.sh                       |  80 ++++++++---------
 lib/core.sh                       | 106 ++++++++++++----------
 tests/cmd_clean.bats              |  78 +++++++++++++++++
 tests/cmd_create_integration.bats |  70 +++++++++++++++
 tests/cmd_go.bats                 |  53 +++++++++++
 tests/cmd_list.bats               |  59 +++++++++++++
 tests/cmd_remove.bats             |  83 ++++++++++++++++++
 tests/core_create_worktree.bats   | 141 ++++++++++++++++++++++++++++++
 tests/core_resolve_target.bats    |  82 +++++++++++++++++
 tests/hooks.bats                  |  90 +++++++++++++++++++
 tests/test_helper.bash            |  33 +++++++
 19 files changed, 898 insertions(+), 182 deletions(-)
 create mode 100644 tests/cmd_clean.bats
 create mode 100644 tests/cmd_create_integration.bats
 create mode 100644 tests/cmd_go.bats
 create mode 100644 tests/cmd_list.bats
 create mode 100644 tests/cmd_remove.bats
 create mode 100644 tests/core_create_worktree.bats
 create mode 100644 tests/core_resolve_target.bats
 create mode 100644 tests/hooks.bats

diff --git a/CLAUDE.md b/CLAUDE.md
index ceba77a..1604f17 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,10 +14,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Testing
 
-This project uses **BATS tests** for core functions and **manual smoke tests** for end-to-end workflows. After any change:
+This project uses **BATS tests** for core functions and **manual smoke tests** for end-to-end workflows. CI runs ShellCheck + BATS automatically on PRs (`.github/workflows/lint.yml`).
 
 1. Run automated tests: `bats tests/`
-2. Run relevant manual smoke tests:
+2. Run a single test file: `bats tests/config.bats`
+3. Run a single test by name: `bats tests/config.bats --filter "cfg_map_to_file_key"`
+4. Run relevant manual smoke tests:
 
 ```bash
 ./bin/gtr new test-feature          # Create worktree
@@ -30,6 +32,8 @@ This project uses **BATS tests** for core functions and **manual smoke tests** f
 
 For exhaustive manual testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
 
+**Test files**: `adapters`, `config`, `copy_safety`, `integration_lifecycle`, `parse_args`, `provider`, `resolve_base_dir`, `sanitize_branch_name` (all in `tests/`). Shared fixtures in `tests/test_helper.bash`.
+
 **Tip**: Use a disposable repo for testing to avoid polluting your working tree:
 
 ```bash
@@ -42,20 +46,25 @@ mkdir -p /tmp/gtr-test && cd /tmp/gtr-test && git init && git commit --allow-emp
 ### Binary Structure
 
 - `bin/git-gtr` — Thin wrapper enabling `git gtr` subcommand invocation
-- `bin/gtr` — Entry point (~105 lines): sources libraries and commands, contains `main()` dispatcher
+- `bin/gtr` — Entry point: sources libraries and commands, contains `main()` dispatcher
 
 ### Module Structure
 
-| File               | Purpose                                                                                                     |
-| ------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `lib/core.sh`      | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
-| `lib/config.sh`    | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
-| `lib/copy.sh`      | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
-| `lib/hooks.sh`     | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
-| `lib/ui.sh`        | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
-| `lib/platform.sh`  | OS detection, GUI helpers                                                                                   |
-| `lib/adapters.sh`  | Adapter registry, builder functions, generic fallbacks, loader functions                                    |
-| `lib/commands/*.sh` | One file per subcommand: `cmd_create`, `cmd_remove`, etc. (16 files)                                       |
+| File                | Purpose                                                                                                     |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `lib/ui.sh`         | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
+| `lib/args.sh`       | Shared argument parser: flag specs (`--flag`, `--flag: val`, aliases), populates `_arg_*` vars              |
+| `lib/config.sh`     | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
+| `lib/platform.sh`   | OS detection, GUI helpers                                                                                   |
+| `lib/core.sh`       | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
+| `lib/copy.sh`       | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
+| `lib/hooks.sh`      | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
+| `lib/provider.sh`   | Remote hosting detection (GitHub/GitLab) and CLI integration for `clean --merged`                           |
+| `lib/adapters.sh`   | Adapter registry, builder functions, generic fallbacks, loader functions                                    |
+| `lib/launch.sh`     | Editor/AI launch orchestration: `_open_editor`, `_auto_launch_editor`, `_auto_launch_ai`                    |
+| `lib/commands/*.sh` | One file per subcommand: `cmd_create`, `cmd_remove`, etc. (16 files)                                        |
+
+Libraries are sourced in the order listed above (ui → args → config → ... → launch → commands/\*.sh glob).
 
 ### Adapters
 
@@ -135,6 +144,17 @@ When adding commands or flags, update all three files:
 - `completions/_git-gtr` (Zsh)
 - `completions/git-gtr.fish` (Fish)
 
+## Critical Gotcha: `set -e`
+
+`bin/gtr` runs with `set -e`. Any unguarded non-zero return silently exits the entire script. When calling functions that may `return 1`, guard with `|| true`:
+
+```bash
+result=$(my_func) || true           # Prevents silent exit
+if my_func; then ...; fi            # Also safe (if guards the return)
+```
+
+This is the most common source of subtle bugs in this codebase.
+
 ## Code Style
 
 - Shebang: `#!/usr/bin/env bash`
diff --git a/lib/args.sh b/lib/args.sh
index 6443668..97d7539 100644
--- a/lib/args.sh
+++ b/lib/args.sh
@@ -123,3 +123,13 @@ EOF
     esac
   done
 }
+
+# Validate that at least N positional arguments were provided.
+# Call after parse_args. Exits with error message if insufficient args.
+# Usage: require_args <min_count> "<usage message>"
+require_args() {
+  if [ "${#_pa_positional[@]}" -lt "$1" ]; then
+    log_error "$2"
+    exit 1
+  fi
+}
diff --git a/lib/commands/ai.sh b/lib/commands/ai.sh
index 6594806..9549d03 100644
--- a/lib/commands/ai.sh
+++ b/lib/commands/ai.sh
@@ -4,16 +4,12 @@
 # shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_ai() {
   parse_args "--ai: value" "$@"
+  require_args 1 "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
 
-  local identifier="${_pa_positional[0]:-}"
+  local identifier="${_pa_positional[0]}"
   local ai_tool="${_arg_ai:-}"
   local -a ai_args=("${_pa_passthrough[@]}")
 
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
-    exit 1
-  fi
-
   # Get AI tool from flag or config (with .gtrconfig support)
   if [ -z "$ai_tool" ]; then
     ai_tool=$(_cfg_ai_default)
diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index b2a3cb7..fa8fea2 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -1,6 +1,58 @@
 #!/usr/bin/env bash
 
 # Clean command (remove prunable worktrees)
+
+# Detect hosting provider with error messaging.
+# Prints provider name on success; returns 1 on failure.
+_clean_detect_provider() {
+  local provider
+  provider=$(detect_provider) || true
+  if [ -n "$provider" ]; then
+    printf "%s" "$provider"
+    return 0
+  fi
+
+  local remote_url
+  remote_url=$(git remote get-url origin 2>/dev/null || true)
+  if [ -z "$remote_url" ]; then
+    log_error "No remote URL configured for 'origin'"
+  else
+    # Sanitize URL to avoid leaking embedded credentials (e.g., https://token@host/...)
+    local safe_url="${remote_url%%@*}"
+    if [ "$safe_url" != "$remote_url" ]; then
+      safe_url="<redacted>@${remote_url#*@}"
+    fi
+    log_error "Could not detect hosting provider from remote URL: $safe_url"
+    log_info "Set manually: git gtr config set gtr.provider github  (or gitlab)"
+  fi
+  return 1
+}
+
+# Check if a worktree should be skipped during merged cleanup.
+# Returns 0 if should skip, 1 if should process.
+# Usage: _clean_should_skip <dir> <branch>
+_clean_should_skip() {
+  local dir="$1" branch="$2"
+
+  if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
+    log_warn "Skipping $dir (detached HEAD)"
+    return 0
+  fi
+
+  if ! git -C "$dir" diff --quiet 2>/dev/null || \
+     ! git -C "$dir" diff --cached --quiet 2>/dev/null; then
+    log_warn "Skipping $branch (has uncommitted changes)"
+    return 0
+  fi
+
+  if [ -n "$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null)" ]; then
+    log_warn "Skipping $branch (has untracked files)"
+    return 0
+  fi
+
+  return 1
+}
+
 # Remove worktrees whose PRs/MRs are merged (handles squash merges)
 # Usage: _clean_merged repo_root base_dir prefix yes_mode dry_run
 _clean_merged() {
@@ -8,69 +60,27 @@ _clean_merged() {
 
   log_step "Checking for worktrees with merged PRs/MRs..."
 
-  # Detect hosting provider (GitHub, GitLab, etc.)
   local provider
-  provider=$(detect_provider) || true
-  if [ -z "$provider" ]; then
-    local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null || true)
-    if [ -z "$remote_url" ]; then
-      log_error "No remote URL configured for 'origin'"
-    else
-      # Sanitize URL to avoid leaking embedded credentials (e.g., https://token@host/...)
-      local safe_url="${remote_url%%@*}"
-      if [ "$safe_url" != "$remote_url" ]; then
-        safe_url="<redacted>@${remote_url#*@}"
-      fi
-      log_error "Could not detect hosting provider from remote URL: $safe_url"
-      log_info "Set manually: git gtr config set gtr.provider github  (or gitlab)"
-    fi
-    exit 1
-  fi
-
-  # Ensure provider CLI is available and authenticated
+  provider=$(_clean_detect_provider) || exit 1
   ensure_provider_cli "$provider" || exit 1
 
-  # Fetch latest from origin
   log_step "Fetching from origin..."
   git fetch origin --prune 2>/dev/null || log_warn "Could not fetch from origin"
 
-  local removed=0
-  local skipped=0
-
-  # Get main repo branch to exclude it
+  local removed=0 skipped=0
   local main_branch
   main_branch=$(current_branch "$repo_root")
 
-  # Iterate through worktree directories
   for dir in "$base_dir/${prefix}"*; do
     [ -d "$dir" ] || continue
 
     local branch
     branch=$(current_branch "$dir") || true
 
-    if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
-      log_warn "Skipping $dir (detached HEAD)"
-      skipped=$((skipped + 1))
-      continue
-    fi
-
-    # Skip if same as main repo branch
-    if [ "$branch" = "$main_branch" ]; then
-      continue
-    fi
-
-    # Check if worktree has uncommitted changes
-    if ! git -C "$dir" diff --quiet 2>/dev/null || \
-       ! git -C "$dir" diff --cached --quiet 2>/dev/null; then
-      log_warn "Skipping $branch (has uncommitted changes)"
-      skipped=$((skipped + 1))
-      continue
-    fi
+    # Skip main repo branch silently (not counted)
+    [ "$branch" = "$main_branch" ] && continue
 
-    # Check for untracked files
-    if [ -n "$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null)" ]; then
-      log_warn "Skipping $branch (has untracked files)"
+    if _clean_should_skip "$dir" "$branch"; then
       skipped=$((skipped + 1))
       continue
     fi
@@ -83,7 +93,6 @@ _clean_merged() {
       elif [ "$yes_mode" -eq 1 ] || prompt_yes_no "Remove worktree and delete branch '$branch'?"; then
         log_step "Removing worktree: $branch"
 
-        # Run pre-remove hooks (skip worktree on failure)
         if ! run_hooks_in preRemove "$dir" \
           REPO_ROOT="$repo_root" \
           WORKTREE_PATH="$dir" \
@@ -94,11 +103,9 @@ _clean_merged() {
         fi
 
         if remove_worktree "$dir" 0; then
-          # Delete the local branch (safe: already merged)
           git branch -d "$branch" 2>/dev/null || git branch -D "$branch" 2>/dev/null || true
           removed=$((removed + 1))
 
-          # Run post-remove hooks (worktree already removed, don't abort)
           if ! run_hooks postRemove \
             REPO_ROOT="$repo_root" \
             WORKTREE_PATH="$dir" \
@@ -111,7 +118,6 @@ _clean_merged() {
         skipped=$((skipped + 1))
       fi
     fi
-    # Branches without merged PRs are silently skipped (this is the normal case)
   done
 
   echo ""
diff --git a/lib/commands/editor.sh b/lib/commands/editor.sh
index 22ed002..c9f5f8f 100644
--- a/lib/commands/editor.sh
+++ b/lib/commands/editor.sh
@@ -4,15 +4,11 @@
 # shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_editor() {
   parse_args "--editor: value" "$@"
+  require_args 1 "Usage: git gtr editor <id|branch> [--editor <name>]"
 
-  local identifier="${_pa_positional[0]:-}"
+  local identifier="${_pa_positional[0]}"
   local editor="${_arg_editor:-}"
 
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr editor <id|branch> [--editor <name>]"
-    exit 1
-  fi
-
   # Get editor from flag or config (with .gtrconfig support)
   if [ -z "$editor" ]; then
     editor=$(_cfg_editor_default)
diff --git a/lib/commands/go.sh b/lib/commands/go.sh
index 354552d..3910598 100644
--- a/lib/commands/go.sh
+++ b/lib/commands/go.sh
@@ -4,11 +4,7 @@
 # shellcheck disable=SC2154  # _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_go() {
   parse_args "" "$@"
-
-  if [ "${#_pa_positional[@]}" -ne 1 ]; then
-    log_error "Usage: git gtr go <id|branch>"
-    exit 1
-  fi
+  require_args 1 "Usage: git gtr go <id|branch>"
 
   local identifier="${_pa_positional[0]}"
   resolve_repo_context || exit 1
diff --git a/lib/commands/remove.sh b/lib/commands/remove.sh
index 8e76bcc..fda759e 100644
--- a/lib/commands/remove.sh
+++ b/lib/commands/remove.sh
@@ -9,15 +9,12 @@ cmd_remove() {
 --force"
   parse_args "$_spec" "$@"
 
+  require_args 1 "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
+
   local delete_branch="${_arg_delete_branch:-0}"
   local yes_mode="${_arg_yes:-0}"
   local force="${_arg_force:-0}"
 
-  if [ ${#_pa_positional[@]} -eq 0 ]; then
-    log_error "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
-    exit 1
-  fi
-
   resolve_repo_context || exit 1
 
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
diff --git a/lib/commands/rename.sh b/lib/commands/rename.sh
index 2f0a6d8..9816278 100644
--- a/lib/commands/rename.sh
+++ b/lib/commands/rename.sh
@@ -8,17 +8,13 @@ cmd_rename() {
 --yes"
   parse_args "$_spec" "$@"
 
-  local old_identifier="${_pa_positional[0]:-}"
-  local new_name="${_pa_positional[1]:-}"
+  require_args 2 "Usage: git gtr mv <old> <new> [--force] [--yes]"
+
+  local old_identifier="${_pa_positional[0]}"
+  local new_name="${_pa_positional[1]}"
   local force="${_arg_force:-0}"
   local yes_mode="${_arg_yes:-0}"
 
-  # Validate arguments
-  if [ -z "$old_identifier" ] || [ -z "$new_name" ]; then
-    log_error "Usage: git gtr mv <old> <new> [--force] [--yes]"
-    exit 1
-  fi
-
   resolve_repo_context || exit 1
 
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
diff --git a/lib/copy.sh b/lib/copy.sh
index fa095c1..7a2027c 100644
--- a/lib/copy.sh
+++ b/lib/copy.sh
@@ -117,6 +117,37 @@ _copy_pattern_file() {
   fi
 }
 
+# Process a single glob pattern: expand via globstar or find fallback, copy matching files.
+# Must be called from within the source directory with shell options already configured.
+# Prints the number of files copied to stdout.
+# Usage: _expand_and_copy_pattern <pattern> <dst_root> <excludes> <preserve_paths> <dry_run> <have_globstar>
+_expand_and_copy_pattern() {
+  local pattern="$1" dst_root="$2" excludes="$3"
+  local preserve_paths="$4" dry_run="$5" have_globstar="$6"
+  local count=0
+
+  if [ "$have_globstar" -eq 0 ] && echo "$pattern" | grep -q '\*\*'; then
+    # Fallback to find for ** patterns on Bash 3.2
+    while IFS= read -r file; do
+      if _copy_pattern_file "$file" "$dst_root" "$excludes" "$preserve_paths" "$dry_run"; then
+        count=$((count + 1))
+      fi
+    done <<EOF
+$(find . -path "./$pattern" -type f 2>/dev/null || true)
+EOF
+  else
+    # Use native Bash glob expansion (supports ** if available)
+    for file in $pattern; do
+      [ -f "$file" ] || continue
+      if _copy_pattern_file "$file" "$dst_root" "$excludes" "$preserve_paths" "$dry_run"; then
+        count=$((count + 1))
+      fi
+    done
+  fi
+
+  printf "%s" "$count"
+}
+
 # Copy files matching patterns from source to destination
 # Usage: copy_patterns src_root dst_root includes excludes [preserve_paths] [dry_run]
 # includes: newline-separated glob patterns to include
@@ -124,31 +155,18 @@ _copy_pattern_file() {
 # preserve_paths: true (default) to preserve directory structure
 # dry_run: true to only show what would be copied without copying
 copy_patterns() {
-  local src_root="$1"
-  local dst_root="$2"
-  local includes="$3"
-  local excludes="$4"
-  local preserve_paths="${5:-true}"
-  local dry_run="${6:-false}"
+  local src_root="$1" dst_root="$2" includes="$3" excludes="$4"
+  local preserve_paths="${5:-true}" dry_run="${6:-false}"
 
-  if [ -z "$includes" ]; then
-    # No patterns to copy
-    return 0
-  fi
+  [ -z "$includes" ] && return 0
 
-  # Change to source directory
   local old_pwd
   old_pwd=$(pwd)
   cd "$src_root" || return 1
 
-  # Save current shell options
+  # Save and configure shell options for glob expansion
   local shopt_save
   shopt_save="$(shopt -p nullglob dotglob globstar 2>/dev/null || true)"
-
-  # Try to enable globstar for ** patterns (Bash 4.0+)
-  # nullglob: patterns that don't match expand to nothing
-  # dotglob: * matches hidden files
-  # globstar: ** matches directories recursively
   local have_globstar=0
   if shopt -s globstar 2>/dev/null; then
     have_globstar=1
@@ -157,44 +175,22 @@ copy_patterns() {
 
   local copied_count=0
 
-  # Process each include pattern (avoid pipeline subshell)
   while IFS= read -r pattern; do
     [ -z "$pattern" ] && continue
 
-    # Security: reject absolute paths and parent directory traversal
     if _is_unsafe_path "$pattern"; then
       log_warn "Skipping unsafe pattern (absolute path or '..' path segment): $pattern"
       continue
     fi
 
-    # Detect if pattern uses ** (requires globstar)
-    if [ "$have_globstar" -eq 0 ] && echo "$pattern" | grep -q '\*\*'; then
-      # Fallback to find for ** patterns on Bash 3.2
-      while IFS= read -r file; do
-        if _copy_pattern_file "$file" "$dst_root" "$excludes" "$preserve_paths" "$dry_run"; then
-          copied_count=$((copied_count + 1))
-        fi
-      done <<EOF
-$(find . -path "./$pattern" -type f 2>/dev/null || true)
-EOF
-    else
-      # Use native Bash glob expansion (supports ** if available)
-      for file in $pattern; do
-        # Skip if not a file
-        [ -f "$file" ] || continue
-
-        if _copy_pattern_file "$file" "$dst_root" "$excludes" "$preserve_paths" "$dry_run"; then
-          copied_count=$((copied_count + 1))
-        fi
-      done
-    fi
+    local pattern_copied
+    pattern_copied=$(_expand_and_copy_pattern "$pattern" "$dst_root" "$excludes" "$preserve_paths" "$dry_run" "$have_globstar")
+    copied_count=$((copied_count + pattern_copied))
   done <<EOF
 $includes
 EOF
 
-  # Restore previous shell options
   eval "$shopt_save" 2>/dev/null || true
-
   cd "$old_pwd" || return 1
 
   if [ "$copied_count" -gt 0 ]; then
diff --git a/lib/core.sh b/lib/core.sh
index ea2d34c..5bd4266 100644
--- a/lib/core.sh
+++ b/lib/core.sh
@@ -324,26 +324,13 @@ _try_worktree_add() {
   return 1
 }
 
-# Create a new git worktree
-# Usage: create_worktree base_dir prefix branch_name from_ref track_mode [skip_fetch] [force] [custom_name] [folder_override]
-# track_mode: auto, remote, local, or none
-# skip_fetch: 0 (default, fetch) or 1 (skip)
-# force: 0 (default, check branch) or 1 (allow same branch in multiple worktrees)
-# custom_name: optional custom name suffix (e.g., "backend" creates "feature-auth-backend")
-# folder_override: optional complete folder name override (replaces default naming)
-create_worktree() {
-  local base_dir="$1"
-  local prefix="$2"
-  local branch_name="$3"
-  local from_ref="$4"
-  local track_mode="${5:-auto}"
-  local skip_fetch="${6:-0}"
-  local force="${7:-0}"
-  local custom_name="${8:-}"
-  local folder_override="${9:-}"
-  local sanitized_name worktree_path
-
-  # Construct folder name
+# Build and validate folder name from branch/custom/override.
+# Prints sanitized folder name on success; returns 1 on validation failure.
+# Usage: _resolve_folder_name <branch_name> [custom_name] [folder_override]
+_resolve_folder_name() {
+  local branch_name="$1" custom_name="${2:-}" folder_override="${3:-}"
+  local sanitized_name
+
   if [ -n "$folder_override" ]; then
     sanitized_name=$(sanitize_branch_name "$folder_override")
   elif [ -n "$custom_name" ]; then
@@ -352,7 +339,6 @@ create_worktree() {
     sanitized_name=$(sanitize_branch_name "$branch_name")
   fi
 
-  # Validate sanitized name is not empty or path traversal attempt
   if [ -z "$sanitized_name" ] || [ "$sanitized_name" = "." ] || [ "$sanitized_name" = ".." ]; then
     if [ -n "$folder_override" ]; then
       log_error "Invalid --folder value: $folder_override"
@@ -362,38 +348,73 @@ create_worktree() {
     return 1
   fi
 
-  worktree_path="$base_dir/${prefix}${sanitized_name}"
-  local force_args=()
+  printf "%s" "$sanitized_name"
+}
 
-  if [ "$force" -eq 1 ]; then
-    force_args=(--force)
+# Check if a branch exists on remote and/or locally.
+# Sets globals: _wt_remote_exists, _wt_local_exists (0 or 1)
+# Usage: _check_branch_refs <branch_name>
+declare _wt_remote_exists _wt_local_exists
+_check_branch_refs() {
+  _wt_remote_exists=0
+  _wt_local_exists=0
+  git show-ref --verify --quiet "refs/remotes/origin/$1" && _wt_remote_exists=1
+  git show-ref --verify --quiet "refs/heads/$1" && _wt_local_exists=1
+  return 0
+}
+
+# Auto-track: create local tracking branch from remote if needed, then add worktree.
+# Usage: _worktree_add_tracked <worktree_path> <branch_name> [force_args...]
+# shellcheck disable=SC2317  # Called indirectly from create_worktree
+_worktree_add_tracked() {
+  local wt_path="$1" branch_name="$2"
+  shift 2
+
+  log_step "Branch '$branch_name' exists on remote"
+  if git branch --track "$branch_name" "origin/$branch_name" >/dev/null 2>&1; then
+    log_info "Created local branch tracking origin/$branch_name"
   fi
+  _try_worktree_add "$wt_path" "" \
+    "Worktree created tracking origin/$branch_name" \
+    "$@" "$branch_name"
+}
+
+# Create a new git worktree
+# Usage: create_worktree base_dir prefix branch_name from_ref track_mode [skip_fetch] [force] [custom_name] [folder_override]
+# track_mode: auto, remote, local, or none
+# skip_fetch: 0 (default, fetch) or 1 (skip)
+# force: 0 (default, check branch) or 1 (allow same branch in multiple worktrees)
+# custom_name: optional custom name suffix (e.g., "backend" creates "feature-auth-backend")
+# folder_override: optional complete folder name override (replaces default naming)
+create_worktree() {
+  local base_dir="$1" prefix="$2" branch_name="$3" from_ref="$4"
+  local track_mode="${5:-auto}" skip_fetch="${6:-0}" force="${7:-0}"
+  local custom_name="${8:-}" folder_override="${9:-}"
+
+  local sanitized_name
+  sanitized_name=$(_resolve_folder_name "$branch_name" "$custom_name" "$folder_override") || return 1
+
+  local worktree_path="$base_dir/${prefix}${sanitized_name}"
+  local force_args=()
+  [ "$force" -eq 1 ] && force_args=(--force)
 
-  # Check if worktree already exists
   if [ -d "$worktree_path" ]; then
     log_error "Worktree $sanitized_name already exists at $worktree_path"
     return 1
   fi
 
-  # Create base directory if needed
   mkdir -p "$base_dir"
 
-  # Fetch latest refs (unless --no-fetch)
   if [ "$skip_fetch" -eq 0 ]; then
     log_step "Fetching remote branches..."
     git fetch origin 2>/dev/null || log_warn "Could not fetch from origin"
   fi
 
-  local remote_exists=0
-  local local_exists=0
-
-  git show-ref --verify --quiet "refs/remotes/origin/$branch_name" && remote_exists=1
-  git show-ref --verify --quiet "refs/heads/$branch_name" && local_exists=1
+  _check_branch_refs "$branch_name"
 
   case "$track_mode" in
     remote)
-      if [ "$remote_exists" -eq 1 ]; then
-        # Try creating with -b first (new local branch tracking remote), fallback to direct checkout
+      if [ "$_wt_remote_exists" -eq 1 ]; then
         _try_worktree_add "$worktree_path" \
           "Creating worktree from remote branch origin/$branch_name" \
           "Worktree created tracking origin/$branch_name" \
@@ -407,7 +428,7 @@ create_worktree() {
       ;;
 
     local)
-      if [ "$local_exists" -eq 1 ]; then
+      if [ "$_wt_local_exists" -eq 1 ]; then
         _try_worktree_add "$worktree_path" \
           "Creating worktree from local branch $branch_name" \
           "Worktree created with local branch $branch_name" \
@@ -427,16 +448,9 @@ create_worktree() {
       ;;
 
     auto|*)
-      if [ "$remote_exists" -eq 1 ] && [ "$local_exists" -eq 0 ]; then
-        # Remote exists, no local branch — create local tracking branch first
-        log_step "Branch '$branch_name' exists on remote"
-        if git branch --track "$branch_name" "origin/$branch_name" >/dev/null 2>&1; then
-          log_info "Created local branch tracking origin/$branch_name"
-        fi
-        _try_worktree_add "$worktree_path" "" \
-          "Worktree created tracking origin/$branch_name" \
-          "${force_args[@]}" "$branch_name" && return 0
-      elif [ "$local_exists" -eq 1 ]; then
+      if [ "$_wt_remote_exists" -eq 1 ] && [ "$_wt_local_exists" -eq 0 ]; then
+        _worktree_add_tracked "$worktree_path" "$branch_name" "${force_args[@]}" && return 0
+      elif [ "$_wt_local_exists" -eq 1 ]; then
         _try_worktree_add "$worktree_path" \
           "Using existing local branch $branch_name" \
           "Worktree created with local branch $branch_name" \
diff --git a/tests/cmd_clean.bats b/tests/cmd_clean.bats
new file mode 100644
index 0000000..0e4d5e7
--- /dev/null
+++ b/tests/cmd_clean.bats
@@ -0,0 +1,78 @@
+#!/usr/bin/env bats
+# Tests for cmd_clean in lib/commands/clean.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_commands
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+# ── Basic clean (prune + empty dirs) ────────────────────────────────────────
+
+@test "cmd_clean runs without errors" {
+  run cmd_clean
+  [ "$status" -eq 0 ]
+}
+
+@test "cmd_clean removes empty directories" {
+  mkdir -p "$TEST_WORKTREES_DIR/empty-dir"
+  cmd_clean
+  [ ! -d "$TEST_WORKTREES_DIR/empty-dir" ]
+}
+
+@test "cmd_clean preserves non-empty directories" {
+  create_test_worktree "keep-me"
+  cmd_clean
+  [ -d "$TEST_WORKTREES_DIR/keep-me" ]
+}
+
+@test "cmd_clean handles missing worktrees dir" {
+  # Don't create any worktrees - base_dir doesn't exist
+  run cmd_clean
+  [ "$status" -eq 0 ]
+}
+
+# ── _clean_detect_provider ──────────────────────────────────────────────────
+
+@test "_clean_detect_provider fails without remote" {
+  run _clean_detect_provider
+  [ "$status" -eq 1 ]
+}
+
+# ── _clean_should_skip ──────────────────────────────────────────────────────
+
+@test "_clean_should_skip skips detached HEAD" {
+  _clean_should_skip "/some/dir" "(detached)"
+  # Returns 0 = should skip
+}
+
+@test "_clean_should_skip skips empty branch" {
+  _clean_should_skip "/some/dir" ""
+  # Returns 0 = should skip
+}
+
+@test "_clean_should_skip skips dirty worktree" {
+  create_test_worktree "dirty-test"
+  echo "dirty" > "$TEST_WORKTREES_DIR/dirty-test/untracked.txt"
+  git -C "$TEST_WORKTREES_DIR/dirty-test" add untracked.txt
+  _clean_should_skip "$TEST_WORKTREES_DIR/dirty-test" "dirty-test"
+  # Returns 0 = should skip (staged changes)
+}
+
+@test "_clean_should_skip skips worktree with untracked files" {
+  create_test_worktree "untracked-test"
+  echo "new" > "$TEST_WORKTREES_DIR/untracked-test/newfile.txt"
+  _clean_should_skip "$TEST_WORKTREES_DIR/untracked-test" "untracked-test"
+  # Returns 0 = should skip
+}
+
+@test "_clean_should_skip does not skip clean worktree" {
+  create_test_worktree "clean-wt"
+  run _clean_should_skip "$TEST_WORKTREES_DIR/clean-wt" "clean-wt"
+  [ "$status" -eq 1 ]  # 1 = don't skip
+}
diff --git a/tests/cmd_create_integration.bats b/tests/cmd_create_integration.bats
new file mode 100644
index 0000000..6920537
--- /dev/null
+++ b/tests/cmd_create_integration.bats
@@ -0,0 +1,70 @@
+#!/usr/bin/env bats
+# Integration tests for cmd_create in lib/commands/create.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_commands
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+# Note: --from HEAD is needed because test repos have no origin remote,
+# so resolve_default_branch can't detect a default branch.
+
+@test "cmd_create creates worktree with basic args" {
+  cmd_create new-feature --from HEAD --no-fetch --yes
+  [ -d "$TEST_WORKTREES_DIR/new-feature" ]
+}
+
+@test "cmd_create creates worktree with --track none" {
+  cmd_create track-none --from HEAD --track none --no-fetch --yes
+  [ -d "$TEST_WORKTREES_DIR/track-none" ]
+}
+
+@test "cmd_create creates worktree with --name suffix" {
+  cmd_create named-branch --from HEAD --name backend --no-fetch --yes
+  [ -d "$TEST_WORKTREES_DIR/named-branch-backend" ]
+}
+
+@test "cmd_create creates worktree with --folder override" {
+  cmd_create folder-branch --from HEAD --folder my-custom --no-fetch --yes
+  [ -d "$TEST_WORKTREES_DIR/my-custom" ]
+}
+
+@test "cmd_create rejects --folder + --name together" {
+  run cmd_create test --folder a --name b --no-fetch --yes
+  [ "$status" -eq 1 ]
+}
+
+@test "cmd_create rejects --force without --name or --folder" {
+  run cmd_create test --force --no-fetch --yes
+  [ "$status" -eq 1 ]
+}
+
+@test "cmd_create --no-copy skips file copying" {
+  git config --add gtr.copy.include ".env"
+  echo "secret" > "$TEST_REPO/.env"
+  cmd_create no-copy-test --from HEAD --no-copy --no-fetch --yes
+  [ ! -f "$TEST_WORKTREES_DIR/no-copy-test/.env" ]
+}
+
+@test "cmd_create --no-hooks skips post-create hooks" {
+  git config --add gtr.hook.postCreate "touch hook-ran"
+  cmd_create no-hook-test --from HEAD --no-hooks --no-fetch --yes
+  [ ! -f "$TEST_WORKTREES_DIR/no-hook-test/hook-ran" ]
+}
+
+@test "cmd_create runs post-create hooks when enabled" {
+  git config --add gtr.hook.postCreate 'touch "$WORKTREE_PATH/hook-ran"'
+  cmd_create hook-test --from HEAD --no-fetch --yes
+  [ -f "$TEST_WORKTREES_DIR/hook-test/hook-ran" ]
+}
+
+@test "cmd_create sanitizes slashed branch name for folder" {
+  cmd_create feature/deep --from HEAD --no-fetch --yes
+  [ -d "$TEST_WORKTREES_DIR/feature-deep" ]
+}
diff --git a/tests/cmd_go.bats b/tests/cmd_go.bats
new file mode 100644
index 0000000..166fb39
--- /dev/null
+++ b/tests/cmd_go.bats
@@ -0,0 +1,53 @@
+#!/usr/bin/env bats
+# Tests for cmd_go in lib/commands/go.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_commands
+  create_test_worktree "go-test"
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+@test "cmd_go prints worktree path to stdout" {
+  run cmd_go go-test
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"$TEST_WORKTREES_DIR/go-test"* ]]
+}
+
+@test "cmd_go resolves ID 1 to main repo" {
+  run cmd_go 1
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"$TEST_REPO"* ]]
+}
+
+@test "cmd_go fails with no arguments" {
+  run cmd_go
+  [ "$status" -eq 1 ]
+}
+
+@test "cmd_go fails for unknown branch" {
+  run cmd_go nonexistent
+  [ "$status" -eq 1 ]
+}
+
+@test "cmd_go resolves slashed branch" {
+  create_test_worktree "feature/nav"
+  run cmd_go "feature/nav"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"feature-nav"* ]]
+}
+
+@test "cmd_go prints human messages to stderr" {
+  local stdout stderr
+  stdout=$(cmd_go go-test 2>/dev/null)
+  stderr=$(cmd_go go-test 2>&1 >/dev/null)
+  # stdout should be just the path
+  [[ "$stdout" == *"$TEST_WORKTREES_DIR/go-test"* ]]
+  # stderr should contain human-readable info
+  [[ "$stderr" == *"Worktree"* ]] || [[ "$stderr" == *"Branch"* ]]
+}
diff --git a/tests/cmd_list.bats b/tests/cmd_list.bats
new file mode 100644
index 0000000..e652bc4
--- /dev/null
+++ b/tests/cmd_list.bats
@@ -0,0 +1,59 @@
+#!/usr/bin/env bats
+# Tests for cmd_list in lib/commands/list.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_commands
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+@test "cmd_list shows main repo" {
+  run cmd_list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"[main repo]"* ]]
+}
+
+@test "cmd_list shows created worktree" {
+  create_test_worktree "list-me"
+  run cmd_list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"list-me"* ]]
+}
+
+@test "cmd_list --porcelain outputs TSV format" {
+  create_test_worktree "porcelain-test"
+  local output
+  output=$(cmd_list --porcelain)
+  # First line: main repo
+  local first_line
+  first_line=$(echo "$output" | head -1)
+  [[ "$first_line" == *"$TEST_REPO"* ]]
+  # Should contain tab-separated fields
+  [[ "$output" == *$'\t'* ]]
+}
+
+@test "cmd_list --porcelain includes worktree branch and status" {
+  create_test_worktree "tsv-test"
+  local output
+  output=$(cmd_list --porcelain)
+  # Worktree line should have: path<tab>branch<tab>status
+  [[ "$output" == *"tsv-test"*$'\t'*"ok"* ]]
+}
+
+@test "cmd_list with no worktrees still works" {
+  run cmd_list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Git Worktrees"* ]]
+}
+
+@test "cmd_list human format has header" {
+  run cmd_list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BRANCH"* ]]
+  [[ "$output" == *"PATH"* ]]
+}
diff --git a/tests/cmd_remove.bats b/tests/cmd_remove.bats
new file mode 100644
index 0000000..a926b91
--- /dev/null
+++ b/tests/cmd_remove.bats
@@ -0,0 +1,83 @@
+#!/usr/bin/env bats
+# Tests for cmd_remove in lib/commands/remove.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_commands
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+@test "cmd_remove removes a worktree" {
+  create_test_worktree "rm-me"
+  [ -d "$TEST_WORKTREES_DIR/rm-me" ]
+  cmd_remove rm-me
+  [ ! -d "$TEST_WORKTREES_DIR/rm-me" ]
+}
+
+@test "cmd_remove fails with no arguments" {
+  run cmd_remove
+  [ "$status" -eq 1 ]
+}
+
+@test "cmd_remove skips unknown branch and continues" {
+  # cmd_remove uses 'continue' for individual failures, not 'exit'
+  run cmd_remove nonexistent
+  [ "$status" -eq 0 ]
+}
+
+@test "cmd_remove cannot remove main repo" {
+  run cmd_remove 1
+  [ "$status" -eq 0 ]  # continues past error, doesn't exit
+  # Main repo should still exist
+  [ -d "$TEST_REPO" ]
+}
+
+@test "cmd_remove handles multiple worktrees" {
+  create_test_worktree "multi-a"
+  create_test_worktree "multi-b"
+  cmd_remove multi-a multi-b
+  [ ! -d "$TEST_WORKTREES_DIR/multi-a" ]
+  [ ! -d "$TEST_WORKTREES_DIR/multi-b" ]
+}
+
+@test "cmd_remove runs pre-remove hooks" {
+  create_test_worktree "hook-rm"
+  git config --add gtr.hook.preRemove "touch $TEST_REPO/pre-hook-ran"
+  cmd_remove hook-rm
+  [ -f "$TEST_REPO/pre-hook-ran" ]
+}
+
+@test "cmd_remove pre-remove hook failure blocks removal" {
+  create_test_worktree "hook-block"
+  git config --add gtr.hook.preRemove "exit 1"
+  run cmd_remove hook-block
+  # Worktree should still exist (hook blocked removal)
+  [ -d "$TEST_WORKTREES_DIR/hook-block" ]
+}
+
+@test "cmd_remove --force skips failed pre-remove hook" {
+  create_test_worktree "force-rm"
+  git config --add gtr.hook.preRemove "exit 1"
+  cmd_remove --force force-rm
+  [ ! -d "$TEST_WORKTREES_DIR/force-rm" ]
+}
+
+@test "cmd_remove runs post-remove hooks" {
+  create_test_worktree "post-rm"
+  git config --add gtr.hook.postRemove "touch $TEST_REPO/post-hook-ran"
+  cmd_remove post-rm
+  [ -f "$TEST_REPO/post-hook-ran" ]
+}
+
+@test "cmd_remove continues on individual failures" {
+  create_test_worktree "good-rm"
+  # Try to remove both a nonexistent and existing worktree
+  run cmd_remove nonexistent good-rm
+  # The good one should have been removed despite the bad one failing
+  [ ! -d "$TEST_WORKTREES_DIR/good-rm" ]
+}
diff --git a/tests/core_create_worktree.bats b/tests/core_create_worktree.bats
new file mode 100644
index 0000000..13109cc
--- /dev/null
+++ b/tests/core_create_worktree.bats
@@ -0,0 +1,141 @@
+#!/usr/bin/env bats
+# Tests for create_worktree and its helpers in lib/core.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_libs
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+# ── _resolve_folder_name ────────────────────────────────────────────────────
+
+@test "_resolve_folder_name sanitizes branch name" {
+  local result
+  result=$(_resolve_folder_name "feature/auth")
+  [ "$result" = "feature-auth" ]
+}
+
+@test "_resolve_folder_name appends custom name" {
+  local result
+  result=$(_resolve_folder_name "feature/auth" "backend")
+  [ "$result" = "feature-auth-backend" ]
+}
+
+@test "_resolve_folder_name uses folder override" {
+  local result
+  result=$(_resolve_folder_name "feature/auth" "" "my-folder")
+  [ "$result" = "my-folder" ]
+}
+
+@test "_resolve_folder_name rejects empty result" {
+  run _resolve_folder_name ""
+  [ "$status" -eq 1 ]
+}
+
+@test "_resolve_folder_name rejects dot" {
+  run _resolve_folder_name "."
+  [ "$status" -eq 1 ]
+}
+
+@test "_resolve_folder_name rejects double-dot" {
+  run _resolve_folder_name ".."
+  [ "$status" -eq 1 ]
+}
+
+# ── _check_branch_refs ──────────────────────────────────────────────────────
+
+@test "_check_branch_refs detects local branch" {
+  git branch local-only HEAD
+  _check_branch_refs "local-only"
+  [ "$_wt_local_exists" -eq 1 ]
+  [ "$_wt_remote_exists" -eq 0 ]
+}
+
+@test "_check_branch_refs sets both to 0 for unknown branch" {
+  _check_branch_refs "nonexistent-branch"
+  [ "$_wt_local_exists" -eq 0 ]
+  [ "$_wt_remote_exists" -eq 0 ]
+}
+
+# ── create_worktree ─────────────────────────────────────────────────────────
+
+@test "create_worktree creates directory with track=none" {
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "new-branch" "HEAD" "none" "1")
+  [ -d "$wt_path" ]
+  [ "$wt_path" = "$TEST_WORKTREES_DIR/new-branch" ]
+}
+
+@test "create_worktree uses local branch with track=local" {
+  git branch local-branch HEAD
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "local-branch" "HEAD" "local" "1")
+  [ -d "$wt_path" ]
+}
+
+@test "create_worktree fails for missing local branch with track=local" {
+  run create_worktree "$TEST_WORKTREES_DIR" "" "nope" "HEAD" "local" "1"
+  [ "$status" -eq 1 ]
+}
+
+@test "create_worktree fails for missing remote branch with track=remote" {
+  run create_worktree "$TEST_WORKTREES_DIR" "" "nope" "HEAD" "remote" "1"
+  [ "$status" -eq 1 ]
+}
+
+@test "create_worktree auto mode creates new branch when neither exists" {
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "auto-new" "HEAD" "auto" "1")
+  [ -d "$wt_path" ]
+}
+
+@test "create_worktree auto mode uses existing local branch" {
+  git branch existing-local HEAD
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "existing-local" "HEAD" "auto" "1")
+  [ -d "$wt_path" ]
+}
+
+@test "create_worktree rejects duplicate worktree" {
+  create_worktree "$TEST_WORKTREES_DIR" "" "dup-test" "HEAD" "none" "1" >/dev/null
+  run create_worktree "$TEST_WORKTREES_DIR" "" "dup-test" "HEAD" "none" "1"
+  [ "$status" -eq 1 ]
+}
+
+@test "create_worktree applies prefix to folder name" {
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "wt-" "prefixed" "HEAD" "none" "1")
+  [ "$wt_path" = "$TEST_WORKTREES_DIR/wt-prefixed" ]
+  [ -d "$wt_path" ]
+}
+
+@test "create_worktree applies custom name suffix" {
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "feature" "HEAD" "none" "1" "0" "backend")
+  [ "$wt_path" = "$TEST_WORKTREES_DIR/feature-backend" ]
+}
+
+@test "create_worktree applies folder override" {
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "any-branch" "HEAD" "none" "1" "0" "" "custom-dir")
+  [ "$wt_path" = "$TEST_WORKTREES_DIR/custom-dir" ]
+}
+
+@test "create_worktree creates base dir if needed" {
+  local nested="$TEST_WORKTREES_DIR/sub/trees"
+  local wt_path
+  wt_path=$(create_worktree "$nested" "" "nest-test" "HEAD" "none" "1")
+  [ -d "$nested" ]
+  [ -d "$wt_path" ]
+}
+
+@test "create_worktree sanitizes slashed branch for folder" {
+  local wt_path
+  wt_path=$(create_worktree "$TEST_WORKTREES_DIR" "" "feature/deep/path" "HEAD" "none" "1")
+  [ "$wt_path" = "$TEST_WORKTREES_DIR/feature-deep-path" ]
+}
diff --git a/tests/core_resolve_target.bats b/tests/core_resolve_target.bats
new file mode 100644
index 0000000..961a356
--- /dev/null
+++ b/tests/core_resolve_target.bats
@@ -0,0 +1,82 @@
+#!/usr/bin/env bats
+# Tests for resolve_target, unpack_target, resolve_worktree in lib/core.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_libs
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+@test "resolve_target ID 1 returns main repo with is_main=1" {
+  local result
+  result=$(resolve_target "1" "$TEST_REPO" "$TEST_WORKTREES_DIR" "")
+  [[ "$result" == "1"$'\t'"$TEST_REPO"* ]]
+}
+
+@test "resolve_target finds worktree by branch name" {
+  create_test_worktree "find-me"
+  local result
+  result=$(resolve_target "find-me" "$TEST_REPO" "$TEST_WORKTREES_DIR" "")
+  [[ "$result" == "0"$'\t'"$TEST_WORKTREES_DIR/find-me"$'\t'"find-me" ]]
+}
+
+@test "resolve_target resolves slashed branch to sanitized path" {
+  create_test_worktree "feature/login"
+  local result
+  result=$(resolve_target "feature/login" "$TEST_REPO" "$TEST_WORKTREES_DIR" "")
+  [[ "$result" == "0"$'\t'"$TEST_WORKTREES_DIR/feature-login"* ]]
+}
+
+@test "resolve_target returns 1 for unknown branch" {
+  run resolve_target "nonexistent" "$TEST_REPO" "$TEST_WORKTREES_DIR" ""
+  [ "$status" -eq 1 ]
+}
+
+@test "resolve_target matches current branch in main repo as is_main=1" {
+  local current
+  current=$(git rev-parse --abbrev-ref HEAD)
+  local result
+  result=$(resolve_target "$current" "$TEST_REPO" "$TEST_WORKTREES_DIR" "")
+  [[ "$result" == "1"$'\t'"$TEST_REPO"* ]]
+}
+
+@test "resolve_target handles prefix in path" {
+  create_worktree "$TEST_WORKTREES_DIR" "wt-" "prefixed" "HEAD" "none" "1" >/dev/null
+  local result
+  result=$(resolve_target "prefixed" "$TEST_REPO" "$TEST_WORKTREES_DIR" "wt-")
+  [[ "$result" == "0"$'\t'"$TEST_WORKTREES_DIR/wt-prefixed"* ]]
+}
+
+@test "unpack_target parses TSV into context globals" {
+  local tsv="0"$'\t'"/some/path"$'\t'"my-branch"
+  unpack_target "$tsv"
+  [ "$_ctx_is_main" = "0" ]
+  [ "$_ctx_worktree_path" = "/some/path" ]
+  [ "$_ctx_branch" = "my-branch" ]
+}
+
+@test "unpack_target parses main repo TSV" {
+  local tsv="1"$'\t'"/repo/root"$'\t'"main"
+  unpack_target "$tsv"
+  [ "$_ctx_is_main" = "1" ]
+  [ "$_ctx_worktree_path" = "/repo/root" ]
+  [ "$_ctx_branch" = "main" ]
+}
+
+@test "resolve_worktree sets context globals" {
+  create_test_worktree "ctx-test"
+  resolve_worktree "ctx-test" "$TEST_REPO" "$TEST_WORKTREES_DIR" ""
+  [ "$_ctx_is_main" = "0" ]
+  [ "$_ctx_worktree_path" = "$TEST_WORKTREES_DIR/ctx-test" ]
+  [ "$_ctx_branch" = "ctx-test" ]
+}
+
+@test "resolve_worktree returns 1 for unknown branch" {
+  run resolve_worktree "nope" "$TEST_REPO" "$TEST_WORKTREES_DIR" ""
+  [ "$status" -eq 1 ]
+}
diff --git a/tests/hooks.bats b/tests/hooks.bats
new file mode 100644
index 0000000..294b310
--- /dev/null
+++ b/tests/hooks.bats
@@ -0,0 +1,90 @@
+#!/usr/bin/env bats
+# Tests for lib/hooks.sh
+
+load test_helper
+
+setup() {
+  setup_integration_repo
+  source_gtr_libs
+}
+
+teardown() {
+  teardown_integration_repo
+}
+
+@test "run_hooks returns 0 when no hooks configured" {
+  run run_hooks postCreate REPO_ROOT="$TEST_REPO"
+  [ "$status" -eq 0 ]
+}
+
+@test "run_hooks executes single hook" {
+  git config --add gtr.hook.postCreate "touch $TEST_REPO/hook-ran"
+  run_hooks postCreate REPO_ROOT="$TEST_REPO"
+  [ -f "$TEST_REPO/hook-ran" ]
+}
+
+@test "run_hooks passes environment variables" {
+  git config --add gtr.hook.postCreate 'echo "$MY_VAR" > "$REPO_ROOT/env-test"'
+  run_hooks postCreate REPO_ROOT="$TEST_REPO" MY_VAR="hello-world"
+  [ "$(cat "$TEST_REPO/env-test")" = "hello-world" ]
+}
+
+@test "run_hooks returns 1 when hook fails" {
+  git config --add gtr.hook.preRemove "exit 1"
+  run run_hooks preRemove REPO_ROOT="$TEST_REPO"
+  [ "$status" -eq 1 ]
+}
+
+@test "run_hooks executes multiple hooks in order" {
+  git config --add gtr.hook.postCreate "echo first >> $TEST_REPO/order"
+  git config --add gtr.hook.postCreate "echo second >> $TEST_REPO/order"
+  run_hooks postCreate REPO_ROOT="$TEST_REPO"
+  [ "$(head -1 "$TEST_REPO/order")" = "first" ]
+  [ "$(tail -1 "$TEST_REPO/order")" = "second" ]
+}
+
+@test "run_hooks reports failure count when multiple hooks fail" {
+  git config --add gtr.hook.postCreate "exit 1"
+  git config --add gtr.hook.postCreate "exit 2"
+  run run_hooks postCreate REPO_ROOT="$TEST_REPO"
+  [ "$status" -eq 1 ]
+}
+
+@test "run_hooks isolates hook side effects in subshell" {
+  git config --add gtr.hook.postCreate "MY_LEAK=leaked"
+  run_hooks postCreate REPO_ROOT="$TEST_REPO"
+  [ -z "${MY_LEAK:-}" ]
+}
+
+@test "run_hooks_in changes to target directory" {
+  mkdir -p "$TEST_REPO/subdir"
+  git config --add gtr.hook.postCreate 'pwd > "$REPO_ROOT/cwd-test"'
+  run_hooks_in postCreate "$TEST_REPO/subdir" REPO_ROOT="$TEST_REPO"
+  [ "$(cat "$TEST_REPO/cwd-test")" = "$TEST_REPO/subdir" ]
+}
+
+@test "run_hooks_in restores original directory" {
+  mkdir -p "$TEST_REPO/subdir"
+  local before_pwd
+  before_pwd=$(pwd)
+  run_hooks_in postCreate "$TEST_REPO/subdir" REPO_ROOT="$TEST_REPO"
+  [ "$(pwd)" = "$before_pwd" ]
+}
+
+@test "run_hooks_in returns 1 for nonexistent directory" {
+  run run_hooks_in postCreate "/nonexistent/path" REPO_ROOT="$TEST_REPO"
+  [ "$status" -eq 1 ]
+}
+
+@test "run_hooks_in propagates hook failure" {
+  mkdir -p "$TEST_REPO/subdir"
+  git config --add gtr.hook.preRemove "exit 1"
+  run run_hooks_in preRemove "$TEST_REPO/subdir" REPO_ROOT="$TEST_REPO"
+  [ "$status" -eq 1 ]
+}
+
+@test "run_hooks REPO_ROOT and BRANCH env vars available" {
+  git config --add gtr.hook.postCreate 'echo "$REPO_ROOT|$BRANCH" > "$REPO_ROOT/vars"'
+  run_hooks postCreate REPO_ROOT="$TEST_REPO" BRANCH="test-branch"
+  [ "$(cat "$TEST_REPO/vars")" = "$TEST_REPO|test-branch" ]
+}
diff --git a/tests/test_helper.bash b/tests/test_helper.bash
index 0c1d264..1a5c2ae 100644
--- a/tests/test_helper.bash
+++ b/tests/test_helper.bash
@@ -73,3 +73,36 @@ source_gtr_libs() {
   # shellcheck disable=SC1091
   . "$PROJECT_ROOT/lib/adapters.sh"
 }
+
+# Source command files + launch.sh (for cmd_* function testing)
+source_gtr_commands() {
+  source_gtr_libs
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/lib/launch.sh"
+  for cmd_file in "$PROJECT_ROOT"/lib/commands/*.sh; do
+    # shellcheck disable=SC1090
+    . "$cmd_file"
+  done
+}
+
+# Create a worktree quickly for testing (skips hooks/copy/fetch)
+# Usage: create_test_worktree <branch>
+# Sets: TEST_WT_PATH (path to created worktree)
+create_test_worktree() {
+  local branch="$1"
+  TEST_WT_PATH=$(create_worktree "$TEST_WORKTREES_DIR" "" "$branch" "HEAD" "none" "1" "0")
+}
+
+# Create a stub CLI in PATH for provider testing
+# Usage: mock_provider_cli <name> <exit_code> [stdout]
+mock_provider_cli() {
+  local name="$1" exit_code="${2:-0}" stdout="${3:-}"
+  MOCK_BIN_DIR=$(mktemp -d)
+  cat > "$MOCK_BIN_DIR/$name" <<SCRIPT
+#!/bin/bash
+echo "$stdout"
+exit $exit_code
+SCRIPT
+  chmod +x "$MOCK_BIN_DIR/$name"
+  export PATH="$MOCK_BIN_DIR:$PATH"
+}

From c05ca37230503b86235f0002ff55ea57347dbb14 Mon Sep 17 00:00:00 2001
From: Tom Elizaga <tom.elizaga@gmail.com>
Date: Wed, 11 Feb 2026 20:52:49 -0800
Subject: [PATCH 19/19] fix: improve directory handling and test execution in
 clean command

- Updated the `clean.sh` script to enhance the logic for finding empty directories by using `grep -Fxv` for better accuracy.
- Modified tests in `cmd_clean.bats` and `hooks.bats` to use `run` for executing commands, improving consistency in test status checks and output handling.
- Ensured that hooks in `hooks.bats` reference the correct variable for repository paths, enhancing portability and reliability of hook execution.
---
 lib/commands/clean.sh |  2 +-
 tests/cmd_clean.bats  | 16 ++++++++--------
 tests/hooks.bats      |  6 +++---
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/lib/commands/clean.sh b/lib/commands/clean.sh
index fa8fea2..929f078 100644
--- a/lib/commands/clean.sh
+++ b/lib/commands/clean.sh
@@ -159,7 +159,7 @@ cmd_clean() {
   # Find and remove empty directories
   local cleaned=0
   local empty_dirs
-  empty_dirs=$(find "$base_dir" -maxdepth 1 -type d -empty 2>/dev/null | grep -v "^${base_dir}$" || true)
+  empty_dirs=$(find "$base_dir" -maxdepth 1 -type d -empty 2>/dev/null | grep -Fxv "$base_dir" || true)
 
   if [ -n "$empty_dirs" ]; then
     while IFS= read -r dir; do
diff --git a/tests/cmd_clean.bats b/tests/cmd_clean.bats
index 0e4d5e7..fa8031d 100644
--- a/tests/cmd_clean.bats
+++ b/tests/cmd_clean.bats
@@ -47,28 +47,28 @@ teardown() {
 # ── _clean_should_skip ──────────────────────────────────────────────────────
 
 @test "_clean_should_skip skips detached HEAD" {
-  _clean_should_skip "/some/dir" "(detached)"
-  # Returns 0 = should skip
+  run _clean_should_skip "/some/dir" "(detached)"
+  [ "$status" -eq 0 ]
 }
 
 @test "_clean_should_skip skips empty branch" {
-  _clean_should_skip "/some/dir" ""
-  # Returns 0 = should skip
+  run _clean_should_skip "/some/dir" ""
+  [ "$status" -eq 0 ]
 }
 
 @test "_clean_should_skip skips dirty worktree" {
   create_test_worktree "dirty-test"
   echo "dirty" > "$TEST_WORKTREES_DIR/dirty-test/untracked.txt"
   git -C "$TEST_WORKTREES_DIR/dirty-test" add untracked.txt
-  _clean_should_skip "$TEST_WORKTREES_DIR/dirty-test" "dirty-test"
-  # Returns 0 = should skip (staged changes)
+  run _clean_should_skip "$TEST_WORKTREES_DIR/dirty-test" "dirty-test"
+  [ "$status" -eq 0 ]
 }
 
 @test "_clean_should_skip skips worktree with untracked files" {
   create_test_worktree "untracked-test"
   echo "new" > "$TEST_WORKTREES_DIR/untracked-test/newfile.txt"
-  _clean_should_skip "$TEST_WORKTREES_DIR/untracked-test" "untracked-test"
-  # Returns 0 = should skip
+  run _clean_should_skip "$TEST_WORKTREES_DIR/untracked-test" "untracked-test"
+  [ "$status" -eq 0 ]
 }
 
 @test "_clean_should_skip does not skip clean worktree" {
diff --git a/tests/hooks.bats b/tests/hooks.bats
index 294b310..d3ee690 100644
--- a/tests/hooks.bats
+++ b/tests/hooks.bats
@@ -18,7 +18,7 @@ teardown() {
 }
 
 @test "run_hooks executes single hook" {
-  git config --add gtr.hook.postCreate "touch $TEST_REPO/hook-ran"
+  git config --add gtr.hook.postCreate 'touch "$REPO_ROOT/hook-ran"'
   run_hooks postCreate REPO_ROOT="$TEST_REPO"
   [ -f "$TEST_REPO/hook-ran" ]
 }
@@ -36,8 +36,8 @@ teardown() {
 }
 
 @test "run_hooks executes multiple hooks in order" {
-  git config --add gtr.hook.postCreate "echo first >> $TEST_REPO/order"
-  git config --add gtr.hook.postCreate "echo second >> $TEST_REPO/order"
+  git config --add gtr.hook.postCreate 'echo first >> "$REPO_ROOT/order"'
+  git config --add gtr.hook.postCreate 'echo second >> "$REPO_ROOT/order"'
   run_hooks postCreate REPO_ROOT="$TEST_REPO"
   [ "$(head -1 "$TEST_REPO/order")" = "first" ]
   [ "$(tail -1 "$TEST_REPO/order")" = "second" ]