| name | worktree |
| description | 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. |
AgentsMesh Worktree
Create worktrees next to the main checkout under AgentsMesh-Worktrees.
Workflow
-
Determine the requested branch name, base branch (default main), and
whether the task actually needs a running development stack.
-
Inspect repository state and identify the base remote from the user's request,
the base branch upstream, or its URL:
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.
-
Fetch the selected base:
git fetch <base-remote> <base-branch>
-
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.
-
Check whether the branch or path already exists. If the branch is new:
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.
-
In the new worktree, verify:
git status --short --branch
git log --oneline -3
git merge-base --is-ancestor <base-remote>/<base-branch> HEAD
-
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.
