Git worktrees create multiple working directories connected to one repository, so different branches can be checked out simultaneously. They turn waiting time into parallel progress, but distribute project state across directories and terminals. section 5.6.1
Treat worktrees as a coordination tradeoff, not free parallelism:
- Increase throughput by running separate tasks—such as authentication refactoring, API tests, and documentation—in parallel. section 5.6.1
- Create context fragmentation when failures, prompts, and unfinished work become distributed across directories. section 5.6.1
- Accumulate merge complexity when parallel branches modify related code; sequential work can be cheaper for coupled tasks. section 5.6.1 section 9.5.3
- Lose shared agent context because each session starts fresh, requiring manual coordination about changes elsewhere. section 5.6.1
- Prefer isolated worktrees for genuinely independent tasks with hard file boundaries; avoid them when agents modify the same utilities. section 9.5.3
A parallel project layout
A repository might contain app-main for current development, app-auth-refactor for an agent, app-api-tests for test improvements, and app-docs-update for documentation review. This makes concurrent work visible, but increases the number of terminals and states that must be monitored. section 5.6.1
~/projects/ ├── app-main/ # Main development, current feature ├── app-auth-refactor/ # Auth refactoring (agent working) ├── app-api-tests/ # API test improvements (agent working) └── app-docs-update/ # Documentation (waiting for review)
Browse a concrete directory layout showing how one repository can host several simultaneous task worktrees. section 5.6.1
