Support git worktrees so multiple geese can work independently in git directories

[wclausen-square]

Please explain the motivation behind the feature request.

tl;dr: I'd like Goose to have better support for concurrent Goose sessions in project directories that are also git repositories.

longer explanation:

Sometimes, I want to run a Goose recipes multiple times with different inputs on a given project or have Goose work in parallel on small, independent tasks. One example of this could be testing updates to a recipe across a set of inputs to see how it performs on my project. Another example could be giving Goose a few independent tasks in the same repository, like introducing a small feature in parallel with fixing a compilation error on a recent pr.

Currently, if these tasks are in the same project directory and involve making any modifications to files, I have to run these operations one-at-a-time, otherwise there is risk of one Goose session interfering with the other (e.g. one Goose instance introduces a breaking compilation change, which prevents other Goose sessions from compiling). If there are many tasks to run, then doing them one-at-a-time is much slower than having them run in parallel. This can be slow enough that I often, with current Goose capabilities, don't think of Goose as a good fit for this kind of work.

If the project directory is also a git repository, this problem can be solved quite well with git worktrees.

Describe the solution you'd like
I'd like Goose to have a setting that, when enabled, has Goose automatically create a worktree when running a task in a project directory that is also a git repository.

Describe alternatives you've considered
In my current Goose usage, I hack around this limitation by having multiple copies of relevant repositories installed on my machine, and jumping between them for individual tasks. So, "multiple repo copies" is one alternative, but it is not a great developer experience, especially in large repos. In setups where Goose is run in headless mode (e.g. CI) this can be ok, bc Goose can be expected to be the only process modifying the repo.

Additional context
Git worktrees appears to be used by similar agentic tools like Claude Squad to solve the problem of "multiple agents working in the same repository without interfering."

• I have verified this does not duplicate an existing feature request

I searched for "worktree", "concurrent", and "multiple" in the issue tracker and did not see anything that seemed related to this feature request.

[DOsinga]

/cc @jamadeo @Kvadratni

[Kvadratni]

I like the idea in general, but with several caveats:

1. This should be part of developer tool or a separate built-in git tool ( the latter is better)
2. Cleanup should be enforced somehow outside of LLM control.
3. There should be rules on how the merges happen between agents to avoid massive merge conflicts an d stepping on each other webbed feet.

[michaelneale]

I like this a lot, don't really know about worktrees but looking at them they seem the right solution for things like this, as multiple repos are a pain.

so question for @Kvadratni @wclausen-square - this seems like it could be not just recipes, but even concurrent sessions (ie you dont' want to clone seperately) but you want to fork off a goose session and work on different things - maybe unrelated features right? Would those sessions need to be aware of each other (other than the fact they are work trees) - as that seems more like claude squad.

Or is this more that you open goose once, and subagents/recipes can work across different features using worktrees, and the one parent session can then co-ordinate?

Agree this should be in developer MCP and be smart enough to kick in and work with git worktrees, so it probably accomomdate a bunch of use cases like this. I wonder if it is related to subagents.

[Kvadratni]

I think both should be supported. If we can have an ability to detect a running goose agent in a directory - we can cover both use cases

[wclausen-square]

this seems like it could be not just recipes, but even concurrent sessions (ie you dont' want to clone seperately) but you want to fork off a goose session and work on different things - maybe unrelated features right? Would those sessions need to be aware of each other (other than the fact they are work trees) - as that seems more like claude squad.

I was envisioning the system behaving basically just like claude squad aka the worktree exists at a session level, not a sub-recipe/sub-agent level. But @michaelneale you are right that it could work in a number of ways. To me they look broadly like:

1. Worktree at session level. When you open goose in a git directory and have enabled some "worktree support" setting, Goose automatically creates or reuses an existing/available worktree for that directory for the given session. The agent the runs everything in that worktree directory instead of the main repo directory. Recipes and subrecipes that are part of that session would all share the same worktree. This means you'd need to control things to that subrecipes that can modify the repo state are run sequentially.
2. Worktree at a subtree/subagent level. You open a session in a given target directory, and that session points to the actual git directory, not a worktree. When the session/recipe wants to do some unit of independent work, it creates/reuses a worktree for that portion of work.
3. Some combination/mixture of the two above.

I think 1. is the probably the best option at this point, but this is colored by some of the repos I work in and how I've seen worktrees work in those contexts. For example, in a large repo (common in larger companies), creating a new worktree can take quite a long time. I've seen it take multiple minutes in very large repositories. To me, this means you'd want to carefully control that resource and not create/destroy them willy nilly. A worktree per sub-recipe feels like it could easily explode the number of worktrees being created/used/destroyed. Additionally, in very large repos, creating worktrees can consume disk usage pretty rapidly. On my work machine, I have myself created and not cleaned up worktrees in large repos and they can quickly consume hundreds of GB. Thankfully, they aren't super complicated to clean up, but the disk usage aspect is an important consideration that leads me to think "1 per session, reused across sessions if available" is the right choice at this stage.

I think that 1. also has a simpler implementation and a lower cognitive overhead for new/unfamiliar users to understand the implications/structure. I'd say the usage of worktrees instead of having Goose directly in the repo is a pretty big cognitive jump for users who are likely to be accustomed to agents working directly alongside them in a given repo directory and who are not likely to be familiar with worktrees (I was not until I looked at Claude Squad, and I have been using git for many years now). It can become difficult to understand how to merge the changes from a worktree back into the user's primary view of the repo/current branch in the main working directory. Ideally, and in the longer term, Goose would include ux pieces that would smooth that process significantly.

But if we are talking about "long-term design," probably the best way is to view worktrees as the "unit of isolation" of agent work. If we think that full sessions or full recipes are going to be the atomic unit of work initiated by a user, then worktrees should probably operate at that level. If we want to model the "atomic unit" of agent work as a subagent/sub-recipe, then worktrees probably make more sense architecturally to integrate there. I expect users will be kicking things off at the session/recipe level, so worktrees should be present there. And then if we want to expose a goose worktree api to recipe developers so they can run sub-recipes/subagents in a worktree that could be open to them as well based on what they think they need.

[wclausen-square]

I like the idea in general, but with several caveats:

1. This should be part of developer tool or a separate built-in git tool ( the latter is better)
2. Cleanup should be enforced somehow outside of LLM control.
3. There should be rules on how the merges happen between agents to avoid massive merge conflicts an d stepping on each other webbed feet.

Broadly agree on all parts.

1. This should be part of developer tool or a separate built-in git tool ( the latter is better)

Either option seems good 👍

2. Cleanup should be enforced somehow outside of LLM control.

I'd extend this to say that, in general, worktrees should be totally opaque to agents, both creation and cleanup should be considered part of environment management, like opening goose in a particular directory, and thus managed by Goose/some Goose plugin outside of the LLMs control/knowledge. The short version is that agents should just see some working directory and are isolated from other contexts, in a perfect world.

Worth noting, like I mentioned above, that worktree creation/cleanup can be a significant/long-running action in large repos. This is another good reason to have it managed by a dedicated plugin that can handle edge cases/ensure the worktrees are working well.

3. There should be rules on how the merges happen between agents to avoid massive merge conflicts an d stepping on each other webbed feet.

Merges are a challenge, for sure. The introduction of worktrees/isolated git environments for different agents/multiple agents working concurrently in the same repo means that merge conflicts become more of a thing to worry about compared with Goose operating as the sole agent/controller of the main git working directory. Ideally, the plugin that supports worktree usage would make it easy to do things like:

• see what work has been done in the worktree (view diffs against a specific branch/commit/etc)
• merge changes back into some other main user branch. This could be something simple like making it easy to open a terminal directly in the worktree directory. Or having the worktree manager deeply integrate with git and be able to show diffs, manage merges, etc. That one seems like a lot more work and makes sense as a longer-term goal if worktrees end up being useful/popular.

I would expect this part of worktree usage to also not be controlled by an LLM/agent, at least at this stage of agent development. There's still a point where I'd expect the overwhelming majority of Goose/LLM users would want a "human in the loop" and I think the "merge point" is a good place for that human review of LLM output. Also fair to note that as agents can take on larger and larger tasks (e.g. execute tasks that would take a person 1+ days), the trendline would be for even this merging piece to become something an agent would want to be able to manage itself. I don't think we are there yet, and the prudent move is to support some clean integration point where a human is in the loop.

[jhult]

How about utilizing one of these?

• https://github.com/ben-rogerson/git-worktree-toolbox
• https://github.com/broskees/worktree-mcp

[DOsinga]

do you have thoughts @baxen ? work-trees is something that keeps coming up. should we ship with a solution for this?

[DOsinga]

and in general git or should it just be part of the devel toolkit - in my experience just gh does wonders

[rs545837]

This thread is describing exactly the problem we've been working on. We built weave, a semantic merge driver for Git that resolves this at the entity level instead of the line level.

The core issue: Git merges by comparing lines. When two agents both add code to the same file, even to completely different functions, Git sees overlapping line ranges and declares a conflict. Worktrees help by giving each agent its own working directory, but you still hit the same line-based merge conflicts when you merge the branches back together.

Weave replaces Git's line-based merge with entity-level merge. It parses all three versions (base, ours, theirs) into semantic entities (functions, classes, types, etc.) via tree-sitter, matches them across versions, and merges at that granularity:

• Two agents add different functions to the same file? Auto-resolved, no conflict.
• Agent A modifies foo(), Agent B adds bar() nearby? Auto-resolved.
• Both agents modify the same function differently? Real conflict, with entity-level context in the markers.

On a benchmark of 31 merge scenarios that produce false conflicts in Git, weave resolves all 31 cleanly (100% vs Git's 48%).

We also built an MCP server (weave-mcp) with 9 tools for agent coordination: weave_claim_entity, weave_who_is_editing, weave_potential_conflicts, etc. Agents can claim entities before editing, check who's working on what, and detect collisions before they happen. This directly addresses @Kvadratni's point about needing "rules on how the merges happen between agents."

Setup is one command (weave setup in any Git repo), then git merge uses weave automatically for configured file types. It supports TypeScript, JavaScript, Python, Go, Rust, JSON, YAML, TOML, and Markdown.

This could work alongside worktrees: each Goose session gets its own worktree, and weave handles the merge when branches come back together. Or without worktrees at all, since the MCP coordination layer prevents agents from stepping on each other's entities in the first place.

Happy to help integrate this if there's interest.