Create and clean up isolated git worktrees for parallel agent tasks, compatible with spec-kit.
3c:T859,
Manage isolated git worktrees so multiple agents can work in the same repository without colliding. Uses detached HEAD so external tools like spec-kit can manage their own branches.
From the target repository, create an isolated worktree:
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")
TASK_ID=$(date +%s) # or use a descriptive slug
DEST="$HOME/.agent-worktrees/${REPO_NAME}-${TASK_ID}"
git worktree add --detach "$DEST"
Avoid duplicating heavy directories and keep env config in sync:
# node_modules — prevent multi-GB duplication
[ -d "$REPO_ROOT/node_modules" ] && ln -sf "$REPO_ROOT/node_modules" "$DEST/node_modules"
# Environment and config files
for f in .env .env.local .env.development .npmrc .yarnrc; do
[ -e "$REPO_ROOT/$f" ] && ln -sf "$REPO_ROOT/$f" "$DEST/$f"
done
cd "$DEST"
All subsequent work happens here. The worktree starts at the same commit as HEAD — spec-kit or any other tool can create branches from this point.
Run your task in the worktree directory. Spec-kit, manual branching, or any other workflow will operate in isolation from the main checkout and other worktrees.
After work is complete (PR merged, changes landed, or task abandoned):
DEST="$HOME/.agent-worktrees/${REPO_NAME}-${TASK_ID}"
# Remove the worktree
git worktree remove "$DEST" 2>/dev/null || rm -rf "$DEST"
# Prune stale worktree references
git worktree prune
If spec-kit created a branch that is no longer needed:
git branch -d <branch-name>
git worktree list
--detach so downstream tools control branching.node_modules and env files to keep a single source of truth.