Semantic merge driver for parallel task worktree merges

[rs545837]

When running parallel tasks in separate worktrees or branches, merging results back hits git's line-level merge conflicts whenever two tasks touch the same file, even if they edited different functions.

weave is a semantic merge driver that merges at the function/class level using tree-sitter. Registers via .gitattributes so every git merge and git rebase uses it automatically. On benchmarks: 31/31 clean merges vs git's 15/31.

Also ships as an MCP server with 14 tools for agent coordination:

• weave_claim_entity / weave_release_entity for advisory locks on specific functions/classes
• weave_potential_conflicts for detecting overlapping changes between worktrees before merge
• weave_preview_merge for simulating merge outcomes
• weave_who_is_editing to check what other agents are touching

brew install ataraxy-labs/tap/weave

[roomote]

Thanks for filing this issue. I have been looking into how weave could fit with the existing worktree infrastructure in Roo Code, and I have a few questions before proposing a concrete plan:

1. Scope of integration - Are you envisioning Roo Code automatically configuring weave as the merge driver (via .gitattributes) when creating worktrees, or is this more about surfacing weave's MCP tools to agents for coordination during parallel tasks?

2. Merge driver setup - For the semantic merge driver side, would the expectation be that Roo Code detects if weave is installed and offers to configure it, or should Roo Code handle installation as well? Since weave is an external binary (brew install), automatic installation may not be appropriate for all platforms.

3. MCP server integration - Regarding the MCP tools (weave_claim_entity, weave_release_entity, weave_potential_conflicts, etc.), should these be auto-registered as an MCP server when weave is detected, or presented as an optional configuration the user can enable?

4. Priority - Which aspect is more valuable to tackle first: the merge driver configuration (improving merge outcomes) or the MCP coordination tools (preventing conflicts before they happen)?

Any guidance on these points would help me put together a focused implementation plan.

Please mention @roomote in a comment with your answers, and I will proceed accordingly.

[rs545837]

@roomote Great questions. Here's how I see it:

1. Scope: Both, but they're independent. The merge driver improves outcomes when branches merge back. The MCP tools let agents coordinate in real time so they avoid conflicts in the first place. Either one works standalone.

2. Merge driver setup: Detect and configure, not install. If weave is on PATH, offer to add the .gitattributes config. Installation should stay with the user (brew install ataraxy-labs/tap/weave or cargo install). Cross-platform binary releases are available on GitHub.

3. MCP server integration: Optional configuration makes more sense. Users who want coordination tools can enable them. The MCP server runs as weave-mcp --stdio, same pattern as any other MCP server in Roo Code.

4. Priority: Merge driver first. It's zero-effort for the user after setup and immediately reduces false conflicts. The MCP coordination tools are more valuable at scale (3+ parallel agents) and can come later.

Happy to help with implementation details if needed. The merge driver config is just three lines in .gitattributes + a .gitconfig entry.

[roomote]

Thanks for the detailed answers, @rs545837. I've seen your comment and will start working on the merge driver integration first, as you suggested. The plan is:

1. Detect whether weave is on PATH when creating/managing worktrees
2. If found, offer to configure .gitattributes and .gitconfig for the semantic merge driver
3. Keep installation as the user's responsibility

I'll open a draft PR to share progress shortly. Feedback and guidance are welcome as I go.

[roomote]

Opened a draft PR with my attempt at the weave merge driver integration: #11711

This covers the merge driver detection and configuration (priority item from the discussion). The MCP coordination tools integration is planned as a follow-up. Feedback welcome!

[ThinkOffApp]

The merge conflict problem with parallel agent worktrees is real. We run multiple coding agents simultaneously and the naive approach of "everyone works on a branch, merge later" breaks down fast when two agents touch overlapping files.

We ended up using append-only receipt logs as a coordination primitive - each agent writes what it changed and why, so the merge step has context about intent, not just line diffs. It is not as sophisticated as a tree-sitter merge driver but it catches the cases where two agents edited the same function for different reasons.

Has anyone tested weave with agents that do large-scale refactors? The function-level merge sounds great for localized edits but I wonder how it handles cases where an agent restructures an entire module.

[rs545837]

Good question. For large-scale refactors, two things help:

1. Rename detection via structural hash. If an agent moves a function from utils.py to auth_helpers.py and renames it, weave matches entities by AST-normalized hash, not just name. So it tracks the function across files even if the name changed, as long as the structure is equivalent.

2. Inner entity merge for classes. When an agent restructures a class (reorders methods, adds new ones, removes old ones), weave chunks the class body by indentation and matches methods by name. Two agents reordering methods differently in the same class produces a clean merge instead of a full-class conflict.

Where it gets harder: if an agent splits one function into three, or inlines a function into its callers, that's a structural change weave sees as "entity deleted + new entities added." It won't automatically link the old function to its replacements. The audit trail (--audit flag) helps here because it tells you exactly what happened to each entity, so a follow-up agent or human can verify the intent.

The receipt log approach you're using is complementary. Weave handles the structural merge, but knowing why an agent made a change (your intent logs) is useful for the cases where structure alone isn't enough. You could actually pipe the audit trail JSON into your receipt logs to get both: what structurally happened to each function + why the agent did it.

If you're running multiple agents on the same repo already, try brew install ataraxy-labs/tap/weave and add it as a merge driver. It's three lines of config and every git merge uses it automatically. The MCP server (weave-mcp --stdio) also gives your agents weave_potential_conflicts to check for overlapping changes before they even attempt a merge.

[ThinkOffApp]

The structural hash approach is smart. We've been doing something simpler - append-only receipt logs where each agent records what it changed and why before committing. That way even if the merge driver can't auto-resolve, you have enough context to understand the intent behind each change. The rename detection via structural hash would be a big upgrade over our current diffstat-based approach though. Are you planning to expose that as a standalone tool or is it tightly coupled to Roo-Code?

[rs545837]

It's standalone, not coupled to Roo Code at all. weave is a git merge driver that works with any git workflow. brew install ataraxy-labs/tap/weave, add three lines to .gitattributes and .gitconfig, and every git merge uses it. The Roo Code integration here is just auto-configuring that setup. The structural hash comes from sem, the entity extraction library underneath weave. You can use sem diff independently to see entity-level changes with rename detection on any repo.

[ThinkOffApp]

That's great to hear - standalone is exactly what we'd need. Going to try brew install ataraxy-labs/tap/weave on our setup this week. We run parallel agents across worktrees and the merge step is always the bottleneck. Having entity-level rename detection would save us a lot of manual conflict resolution. Thanks for the pointer to sem too - sem diff looks useful for our receipt logs where we track what each agent actually changed.

We built a similar coordination setup for parallel agents in ide-agent-kit - weave would be a great complement for the merge step.