Git Worktree Best Practices for Multi-Agent Development
Git Worktree Best Practices for Multi-Agent Development
Git worktrees are the standard for running parallel AI agents on the same codebase. But without discipline, worktrees sprawl just like branches do. Here are the practices that keep things clean.
Setup: Keep a Consistent Directory Structure
Put all worktrees in a sibling directory to your main repo. Don't scatter them across your filesystem:
mkdir -p ../project-worktrees
git worktree add ../project-worktrees/auth -b feat/auth
git worktree add ../project-worktrees/api -b feat/api
This makes it obvious where your worktrees live and simplifies cleanup. A flat structure with descriptive names beats nested directories every time.
Branch Strategy: Feature-Based, Not Agent-Based
Name branches after the feature, not the agent. feat/auth-refactor is useful six months from now. agent-3-session-tuesday is meaningless by Wednesday.
Keep branches short-lived. The ideal lifecycle is: create worktree, complete the task, merge the branch, remove the worktree. If a worktree exists for more than a day, the task scope is probably too large.
Cleanup: Prune Aggressively
Stale worktrees waste disk space and clutter git worktree list output. After merging:
git worktree remove ../project-worktrees/auth
git branch -d feat/auth
git worktree prune
Make this a habit. Run git worktree list at the start of each day and remove anything that's done.
Common Mistakes
Don't check out the same branch in multiple worktrees - git prevents this, but the error message is confusing. Don't forget to install dependencies in each worktree if your project needs them. Node modules, Python venvs, and similar setups are per-directory, not shared.
The biggest mistake is creating worktrees without a plan for merging them back. Decide the merge order before you start parallel work, not after three agents have all modified the same module.
Fazm is an open source macOS AI agent. Open source on GitHub.