Two agent tabs in one checkout share one set of working files. Git worktrees give each code-changing session its own directory and branch while retaining one repository history.
Check the starting repository
Run git status before creating a worktree. Keep unrelated uncommitted changes in the main checkout where you can see them. Decide two independent outcomes and choose branch names that make ownership obvious. If both agents must change the same public API, settle the interface first or run the tasks sequentially.
Create one worktree per change
From the repository root, use git worktree add -b to create a new branch and linked directory. The example below puts directories beside the main checkout. Open each directory in its own agent session. Canopy can launch supported CLIs in isolated worktrees and show the branch and files beside each session.
Run services without port collisions
Separate working files do not automatically separate ports, databases, or external services. Give each preview a distinct port or run only the checkout you are inspecting. Canopy can allocate workspace ports and show detected local services, but a task may still need project-specific environment setup. Never copy secrets into a worktree without checking how your project handles them.
Review before integration
Run each worktree's relevant tests and inspect its diff. Open a PR for each branch or merge a reviewed branch through your team's normal process. Worktrees prevent concurrent edits from overwriting working files; they do not prevent merge conflicts when branches change the same lines or incompatible behavior.
Remove a worktree intentionally
Check for uncommitted changes and any process still using the directory. Git normally refuses to remove a worktree with untracked or modified files unless forced; do not force cleanup until those files are understood. After the branch is merged and the checkout is clean, remove the worktree through Git. Keep or delete the branch separately according to your repository workflow.
Copyable resources
Copyable two-agent setup
Run from the main repository directory; rename paths and branches for your project.
git status --short
git worktree add -b agent/settings ../project-settings
git worktree add -b agent/auth-review ../project-auth-review
git worktree list
# Open ../project-settings in one agent session.
# Open ../project-auth-review in another agent session.
# Use separate ports or dependencies where the project requires them.Inspection and cleanup
Review and merge first; avoid force-removing worktrees with unknown changes.
git -C ../project-settings status --short
git -C ../project-settings diff --stat
git -C ../project-auth-review status --short
git -C ../project-auth-review diff --stat
# After reviewed work is committed/merged and each checkout is clean:
git worktree remove ../project-settings
git worktree remove ../project-auth-review
git worktree listFrequently asked questions
Can two worktrees use the same branch?
Git normally prevents one branch from being checked out in multiple worktrees at once. Give each code-changing agent its own branch.
Do worktrees eliminate merge conflicts?
No. They isolate working files. Conflicting edits or incompatible decisions still need integration and review.