# Worktrees Source: https://docs.ideharmony.com/concepts/worktrees Two agents editing the same files at the same time produces work nobody can review. Harmony's answer is git worktrees: each unit of delegated work gets its own checkout of the repository, on its own branch, in its own directory. ## What a worktree gives you | Property | Effect | |---|---| | Separate working directory | Agents do not overwrite each other's edits | | Separate branch | Each line of work has its own history | | Shared git object store | Cheap to create; no full clone per agent | | Independent review | You can read one agent's diff without the others' noise | ## What it does not give you > [!IMPORTANT] > A worktree is file isolation, not a security boundary. An agent in a worktree > can still reach the rest of your machine, your network, and any credentials in > its environment. Do not treat worktree isolation as a sandbox. It also does not prevent logical conflicts. Two agents can produce individually correct changes that contradict each other. Integration is still a decision someone has to make. ## The shape of a run A lead run coordinates; workers each get a worktree; artifacts and diffs come back for review; integration is explicit.
Worktree isolationA lead run delegates to two or more workers. Each worker gets its own git worktree, on its own branch, in its own directory, so their file edits cannot collide. Each returns a diff. A human reviews the diffs separately and then makes an explicit integration decision. Nothing merges automatically because a worker reported success. The worktrees share one git object store, so they are cheap to create, and isolation is at the file level only — it is not a security boundary.Lead runcoordinatesWorker Aworktree A · branch AWorker Bworktree B · branch BDiff ADiff BReviewby a humanShipShared git object store — worktrees are cheap. File isolation only, not a security boundary.
Workers cannot collide in the same files. They can still produce individually correct changes that contradict each other, which is why review sits between the diffs and the merge.
Nothing merges itself because a worker declared success. ## Writer leases The daemon is the single durable writer for orchestration state. When several participants could write the same record, a lease decides who may. This is why two clients watching one run do not corrupt its state. ## Practical guidance - **Give each worker a scope that maps to a worktree.** Work that spans every file in the repository does not parallelise usefully. - **Review each diff separately**, then think about interactions. - **Clean up after integration.** Abandoned worktrees accumulate. ## Verify what exists ```powershell git worktree list ``` **Expected result:** the main checkout plus one entry per active worker. ## Related - [Orchestration](/docs/orchestration) - [Tasks, plans, and runs](/docs/concepts/tasks-plans-and-runs) - [Architecture](/docs/concepts/architecture)