npx claudepluginhub manifoldlogic/claude-code-plugins --plugin devxThis skill uses the workspace's default tool permissions.
**Last Updated:** 2026-03-16
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Last Updated: 2026-03-16
Script Source: plugins/devx/skills/worktree-teardown/scripts/teardown-worktree.sh
The teardown-worktree.sh script orchestrates the complete worktree teardown workflow by combining cmux workspace closure with worktree cleanup in a single command:
cmux-ssh.sh list-workspaces)cmux-ssh.sh close-workspace)cleanup-worktree.sh (ticket detection, confirmation, git cleanup, VS Code workspace update)This is the teardown counterpart to setup-worktree.sh. Where setup creates worktree first then cmux workspace, teardown reverses the order: closes cmux workspace first, then removes worktree.
Unlike running cleanup-worktree.sh manually, teardown-worktree.sh also closes the cmux terminal workspace associated with the worktree, providing end-to-end environment teardown.
KEY FEATURES:
cmux Execution Context: cmux terminal commands in this skill execute via SSH to the macOS host using
cmux-ssh.sh. The script is not on PATH and must be invoked by absolute path:$CMUX_PLUGIN_DIR/skills/terminal-management/scripts/cmux-ssh.sh. See the cmux terminal-management SKILL.md for the full SSH execution model.
--dry-run to see all planned operations without making changes--skip-cmux to bypass cmux workspace closure entirely--keep-branch to remove the worktree but preserve the branch-y or --yes to skip the confirmation prompt in cleanup-worktree.shRequired:
cleanup-worktree.sh at $CLEANUP_WORKTREE_SCRIPT or /workspace/.devcontainer/scripts/cleanup-worktree.shOptional (graceful degradation when absent):
cmux-check.sh and cmux-ssh.sh at $CMUX_PLUGIN_DIR/skills/terminal-management/scripts/ -- cmux steps skipped if not found or if cmux-check.sh returns non-zerocrewchief worktree) -- required by cleanup-worktree.sh for worktree removalworkspace-folder.sh -- required by cleanup-worktree.sh for VS Code workspace update (skipped if not found)# Check cleanup-worktree.sh
ls /workspace/.devcontainer/scripts/cleanup-worktree.sh
# Check cmux scripts
ls "$CMUX_PLUGIN_DIR/skills/terminal-management/scripts/cmux-check.sh"
ls "$CMUX_PLUGIN_DIR/skills/terminal-management/scripts/cmux-ssh.sh"
# Check CrewChief CLI
command -v crewchief
teardown-worktree.sh <worktree-name> --repo <repository> [OPTIONS]
Both worktree-name and --repo are required. The worktree name is typically a ticket ID (e.g., DEVX-1001, TICKET-123).
worktree-name -- Name of the worktree to tear down (positional argument, typically a ticket ID)-r, --repo REPO -- Repository name-y, --yes -- Skip confirmation prompt (passed to cleanup-worktree.sh)--keep-branch -- Do not delete the git branch (passed to cleanup-worktree.sh)--skip-cmux -- Skip cmux workspace closure (steps 2-3)--skip-workspace -- Skip VS Code workspace update (passed to cleanup-worktree.sh)--dry-run -- Preview planned operations without making changes--verbose -- Show detailed cmux-ssh.sh and cleanup-worktree.sh output-h, --help -- Show help message and exitCMUX_PLUGIN_DIR -- Path to cmux plugin directory (default: /workspace/repos/claude-code-plugins/claude-code-plugins/plugins/cmux)CLEANUP_WORKTREE_SCRIPT -- Path to cleanup-worktree.sh (default: /workspace/.devcontainer/scripts/cleanup-worktree.sh)The --dry-run flag previews all planned operations without making any changes. It resolves all parameters, validates the configuration, and shows exactly what commands would run.
Example invocation:
teardown-worktree.sh TICKET-1 --repo crewchief --dry-run
Expected output format:
=== DRY RUN: teardown-worktree ===
Worktree: TICKET-1
Repo: crewchief
Flags:
Skip cmux: false
Skip workspace: false
Keep branch: false
Yes (skip confirm): false
Verbose: false
Planned operations:
[DRY-RUN] Step 1: Validate prerequisites
Check: cleanup-worktree.sh, cmux-check.sh
[DRY-RUN] Step 2: Identify cmux workspace
<CMUX_SSH_SCRIPT> list-workspaces
Match workspace name: TICKET-1
[DRY-RUN] Step 3: Close cmux workspace
<CMUX_SSH_SCRIPT> close-workspace --workspace <workspace_id>
[DRY-RUN] Step 4: Cleanup worktree (delegate to cleanup-worktree.sh)
<CLEANUP_WORKTREE_SCRIPT> TICKET-1 --repo crewchief --dry-run
=== END DRY RUN ===
With --skip-cmux, steps 2 and 3 show the skip reason:
[DRY-RUN] Step 2: Identify cmux workspace [SKIPPED: --skip-cmux]
[DRY-RUN] Step 3: Close cmux workspace [SKIPPED: --skip-cmux]
teardown-worktree.sh DEVX-1001 --repo claude-code-plugins
Output:
[INFO] Step 1: Validating prerequisites...
[OK] Prerequisites validated
[INFO] Step 2: Identifying cmux workspace for 'DEVX-1001'...
[OK] Found cmux workspace: workspace:3
[INFO] Step 3: Closing cmux workspace workspace:3...
[OK] cmux workspace workspace:3 closed
[INFO] Step 4: Cleaning up worktree (delegate to cleanup-worktree.sh)...
[OK] Worktree cleanup completed
==========================================
Worktree Teardown Complete
==========================================
[OK] Worktree: DEVX-1001
[INFO] Repository: claude-code-plugins
[OK] cmux: Workspace closed
Use case: Finishing work on a ticket. Closes the cmux terminal session and removes the worktree, branch, and workspace entry.
teardown-worktree.sh TICKET-42 --repo myproject --skip-cmux
Output:
[INFO] Step 1: Validating prerequisites...
[OK] Prerequisites validated
[INFO] Steps 2-3: Skipping cmux workspace closure (--skip-cmux)
[INFO] Step 4: Cleaning up worktree (delegate to cleanup-worktree.sh)...
[OK] Worktree cleanup completed
==========================================
Worktree Teardown Complete
==========================================
[OK] Worktree: TICKET-42
[INFO] Repository: myproject
[INFO] cmux: Skipped
Use case: When cmux is not available, not configured, or you manage your terminal sessions manually.
teardown-worktree.sh TICKET-1 --repo crewchief --dry-run
See the Dry-Run Usage section above for the expected output format.
Use case: Verify that the correct worktree and cmux workspace will be targeted before running the actual teardown. Useful for debugging configuration issues.
teardown-worktree.sh FEATURE-99 --repo webapp --keep-branch
Output:
[INFO] Step 1: Validating prerequisites...
[OK] Prerequisites validated
[INFO] Step 2: Identifying cmux workspace for 'FEATURE-99'...
[OK] Found cmux workspace: workspace:5
[INFO] Step 3: Closing cmux workspace workspace:5...
[OK] cmux workspace workspace:5 closed
[INFO] Step 4: Cleaning up worktree (delegate to cleanup-worktree.sh)...
[OK] Worktree cleanup completed
==========================================
Worktree Teardown Complete
==========================================
[OK] Worktree: FEATURE-99
[INFO] Repository: webapp
[OK] cmux: Workspace closed
Use case: When you plan to create a new worktree from the same branch later, or want to preserve the branch for a pull request review.
teardown-worktree.sh TICKET-1 --repo crewchief -y
Use case: Scripts, automation, or when you are certain the worktree should be removed. Bypasses the confirmation prompt that cleanup-worktree.sh shows when it detects an incomplete SDD ticket.
teardown-worktree.sh TICKET-1 --repo crewchief --skip-cmux --keep-branch --yes
Use case: Quick cleanup in a non-cmux environment where you want to preserve the branch.
| Exit Code | Meaning | Common Causes | Solution |
|---|---|---|---|
| 0 | Success | Worktree torn down, cmux closed or gracefully skipped | (Success - no action needed) |
| 1 | Usage error | Missing worktree name, missing --repo, missing flag value, invalid name format (contains slash/space/dot) | Check syntax with --help |
| 2 | Prerequisite failure | cleanup-worktree.sh not found, cmux-check.sh returned non-zero | Set CLEANUP_WORKTREE_SCRIPT env var or use --skip-cmux for cmux issues |
| 3 | Unrecognized option | Unknown flag, worktree name starting with a hyphen | Check valid options with --help |
| 4 | Worktree cleanup failure | cleanup-worktree.sh returned a fatal error | Run cleanup-worktree.sh directly with --verbose for details; check crewchief worktree list |
| 5 | User cancelled | User declined the confirmation prompt in cleanup-worktree.sh | Re-run with --yes to skip the prompt, or verify the worktree should be removed |
Note: cleanup-worktree.sh may exit 1, 2, 3, or 6 (lock failure). These are passed through by teardown-worktree.sh as exit 4.
When cleanup-worktree.sh runs, it may emit a warning about skipping iTerm tab closure. This warning is cosmetic and harmless -- it occurs because cleanup-worktree.sh has iTerm awareness that does not apply inside the devcontainer. The teardown script handles terminal closure via cmux instead.
The cmux workspace must be named exactly after the worktree for identification to work. The setup-worktree.sh script renames workspaces to the worktree name during creation. If a workspace was renamed manually, teardown will not find it and will warn but continue with worktree cleanup.
The script is designed to run inside the devcontainer. Host-mode execution is not supported because it relies on cmux-ssh.sh for terminal management and cleanup-worktree.sh for worktree removal.
If cmux workspace identification or closure fails (steps 2-3), the script still proceeds to worktree cleanup (step 4) and reports success (exit 0) if cleanup succeeds. The cmux failure is reported as a warning.
[WARN] No cmux workspace found matching 'TICKET-1'. Continuing with worktree cleanup.
What this means: The script called cmux-ssh.sh list-workspaces but no workspace name matched the worktree name. This is non-fatal -- worktree cleanup proceeds.
What to do:
bash "$CMUX_PLUGIN_DIR/skills/terminal-management/scripts/cmux-ssh.sh" list-workspaces
--skip-cmux to suppress this check entirely[ERROR] cleanup-worktree.sh not found at: /workspace/.devcontainer/scripts/cleanup-worktree.sh
What this means: The required cleanup-worktree.sh script is not at the expected location. The teardown cannot proceed.
What to do:
find /workspace -name cleanup-worktree.sh 2>/dev/null
CLEANUP_WORKTREE_SCRIPT="/path/to/cleanup-worktree.sh" teardown-worktree.sh TICKET-1 --repo crewchief
[WARN] Multiple cmux workspaces match 'TICKET-1' (2 found). Skipping close to avoid ambiguity.
What this means: More than one cmux workspace has the same name as the worktree. The script skips closure to avoid closing the wrong workspace.
What to do:
bash "$CMUX_PLUGIN_DIR/skills/terminal-management/scripts/cmux-ssh.sh" list-workspaces
bash "$CMUX_PLUGIN_DIR/skills/terminal-management/scripts/cmux-ssh.sh" close-workspace --workspace workspace:N
--skip-cmux for the worktree cleanupplugins/devx/skills/worktree-setup/SKILL.md) -- The setup counterpart that creates worktrees and cmux workspaces. Teardown reverses the operations performed by setup.plugins/cmux/skills/terminal-management/SKILL.md) -- The cmux terminal management skill providing cmux-ssh.sh for workspace listing and closure.crewchief worktree)