---
name: Worktree
slug: worktree
category: DevOps
description: Worktree creates or reuses an isolated AgentsMesh Git worktree from a verified base branch, preserves existing changes, and optionally starts the worktree-scoped development environment. Use when the user asks for a new worktree or isolated work for a feature, fix, investigation, or review.
github: "https://github.com/AgentsMesh/AgentsMesh/tree/main/agents/skills/worktree"
language: Go
stars: 2318
forks: 238
install: "npx degit https://github.com/AgentsMesh/AgentsMesh/tree/main/agents/skills/worktree ~/.claude/skills/worktree"
installs_to: ~/.claude/skills/worktree
source_path: agents/skills/worktree/SKILL.md
collection_size: 5
category_size: 798
collection_url: "https://dirskills.com/collections/AgentsMesh/AgentsMesh"
added: 2026-08-18T06:58:19.450Z
last_synced: 2026-08-18T06:58:19.450Z
canonical_url: "https://dirskills.com/skills/worktree"
---

# Worktree

Worktree creates or reuses an isolated AgentsMesh Git worktree from a verified base branch, preserves existing changes, and optionally starts the worktree-scoped development environment. Use when the user asks for a new worktree or isolated work for a feature, fix, investigation, or review.

**Install:**

```bash
npx degit https://github.com/AgentsMesh/AgentsMesh/tree/main/agents/skills/worktree ~/.claude/skills/worktree
```

## README

# AgentsMesh Worktree

Create worktrees next to the main checkout under `AgentsMesh-Worktrees`.

## Workflow

1. Determine the requested branch name, base branch (default `main`), and
   whether the task actually needs a running development stack.
2. Inspect repository state and identify the base remote from the user's request,
   the base branch upstream, or its URL:

   ```bash
   git status --short --branch
   git remote -v
   git worktree list
   ```

   Preserve all existing changes. Do not stash, reset, commit, or clean the main
   checkout as a side effect of worktree creation.
3. Fetch the selected base:

   ```bash
   git fetch <base-remote> <base-branch>
   ```

4. Derive a filesystem-safe directory name by replacing `/` in the branch with
   `-`. Use `$(dirname "$repo_root")/AgentsMesh-Worktrees`; do not embed a
   user-specific absolute path.
5. Check whether the branch or path already exists. If the branch is new:

   ```bash
   git worktree add -b <branch-name> \
     <worktree-root>/<directory-name> \
     <base-remote>/<base-branch>
   ```

   If the branch already exists and is not checked out elsewhere, attach it
   without `-b`. Never delete or reset an existing branch to make the command
   succeed.
6. In the new worktree, verify:

   ```bash
   git status --short --branch
   git log --oneline -3
   git merge-base --is-ancestor <base-remote>/<base-branch> HEAD
   ```

7. Start the environment only when runtime verification is needed. Read
   `references/dev-environment.md`, run the appropriate Bazel lifecycle target,
   then load and report the generated `deploy/dev/.env` values.

## Result

Report the absolute worktree path, branch, base ref and commit, whether the
development stack was started, and the generated ports when applicable. Do not
remove the worktree automatically; cleanup must preserve uncommitted or
unpushed work.