# Ataraxy-Labs/weave: entity-level merge for Git conflicts between coding agents

> Weave is a Git merge driver that parses base, ours and theirs into functions, classes and keys with tree-sitter, then merges those entities instead of lines. It targets the false conflicts that appear when independent agents edit the same file.

**Ataraxy-Labs/weave** — Entity-level git merge driver. Resolves false conflicts git invents when independent agents edit the same file. ~95% reduction vs. line-based merge.

- Repository: https://github.com/Ataraxy-Labs/weave
- Website: https://ataraxy-labs.github.io/weave/
- Stars: 1,312 · Forks: 45
- Language: Rust
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ataraxy-labs-weave

## The false conflict weave was built to remove

Git compares lines. When two branches both add code to the same file, even to entirely separate functions, the line ranges overlap and Git stops the merge. The README shows the canonical case: one branch adds validateToken, another adds formatDate, and the result is a conflict block containing two functions that have nothing to do with each other. A human resolves it by deleting three marker lines.

The cost is not the resolution, it is the interruption. The README frames the target audience directly: this happens constantly when multiple AI agents work on the same codebase, where Agent A adds a function and Agent B adds a different function to the same file. In that workflow nobody is holding a mental model of the file, so a conflict marker is pure overhead. Weave is for teams running coding agents against a shared repository, and for anyone whose branches keep colliding on line numbers rather than on meaning.

## How the entity-level three-way merge actually works

Weave replaces Git's line-based merge with a three-way merge over semantic entities. The README describes four steps. All three revisions (base, ours, theirs) are parsed with tree-sitter into entities: functions, classes, JSON keys and similar. Entities are then matched across versions by identity, which the README defines as name plus type plus scope, and renames are handled in that matching step. The merge then runs on entities rather than lines, with three outcomes: different entities changed on each side resolve automatically; the same entity changed by both sides triggers an attempt at an intra-entity merge that conflicts only if the two edits are truly incompatible; and a modify-on-one-side, delete-on-the-other case is flagged as a meaningful conflict.

The algorithm is deterministic and stateless. It reads three file revisions and writes one result, the same shape as git merge-file, and the README is explicit that this is not a CRDT. That distinction matters because it tells you where weave sits in the pipeline: it is a merge driver invoked by Git, not a live editing protocol. The project does ship a separate CRDT-backed layer, weave-crdt, for tracking live multi-agent edits before they reach Git, and the Cargo workspace lists it as its own crate alongside weave-core, weave-driver, weave-cli, weave-mcp and weave-github. The Cargo.toml comment states that the three tree-sitter parses of the three inputs account for roughly 94% of a real merge, profiled on a 51KB Django file, which explains the release profile settings: thin LTO and codegen-units set to 1.

## Installing weave and resolving your first conflict

The README lists Homebrew as a distribution channel and the repository carries a Formula directory. The npm package @ataraxy-labs/weave is a wrapper: according to package.json it downloads matching release binaries and exposes three commands, weave, weave-driver and weave-mcp, with a postinstall script and a verify-checksum script. It requires Node 20 or newer.

Once the binary is on PATH, the quickstart is three commands. weave setup wires the current repository to merge through weave while leaving git merge, rebase and cherry-pick invocation unchanged.

```bash
weave setup
```

After that, a normal merge runs as usual, but real conflicts land as markers that include a refused_by: line stating why weave declined to resolve them.

```bash
git merge <branch>
```

When a file does conflict, weave explain reads the actual Git stages and prints per-hunk detail for that one file.

```bash
weave explain <file>
```

After editing, weave check verifies the working tree against the three merge stages and exits 1 when it finds problems, which makes it usable as a pre-commit or CI gate. The README points to a Setup section for --global and --local variants of weave setup, so the driver can be registered per repository or for the whole machine.

## Where weave refuses, and why that is the correct behaviour

Two of the 31 scenarios in the project's benchmark must not merge, and the README argues the point rather than hiding it. When both sides add different decorators to the same Python or TypeScript function, decorator application is function composition, so stack order is a semantic decision neither side made. The README's own example is that @cache outside @auth serves cached responses without ever running the auth check. Weave refuses instead of fabricating an order. Annotations in Java, C# and Kotlin are treated as unordered metadata, so those are still set-unioned.

That is the honest boundary of the tool. Same-entity edits by both sides still conflict, and the README says so in its comparison table: both agents modifying the same function differently is a conflict in Git and a conflict in weave, the difference being that weave reports it with entity-level context. A modify-versus-delete becomes a message like function 'validateToken' (modified in ours, deleted in theirs) instead of a cryptic diff. If your workflow is two people rewriting the same function, weave buys you a better error message and nothing more. It is also a merge driver, so it does nothing for conflicts that are not semantic: binary files, lockfiles, generated artifacts and files whose language tree-sitter cannot parse fall outside its model.

## Weave against Git and mergiraf on the same scenarios

The README publishes a 31-scenario, 7-language corpus and a weave bench command to reproduce it, and compares against mergiraf v0.16.3 and plain Git. Weave reports 29 of 29 mergeable scenarios resolved cleanly and 31 of 31 correct outcomes; mergiraf reports 26 of 29 and 28 of 31; Git reports 15 of 29 and 17 of 31. All three tools correctly refuse the two decorator scenarios.

The difference in approach is the interesting part. Mergiraf is the closest comparable tool: a structural merge tool, also parsing code rather than lines. Weave's claim to a gap comes from cases the README names as both-add-at-end-of-file and insert-between-existing, which mergiraf fails on the corpus and weave resolves. Treat these numbers as the project's own benchmark on its own corpus, run with weave bench, not as an independent measurement. The honest reading is that both tools attack the same class of false conflict and weave reports better results on a corpus it wrote, over 31 scenarios, which is a small sample.

## Licence, packaging and the cost of upgrading

The repository carries LICENSE-MIT and LICENSE-APACHE, and both package.json and the README badge describe the project as MIT OR Apache-2.0, the standard Rust dual-licence arrangement. The GitHub metadata for the repository lists Apache-2.0. If your organisation cares which terms apply, read both files in the repository rather than the metadata line, since the dual grant is the more specific statement.

The workspace has six crates and the Cargo.toml notes that all of them now depend on published sem-core 0.23.0 directly, after an earlier local path override was retired once the speedup shipped upstream in sem 0.22. That is a good sign for upgrade cost: no vendored fork to track. Distribution runs through several channels at once, including Homebrew, npm and Nix (flake.nix, package.nix and shell.nix are all present), plus a fly.toml and .dockerignore at the top level. The npm wrapper downloads release binaries at postinstall and verifies checksums, which is convenient but means an install step reaches the network outside the registry; in a locked-down build environment that matters. The npm wrapper is versioned 0.5.0 while the latest release is v0.5.4, so the wrapper and the binaries it fetches do not always move together.

## Conclusion

Adopt weave if several agents or branches routinely touch different functions in the same file and you are tired of hand-resolving conflicts that carry no real disagreement. Do not adopt it as a general replacement for human merge review: same-entity edits still conflict, and the two decorator-order scenarios are refused by design. Before rolling it out, check the language coverage for your stack, confirm whether the npm wrapper's postinstall binary download is acceptable in your environment, and note that the repository ships LICENSE-MIT and LICENSE-APACHE while the GitHub metadata lists Apache-2.0, so decide which terms you are relying on.

## FAQ

### How do I install weave?

The README lists Homebrew as a channel and the repository includes a Formula directory. There is also an npm wrapper, @ataraxy-labs/weave, which downloads matching release binaries and exposes the weave, weave-driver and weave-mcp commands; it requires Node 20 or newer.

### How do I use weave after installing it?

Run weave setup in the repository, then use git merge as normal. Real conflicts still appear as markers but include a refused_by: line explaining why weave declined; weave explain <file> gives per-hunk detail and weave check verifies the working tree against the three merge stages.

### Is weave a CRDT?

No. The README states the merge algorithm is deterministic and stateless, reading three file revisions and writing one result, the same way git merge-file does. A separate crate, weave-crdt, handles live multi-agent edit coordination before changes reach Git.

### Which languages does weave support?

The README badge states 38 languages, and the benchmark corpus covers 7 languages. Parsing is done with tree-sitter, so coverage follows the grammars weave ships.

### Does weave resolve every merge conflict?

No. Different entities changed on each side are auto-resolved, but the same entity changed by both sides conflicts unless an intra-entity merge succeeds, and a modify-on-one-side, delete-on-the-other case is flagged as a meaningful conflict. Decorator-order scenarios in Python and TypeScript are refused deliberately.

## Sources

- [Ataraxy-Labs/weave on GitHub](https://github.com/Ataraxy-Labs/weave)
- [License: Apache-2.0](https://github.com/Ataraxy-Labs/weave/blob/main/LICENSE)
- [Project website](https://ataraxy-labs.github.io/weave/)
- [README](https://github.com/Ataraxy-Labs/weave/blob/main/README.md)
- [Releases](https://github.com/Ataraxy-Labs/weave/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ataraxy-labs-weave