Skip to main content
Harmony
Download

Worktrees

PreviewAvailable on: WindowsShips in the preview channel only. Not a stable release.

How Harmony keeps parallel agents from colliding, and what isolation does and does not protect.

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

PropertyEffect
Separate working directoryAgents do not overwrite each other's edits
Separate branchEach line of work has its own history
Shared git object storeCheap to create; no full clone per agent
Independent reviewYou 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

git worktree list

Expected result: the main checkout plus one entry per active worker.