Worktrees

Agentree runs agents in isolated git worktrees so parallel runs do not write into the same checkout. Each assistant node gets its own worktree and branch.

Where Worktrees Live

Agent worktrees live under:

~/.agentree/worktrees/<repo-key>/nodes/<assistant-node-id>

<repo-key> is a stable key derived from the repository path. The branch name is:

agentree/<assistant-node-id>

Agentree also supports older worktrees under .git/agentree/worktrees/<assistant-node-id> when resolving existing runs.

Creation

When an agent run is accepted, Agentree first previews the worktree path and records it in the run ledger. The actual worktree is created in the background lifecycle before the agent process starts.

Creation does this:

• removes any old worktree already attached to the same agentree/<assistant-node-id> branch.
• removes any stale worktree directory at the target path.
• deletes any stale local branch with the same name.
• runs git worktree add <path> -B agentree/<assistant-node-id> <parent-commit>.
• records the worktree path, branch name, and base commit in the assistant run metadata.
• starts the agent process inside that worktree.

Dependency Symlinks

After creating the worktree, Agentree links large dependency directories from the original repository into the worktree instead of copying them.

Agentree looks for these dependency directories at the repo root and one level below normal package directories:

node_modules
.venv
venv
vendor
.gradle
target

If the matching directory exists in the original repo and does not already exist in the worktree, Agentree creates a symlink at the same relative path in the worktree.

Agentree writes managed entries into the repository git exclude file so these symlinks do not show up as normal changes.

Env Files

Agentree copies .env* files into the worktree after dependency links are created. This preserves local runtime configuration even when those files are gitignored.

What Gets Committed

When the agent finishes, Agentree finalizes the worktree by collecting changed paths from:

• unstaged tracked changes.
• staged changes.
• untracked files that are not ignored by git.

Before staging, Agentree removes managed scaffolding paths from that list. Dependency symlinks are omitted from the agent commit. Provider-native skill files in the repository are treated as normal repository files.

If no committable paths remain, Agentree records that no commit was created. If real changes remain, it stages only those paths and creates one commit with the assistant run's commit message.

If the agent already advanced the worktree HEAD with a clean commit, Agentree can detect that commit when HEAD is a descendant of the parent commit.

Cleanup

After finalization, Agentree cleans up worktrees only from terminal runs. Completed runs also require durable finalization before cleanup proceeds.

Cleanup checks that the recorded worktree path belongs to the assistant node, removes the worktree with git worktree remove --force, then archives and deletes the agentree/<assistant-node-id> branch head.

Failed setup or spawn paths also request cleanup when enough ledger information exists.

Note: Above hardcoded paths should work fine for 95% of users. We plan to make them configurable repository wise in future.