Worktrees and the Parallel Fix
Freddy has three threads in one project and he has noticed the problem he was warned about: two of them are editing the same file. This chapter is the fix, and the thing you can build on it: giving one task to several agents and keeping the best result.
The problem
A Git repository has one working folder. Two agents working in it share the same files: one rewrites a function while the other is reading it, one runs the tests against half of the other's change, and the diff in the Changes tab is a mix of both. Parallel threads are only useful if they do not step on each other.
The hard way
git worktree add by hand, or a second clone. It
works. You choose a folder, name a branch, install dependencies,
remember to delete it, and merge it back. Most people do it for
the big refactor and not for the small task, which is exactly
when two small tasks collide.
New worktree
When you start a thread in a Git repository, you choose
Local or New worktree (chapter
2). With New worktree, Workspace creates a Git
worktree for the thread under ~/.elyra/worktrees, on
a new branch. The thread, its terminal and its Changes tab all
work there. The project folder itself is not touched, so several
threads can work in parallel.
- The choice is made before the first message; it cannot be changed afterwards. Decide when you start the thread.
- File → Manage Worktrees… lists the worktrees Workspace created and their threads. Remove ones you no longer need (their branches are kept).
- When you delete a thread that has a worktree, Delete with worktree removes both.
A good rule: a thread that only reads can be Local. A thread that edits, while something else might also be editing, gets its own worktree. And a worktree is the place for the permission mode from chapter 3 that you would otherwise hesitate over: if the folder is a copy on its own branch, Full access has a much smaller blast radius.
A worktree with its own running app
There is a second problem a plain worktree does not solve. It is a copy of the files on a new branch, and nothing in it gives a web app its own data or its own address. Two threads testing a migration would still be testing it against whatever database the project is configured to use.
When Elyra Grove runs the project as an app, Grove makes the
worktree instead (grove try --new, under
~/.grove/try): on the same new branch, but with its
own copy of the database, migrated, and its
own address, such as
shop--elyra-1a2b3c4d.test. The thread says where it
runs, and the address opens in the thread's browser. Each thread
can change data and run migrations without touching yours.
- Removing such a worktree (deleting its thread with the worktree, or in Manage Worktrees) takes its site and database copy down with it; the branch stays.
- If Grove cannot start the branch, the thread gets a plain worktree and says why.
- Turn this off in Settings → Agents & MCP → Grove runs worktrees.
Best of N
Now that threads cannot collide, there is a thing you can do
that is awkward without them: give one task to several agents at
once and keep the best result. Open the command palette
(⌘K), choose Best of N…,
write the task, pick at least two agents and press
Start. Each agent gets its own thread and its
own Git worktree.
The comparison opens in the middle of the window. For each candidate it shows its status, whether its checks and journeys passed (chapters 9 and 10), the files and lines it changed, its cost and its reply. Open shows the thread, with its diff in the Changes tab.
Workspace recommends one of the finished candidates and says why: green checks and journeys first, then the smallest change, then the lowest cost. It is advice; you pick. When one is done and you like it best:
-
Use this one commits the candidate's
worktree and brings its changes into the project folder with
git merge --squash. They are staged, not committed, so you can review them in Changes and commit them yourself. Uncommitted changes in the project that touch the same files may conflict. - Delete the other N and their worktrees cleans up the rest.
The candidates are ordinary threads, so you can also talk to them before you choose. Compare best of N in a candidate's thread menu reopens the comparison. With Grove, every candidate runs as its own app you can look at.
What you learned
- Why parallel threads need separate folders, and what New worktree does
- That the Local or worktree choice is made before the first message
- How Manage Worktrees and Delete with worktree keep the disk tidy
- How Grove gives each worktree its own database and address
- How best of N works, how the recommendation is ordered, and what Use this one really does