# Using Git Worktrees

> Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

- Skill: `mrlyk/using-git-worktrees` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrlyk/using-git-worktrees`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/using-git-worktrees/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrlyk (https://skillmd.com/u/mrlyk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrlyk/using-git-worktrees

---


# Using Git Worktrees

One CLI call creates or reuses the single task worktree. Run the command, then act on the JSON result.

## Create

```bash
superharness task worktree create {task-id} --json
```

Full and Lite share the same worktree kind: branch `superharness/{task-id}`, one checkout per task. The CLI resolves the layout (a non-empty persisted `worktree_path` is authoritative and reused exactly; otherwise flat-v1 from `.superharness/worktree.yaml`), verifies the directory is git-ignored (appending to `.gitignore` when needed — commit that change), copies minimal `.superharness/` state (spec, config, workflow, worktree.yaml, active task directory), writes `worktree_path` back to both task.json copies (parent-thread hooks locate the active task by matching it against the session cwd), symlinks `node_modules` from the primary checkout when possible, and returns `reused: true` when a compatible worktree already exists.

`superharness task worktree path {task-id} --json` answers path-only lookups. A generic worktree without a task directory is the only manual case: `git worktree add <worktree_dir>/<name> -b superharness/<name>`.

## Verify Baseline

Run the `post_create` and `verify` commands from the JSON result and read the output. If verification fails, report the failures and ask whether to proceed.

## Recovery and Cleanup

`reused: true` never re-copies or resets anything. An `in_progress` task may leave intentional uncommitted work: inspect `git status`, the diff, recent commits, and the task's focused verification before assigning ownership, dispatch a recovery agent for the same task, and ask the user when ownership is unclear. **Never reset or stash** a dirty recovery checkout.

Cleanup goes through `superharness task worktree prune {task-id} --json`, which removes the worktree only after the task is completed, the checkout is clean, and the registered branch matches `superharness/{task-id}`; anything else is preserved with a reason.

## Integration

**Called by:**
- **superharness:subagent-driven-development** - Setup, REQUIRED before dispatching any implementer (full profile)
- **superharness:go** - lite profile only, when the concurrency check finds another active task on this checkout
- Any skill needing isolated workspace

**Pairs with:**
- **superharness:finishing-a-development-branch** - REQUIRED for cleanup after work complete