https://github.com/Ataraxy-Labs/weave
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Ataraxy-Labs/weave with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Ataraxy-Labs/weave'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/ataraxy-labs--weave)HTML
<a href="/listings/ataraxy-labs--weave"><img src="/api/listings/ataraxy-labs--weave/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
weave setup # this repo now merges through weave; git merge/rebase/cherry-pick unchanged git merge <branch> # real conflicts land as markers with a `refused_by:` line stating why weave explain <file> # per-hunk detail for one conflicted file, read off the actual git stages # ...edit to resolve... weave check # verify the working tree against the three merge stages; exits 1 on findings, 2 if it could not verify weave land --resolver <cmd> # or: land it, each conflicted file labelled PROVEN / VERIFIED / REFUSED
See [Setup](#setup) for `--global`/`--local` variants, [CLI Commands](#cli-commands) for the rest of the `weave` binary, and [MCP Server](#mcp-server) for agent-framework integration.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 146 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # weave
- Entity-level semantic merge driver for Git. Resolves conflicts at the
- function/class level instead of the line level, so two changes to different
- functions in the same file never conflict.
- ## Setup
- ```bash
- weave setup # this repo: registers weave as the merge driver + .gitattributes
- weave setup --global # every repo on this machine, no per-repo step
- weave setup --local # this repo only, writes .git/info/attributes instead
- ```
- `weave setup` auto-detects the `weave-driver` binary, writes
- `merge.weave.driver` to git config, and adds `*.ts merge=weave` (etc.) for
- every supported extension. The equivalent by hand, if you need it:
- ```bash
- git config merge.weave.name "Entity-level semantic merge"
- git config merge.weave.driver "weave-driver %O %A %B %L %P"
- echo '*.py merge=weave' >> .gitattributes # repeat per extension you want covered
- ```
- After setup, `git merge` / `git rebase` / `git cherry-pick` all route through
- weave automatically. No new commands to run to get a merge — only to resolve
- one that still conflicts.
- ## The resolve loop
- Most merges finish clean with no conflict markers. When one entity is
- genuinely disputed by both sides, weave leaves a marker box like git's, plus
- one line stating *why*:
- ```
- <<<<<<< ours — function `process` (T, confidence: high)
- // refused_by: statement_fold · collision: ` return data.upper()` +1 more
- def process(data):
- return data.upper()
- =======
- def process(data):
- return json.dumps(data)
- >>>>>>> theirs — function `process` (T, confidence: high)
- ```
- 1. **Read the `refused_by:` line first.** It names the guard that declined to
- auto-merge and quotes the exact line(s) both sides disagree about — that's
- usually enough to resolve on the spot.
- 2. **Still unclear? Run `weave explain <file>`.** It reads the three merge
- stages straight out of git's index and reports, per conflicted entity, the
- guard, the confidence, and the hunks *both* sides actually touched —
- narrower and more precise than diffing the whole file by eye.
- 3. **Edit.** Pick a side, merge by hand, or rewrite — same as any conflict.
- Remove the marker lines. The `weave explain` hint is written on the first
- box's closing marker, so it goes when the markers go. Older weave versions
- appended it as a separate trailing comment; `weave check` flags a leftover
- copy.
- 4. **Run `weave check`.** With no arguments it verifies the working tree —
- the file as you just edited it — against the three merge stages: markers
- left behind, lines both sides kept that went missing, anything stated more
- often than either side stated it, references that no longer resolve. One
- verdict line per file, always a sentence, never a bare empty result:
- ```
- OK: src/api.py — markers cleared, no unanimous-line loss, no duplicated
- definitions or lines, no dangling references
- ```
- A file with a real problem gets `FOUND: <file> — <what and where>` plus a
- suggested repair when one follows mechanically from the finding. Exit code
- is 0 clean / 1 findings, so it composes with a script or a pre-commit hook.
- `weave check --base <rev> --ours <rev> --theirs <rev>` runs the same checks
- between two revisions instead of the working tree (useful pre-merge, or with
- no git repo at all via `--base-dir`/`--ours-dir`/`--theirs-dir`), and emits
- JSON findings instead of the verdict sentence.
- ## MCP server (for agent frameworks)
- ```bash
- claude mcp add --scope user weave -- weave-mcp
- ```
- Or any MCP client, via stdio:
- ```json
- { "mcpServers": { "weave": { "command": "weave-mcp" } } }
- ```
- `weave-mcp` discovers the repo from the first tool call's file path, the
- `WEAVE_REPO` env var, or its working directory — set `WEAVE_REPO` if you
- launch it from outside the repo. It lists one tool per command:
- `weave_edit`, `weave_preview`, `weave_explain`, `weave_check`, `weave_land` and `weave_patch`.
- For callers and blast radius use sem's MCP server. The live claim/release CRDT
- layer (`weave_claim_entity`, `weave_status`, ...) is listed only with
- `WEAVE_EXPERIMENTAL=1`. Each tool's description says when to call it and what an
- empty result means — read that at call time, not here.
- ## Reference
- | Command | Does |
- |---|---|
- | `weave setup` / `setup --off` | register / remove the git merge driver |
- | `weave land` | land a merge: gate each conflicted file PROVEN / VERIFIED / REFUSED; `--onto origin/main --check sem` merges, gates, verifies and publishes |
- | `weave explain <file>` | per-entity conflict detail for one conflicted file |
- | `weave check` | verify the working tree (or two revisions) against the merge |
- | `weave preview <branch>` | dry-run a merge before running it |
- | `weave patch extract/apply` | typed entity ops — turn a diff into ops, apply them three-way to a drifted target |
- | `weave stats` | lifetime counters; `--bench` / `--repo <path>` compare weave with git |
- | `weave explain <file> --summary` | structured JSON summary of the markers in a file |
- | `weave experimental status` / `claim` / `release` | CRDT-backed multi-agent coordination state (prototype) |
- Run `weave --help` or `weave <command> --help` for full flags.
- ### Watching a lot of merges at once
- `WEAVE_EVENT=1` makes the merge driver write one JSON line per merge to
- stderr, behind a `weave-event: ` prefix:
- ```text
- weave-event: {"schema":"weave-event","schema_version":"1.0.0","file":"src/app.py",
- "outcome":"clean","exit_code":0,"confidence":"very_high","conflicts":0,"findings":0,
- "entities":{...},"bytes_out":481,"ms_merge":4.43,"ms_total":5.72,...}
- ```
- One line per merge, including the ones that fail — so "which files conflicted
- in this rebase, on what, and how long did each take" is one pass over the
- lines rather than four stderr channels joined by hand. Off by default; nothing
- is computed for it that the driver did not already have. The fields are
- described in `crates/weave-mcp/schema/weave-event.schema.json`.
- ## Supported languages
- 38 languages and data formats — TypeScript, JavaScript, Python, Go, Rust,
- Java, C/C++, Ruby, C#, PHP, Swift, Kotlin, SQL, Lua, Nix, JSON, YAML and more
- (see README for the full list). Anything else falls back to git's standard
- line-level merge, including `.vue`, `.svelte`, `.erb` and `.hs`, which weave
- can parse but does not yet merge well enough to claim.
- ## Build & test (contributors)
- ```bash
- cargo build --release && cargo test --workspace # weave, weave-driver, weave-mcp
- ```
- License: MIT OR Apache-2.0.
README.md · README · 519 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- > **Part of the [Ataraxy Labs](https://ataraxy-labs.com) stack**, agent-native infrastructure for software development. See also: [sem](https://ataraxy-labs.com/sem) (semantic version control) · [inspect](https://github.com/Ataraxy-Labs/inspect) (semantic code review) · [opensessions](https://github.com/Ataraxy-Labs/opensessions) (tmux sidebar for coding agents).
- >
- > Read the manifesto: https://ataraxy-labs.com/#thesis · Essays: https://ataraxy-labs.com/blogs · LLMs: https://ataraxy-labs.com/llms.txt
- <p align="center">
- <img src="assets/banner.svg" alt="weave" width="600" />
- </p>
- <p align="center">
- <strong>Entity-level semantic merge for Git.</strong><br>
- Resolves merge conflicts that Git can't by parsing code into functions, classes, and keys with tree-sitter, then merging those entities instead of lines.
- </p>
- <p align="center">
- <a href="#how-weave-land-works">How weave land works</a> ·
- <a href="#install">Install</a> ·
- <a href="#quickstart">Quickstart</a> ·
- <a href="#how-weave-fixes-this">How It Works</a> ·
- <a href="#mcp-server">MCP Server</a> ·
- <a href="#cli-commands">CLI</a> ·
- <a href="https://github.com/Ataraxy-Labs/weave/releases/latest">Releases</a>
- </p>
- <p align="center">
- <a href="https://github.com/Ataraxy-Labs/weave/releases/latest"><img src="https://img.shields.io/github/v/release/Ataraxy-Labs/weave?color=blue&label=release" alt="Release"></a>
- <a href="https://formulae.brew.sh/formula/weave"><img src="https://img.shields.io/badge/homebrew-weave-orange" alt="Homebrew"></a>
- <img src="https://img.shields.io/badge/rust-stable-orange" alt="Rust">
- <img src="https://img.shields.io/badge/tests-441_passing-brightgreen" alt="Tests">
- <a href="LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT_OR_Apache--2.0-yellow" alt="License"></a>
- <img src="https://img.shields.io/badge/languages-38-blue" alt="Languages">
- </p>
- <p align="center">
- <img src="assets/merge-animation.gif" alt="Weave merge animation: two branches add different functions, git conflicts, weave merges cleanly" width="700" />
- </p>
- ## How weave land works
- `weave land` merges code and checks the result for structural problems. Add `--onto` to integrate and publish, and `--verify-cmd` or `--check sem` to validate the final tree before publishing.
- [Usage and safety](#landing-an-agents-merge-weave-land)
- ## Quickstart
- ```bash
- weave setup # this repo now merges through weave; git merge/rebase/cherry-pick unchanged
- git merge <branch> # real conflicts land as markers with a `refused_by:` line stating why
- weave explain <file> # per-hunk detail for one conflicted file, read off the actual git stages
- # ...edit to resolve...
- weave check # verify the working tree against the three merge stages; exits 1 on findings, 2 if it could not verify
- weave land --resolver <cmd> # or: land it, each conflicted file labelled PROVEN / VERIFIED / REFUSED
- ```
- See [Setup](#setup) for `--global`/`--local` variants, [CLI Commands](#cli-commands) for the rest of the
- `weave` binary, and [MCP Server](#mcp-server) for agent-framework integration.
- ## The Problem
- Git merges by comparing **lines**. When two branches both add code to the same file, even to completely different functions, Git sees overlapping line ranges and declares a conflict:
- ```
- <<<<<<< HEAD
- export function validateToken(token: string): boolean {
- return token.length > 0 && token.startsWith("sk-");
- }
- =======
- export function formatDate(date: Date): string {
- return date.toISOString().split('T')[0];
- }
- >>>>>>> feature-branch
- ```
- These are **completely independent changes**. There's no real conflict. But someone has to manually resolve it anyway.
- This happens constantly when multiple AI agents work on the same codebase. Agent A adds a function, Agent B adds a different function to the same file, and Git halts everything for a human to intervene.
- ## How Weave Fixes This
- Weave replaces Git's line-based merge with **entity-level merge**, a 3-way merge that compares base, ours, and theirs at the level of individual functions, classes, and keys instead of individual lines. That lets it tell where the two branches actually drifted apart, rather than just where their edits happen to land on the same line numbers. It works like this:
- 1. Parses all three versions (base, ours, theirs) into semantic entities: functions, classes, JSON keys, etc., using [tree-sitter](https://tree-sitter.github.io/)
- 2. Matches entities across versions by identity (name + type + scope), including renames
- 3. Merges at the entity level:
- - **Different entities changed** → auto-resolved, no conflict
- - **Same entity changed by both** → attempts intra-entity merge, conflicts only if truly incompatible
- - **One side modifies, other deletes** → flags a meaningful conflict
- Run the same scenario above through weave, and it merges cleanly with zero conflicts: both functions end up in the output.
- This merge algorithm is deterministic and stateless: it reads three file revisions and writes one result, the same way `git merge-file` does. It is not a CRDT. (Weave separately ships a CRDT-backed coordination layer, `weave-crdt`, for tracking *live* multi-agent edits before they hit Git; see [Architecture](#architecture).)
- ## Weave vs Git Merge
- | Scenario | Git (line-based) | Weave (entity-level) |
- |----------|-----------------|---------------------|
- | Two agents add different functions to same file | **CONFLICT** | Auto-resolved |
- | Agent A modifies `foo()`, Agent B adds `bar()` | **CONFLICT** (adjacent lines) | Auto-resolved |
- | Both agents modify the same function differently | CONFLICT | CONFLICT (with entity-level context) |
- | One agent modifies, other deletes same function | CONFLICT (cryptic diff) | CONFLICT: `function 'validateToken' (modified in ours, deleted in theirs)` |
- | Both agents add identical function | **CONFLICT** | Auto-resolved (identical content detected) |
- | Both agents add different properties to same object | **CONFLICT** | Auto-resolved |
- | Different JSON keys modified | **CONFLICT** | Auto-resolved |
- The key difference: Git produces false conflicts on **independent changes** because they happen to be in the same file. Weave only conflicts on **actual semantic collisions** when two branches change the same entity incompatibly.
- ## Weave vs Mergiraf
- 31 hand-crafted merge scenarios across 7 languages, comparable to [mergiraf](https://mergiraf.org/)'s own test corpus. Run `weave stats --bench` to reproduce:
- Two of the 31 **must not** merge. When both sides add different decorators to the same Python or TypeScript function, decorator application is function composition, so the stack order is a semantic decision neither side made — `@cache` outside `@auth` serves cached responses without ever running the auth check. Weave refuses rather than fabricate an order, and a tool that merges those cleanly is wrong, not better. Annotations in Java, C# and Kotlin are unordered metadata, so weave still set-unions those.
- | Tool | Clean merges (of 29 mergeable) | Correct outcomes (of 31) |
- |------|-------------------------------|--------------------------|
- | **Weave** | **29/29** (100%) | **31/31** (100%) |
- | Mergiraf (v0.16.3) | 26/29 (90%) | 28/31 (90%) |
- | Git | 15/29 (52%) | 17/31 (55%) |
- All three tools correctly refuse the two decorator scenarios. Mergiraf fails on both-add-at-end-of-file and insert-between-existing; weave resolves those because it operates at entity granularity (functions, classes, methods) rather than AST node level. Full breakdown at [ataraxy-labs.github.io/weave](https://ataraxy-labs.github.io/weave/benchmarks.html).
- ## Real-World Benchmarks
- Replayed against real merge commits from five long-lived open-source repositories. For each of the first 500 merge commits per repo, weave re-runs the merge (base/ours/theirs from the actual git history) and compares its output to both Git's line merge and the human-authored merge commit. Reproduce with `weave stats --repo <path-to-clone> --limit 500`; full per-repo breakdown, including which files disagree and why, is at [ataraxy-labs.github.io/weave/benchmarks.html](https://ataraxy-labs.github.io/weave/benchmarks.html).
- - **Win**: the line-based 3-way merge conflicted, weave resolved cleanly
- - **Regression**: the line-based 3-way merge resolved cleanly, weave conflicted
- - **Human match**: of weave's wins, how many are byte-identical (whitespace-normalized) to what the developer actually wrote
- > **Note (0.5.3):** regenerated on the 0.5.3 engine on 2026-09-01 (`weave stats --repo <clone>
- > --limit 500`, fresh full clones). Read against the previous table with three caveats, stated
- > rather than smoothed over. First, 0.5.3 conflicts on purpose where 0.5.2 sometimes resolved
- > silently (divergent same-name additions, tightened same-entity and gap verdicts) — most of the
- > regression increase is that tightening doing its job; on CPython, whose tested window is
- > identical between runs, all of it is. Second, the earlier run's exact commit window was not
- > recorded, and `stats --repo` walks the most recent N merges — for git, Go, and TypeScript the two
- > runs replay substantially different commit sets, so cross-run rate comparisons there are
- > indicative, not exact; this run's windows are current as of the date above. Third, audited
- > details: the "clean line merge" baseline is a diff3 implementation (`diffy`), which disagrees
- > with `git merge-file` on a small number of cases; 3 of the 86 regressions are a known guard
- > false-positive (files whose *source code contains conflict-marker string literals* — e.g.
- > TypeScript's own scanner); and in 2 regressions the line merge's "clean" result differs from
- > what the human actually committed, i.e. weave's refusal was arguably the safer verdict.
- | Repository | Language | File merges tested | Wins | Regressions | Human match |
- |------------|----------|--------------------:|-----:|-------------:|-------------:|
- | [git/git](https://github.com/git/git) | C | 1,701 | 183 | 23 | 72% |
- | [Flask](https://github.com/pallets/flask) | Python | 67 | 15 | 1 | 33% |
- | [CPython](https://github.com/python/cpython) | C / Python | 256 | 11 | 10 | 45% |
- | [Go](https://github.com/golang/go) | Go | 1,667 | 120 | 37 | 33% |
- | [TypeScript](https://github.com/microsoft/TypeScript) | TypeScript | 1,280 | 15 | 15 | 53% |
- Across all five repos: 344 wins on 4,971 file merges (0.5.2 measured 83 wins on 4,517), with 86 total
- regressions spread across every repo (0.5.2 measured 3, all on TypeScript). The jump in regressions is
- expected and by design, not a quality drop we're hiding: 0.5.3 now conflicts on genuinely divergent
- concurrent additions that 0.5.2 silently merged, and no longer resolves a case that could resurrect a
- deleted JSON key — both changes move cases from "weave resolves" into "weave conflicts" under this
- benchmark's own regression definition (git resolves cleanly, weave doesn't). Wins also rose substantially
- on every repo. File-merge counts and human-match rates shifted too, partly because "first 500 merge
- commits" is a moving window and all five repos have advanced since the 0.5.2 run. See the per-repo
- breakdown on the benchmarks page before relying on weave for large merges in any of these languages.
- ## Testing
- The open test suite in this repository, 441 unit and integration tests plus a five-scenario
- sweep per supported language in `crates/weave-core/tests/language_coverage.rs`, covers the
- documented merge properties and runs in CI (`cargo fmt --check`, `cargo clippy -D warnings`,
- `cargo test --workspace`) on Linux and Windows on every push and PR.
- ## Conflict Markers
- When a real conflict occurs, weave gives you context that Git doesn't: which
- entity, what type, and, on the line inside the box, which internal guard
- declined to auto-merge and exactly which lines both sides disagree about.
- ```
- <<<<<<< ours — function `process` (T, confidence: high)
- // refused_by: statement_fold · collision: ` return data.upper()` +1 more
- export function process(data: any) {
- return JSON.stringify(data);
- }
- =======
- export function process(data: any) {
- return data.toUpperCase();
- }
- >>>>>>> theirs — function `process` (T, confidence: high)
- ```
- Run `weave explain <file>` for more detail on every conflicted entity in the
- file, and `weave check` after editing to verify your resolution against the
- three merge stages; see [Quickstart](#quickstart).
- ## Supported Languages
- TypeScript, TSX, JavaScript, Python, Go, Rust, Java, C, C++, Ruby, C#, PHP, Swift, Kotlin, Scala, Dart, Elixir, Bash, Fish, Fortran, Perl, OCaml, Zig, Elm, Clojure, EDN, D, Lua, Nix, SQL, HCL/Terraform, LaTeX, XML, JSON, YAML, TOML, CSV, Markdown. Falls back to standard line-level merge for everything else.
- `weave setup` derives its `.gitattributes` rules directly from the parser
- registry: every extension the tree-sitter grammars recognize gets a
- `merge=weave` line automatically, with no hand-maintained list to fall
- behind. Each language on it passes a five-scenario merge sweep (two sides
- adding different definitions merges clean, two sides rewriting the same
- definition conflicts, and nothing is dropped) in
- `crates/weave-core/tests/language_coverage.rs`, and a separate parity test
- (`crates/weave-core/tests/setup_extension_coverage.rs`) fails the build if a
- newly added grammar is ever left unclaimed and undeclined.
- INI files (`*.ini`, `*.cfg`) have no grammar but are claimed too
- (`weave_core::LINE_RULE_EXTENSIONS`): they take Git's line merge, plus the
- rule that unites keys two sides added to one section.
- Vue, Svelte, ERB and Haskell are parsed but deliberately **not** claimed:
- weave declines exactly these four (`weave_core::DECLINED_EXTENSIONS`), and
- nothing else. Their entity model treats a whole `<script>` block, template,
- or type signature as a single unit, so two people adding two different
- definitions conflict where they should merge cleanly, and the conflict
- marker can land mid-definition. Those files get Git's line-level merge
- instead, which is the better answer until the parser gains a real
- per-definition model for them. They're excluded from `weave setup`
- automatically; nothing to opt out of by hand.
- ## Install
- ```bash
- brew install weave
- ```
- Or build from source (requires Rust). Two binaries, both required: `weave`
- (the CLI you run: `setup`/`explain`/`check`/...) and `weave-driver` (the one
- git itself invokes on every merge; `weave setup` fails without it on `PATH`):
- ```bash
- git clone https://github.com/Ataraxy-Labs/weave
- cd weave
- cargo install --path crates/weave-cli # the `weave` binary
- cargo install --path crates/weave-driver # the `weave-driver` binary git calls
- ```
- Upgrading an existing source install? `cargo install` refuses to overwrite a
- binary it didn't put there itself, so add `--force` to either command above.
- ## Setup
- In any Git repo:
- ```bash
- weave setup
- ```
- This configures Git to use weave for all supported file types. Then use `git merge` as normal.
- To revert back to normal git merging:
- ```bash
- weave setup --off
- ```
- To set up for just yourself (without modifying `.gitattributes`), write the same supported file type rules to `.git/info/attributes` instead:
- ```bash
- weave setup --local
- ```
- ### Global (every repo)
- To make weave the default merge driver for **all** your repos at once (no per-repo setup, like [mergiraf](https://mergiraf.org/usage.html#registration-as-a-git-merge-driver)):
- ```bash
- weave setup --global
- ```
- This writes the driver to your `~/.gitconfig` and the supported file-type rules to git's global attributes file (`~/.config/git/attributes`, or your `core.attributesfile` if set). No git repo required. Make sure `weave-driver` is on your `PATH` (it ships next to the `weave` binary).
- The equivalent manual config, if you prefer:
- ```bash
- git config --global merge.weave.name "Entity-level semantic merge"
- git config --global merge.weave.driver "weave-driver %O %A %B %L %P"
- # then add `*.ts merge=weave` (etc.) to ~/.config/git/attributes
- ```
- ### Declaring a container a set (`weave-set`)
- When two branches each add an entry at the same point of one container,
- weave unites them only if the container's order carries no meaning: a
- Python dict or JS/TS object literal with constant keys, `__all__`, an
- `import`/`export` name list, the keys of one INI section, TOML/JSON/YAML
- keys. The union never depends on which side is "ours", and in a Python,
- JS/TS or INI container it is merged by key, so a fleet of branches that
- each add one entry lands on one tree whatever order they merge in (an entry
- under its own comment keeps its run together instead).
- A list, a statement sequence, match/switch arms, an INI multi-line value or
- a YAML sequence is ordered in general (the first matching arm wins, a
- parametrize list names test ids by position), so two insertions at one point
- stay a conflict. So do the entries two branches add to one section of a
- changelog: two differently worded bullets can describe one change, and
- telling them apart is not a set's job. If you know one of yours is really a
- set, say so with the `weave-set` gitattribute:
- ```gitattributes
- setup.cfg weave-set=console_scripts
- tests/test_*.py weave-set=parametrize
- src/cli.py weave-set=build_parser
- .pre-commit-hooks.yaml weave-set
- CHANGELOG.md weave-set=Unreleased
- ```
- A bare `weave-set` makes every container in the file a set; a value is a
- comma-separated list of container names: the variable a literal is assigned
- to, the key it is the value of, the function it is an argument of
- (`parametrize`), the function whose body or match arms it is, the INI key of
- a multi-line value, the YAML/JSON/TOML key of an array, the title of a
- changelog section or of a heading above it (brackets off, or its first word:
- `## [Unreleased]` is `Unreleased`, `## 1.2.0 - 2026-01-01` is `1.2.0`). The driver reads the
- attribute with `git check-attr` only when such a container is what stands
- between a conflict and a union. Every union is still checked: an entry
- edited, deleted or moved beside the insertion, one key with two values, or
- an answer that does not parse stays a conflict.
- ## Jujutsu (jj)
- Add to your jj config (`jj config edit --user`):
- ```toml
- [merge-tools.weave]
- program = "weave-driver"
- merge-args = ["$base", "$left", "$right", "-o", "$output", "-l", "$marker_length", "-p", "$path"]
- merge-conflict-exit-codes = [1]
- merge-tool-edits-conflict-markers = true
- conflict-marker-style = "git"
- ```
- Resolve conflicts with `jj resolve --tool weave`, or set as default:
- ```bash
- jj config set --user ui.merge-editor "weave"
- ```
- ## Preview
- Dry-run a merge to see what weave would do:
- ```bash
- weave preview feature-branch
- ```
- ```
- src/utils.ts — auto-resolved
- unchanged: 2, added-ours: 1, added-theirs: 1
- src/api.ts — 1 conflict(s)
- ✗ function `process`: both modified
- ✓ Merge would be clean (1 file(s) auto-resolved by weave)
- ```
- After a real conflict, `weave explain <file>` and `weave check` are the
- next two commands; see [Quickstart](#quickstart).
- ## Landing an agent's merge: `weave land`
- Resolve a merge in progress, check its result, and stage accepted files:
- ```bash
- weave land
- weave land --resolver '<resolver-command>' --certificate land.json
- ```
- A resolver is optional. It receives merge inputs as JSON on stdin and returns a resolved file. Rejected answers are not written; unresolved files remain conflicted.
- | Result | Meaning |
- |---|---|
- | **PROVEN** | The result satisfies the supported structural proof rules. |
- | **VERIFIED** | The result passed the merge gate, without a structural proof. |
- | **REFUSED** | The result was not accepted; resolve the reported findings. |
- These labels describe merge checks, not proof that the program behaves correctly. The gate checks individual files for problems such as lost changes, duplicates, and invalid syntax; it does not establish cross-file or runtime correctness.
- ### Integrate and publish
- `--onto` merges the target branch, gates the result, runs configured validation, and publishes fast-forward only. If the target moves, it retries against the new tip.
- ```bash
- weave land --onto origin/main --verify-cmd 'go build ./... && go test ./...'
- # Or use Sem's project checkers:
- weave land --onto origin/main --check sem
- ```
- **Configure validation before publishing.** A failed gate or configured validation refuses publication. Without `--onto`, `weave land` does not publish.
- Use `--dry-run` to inspect without writing, `--json` for structured output, and `weave land --help` for resolver inputs, revision selection, timeouts, and other options. Exit codes: `0` accepted, `1` refused, `2` execution error.
- ## CLI Commands
- Seven commands. Each `--help` line says which question the command answers, and every flag has an example (`weave <command> --help`).
- | Command | The question it answers |
- |---|---|
- | `weave setup [--global] [--local] [--off]` | Make `git merge` use weave here (`--global`: every repo; `--off`: stop) |
- | `weave land [--resolver <cmd>] [--onto <remote>/<branch>] [--verify-cmd <cmd>] [--check sem] [--queue]` | Can this merge land? Merge, gate every file (PROVEN / VERIFIED / REFUSED), verify, publish; see [above](#landing-an-agents-merge-weave-land). `--queue` is experimental |
- | `weave explain <file> [--summary] [--json]` | Why did this file conflict? `--summary`: a structured summary of the weave markers in any file |
- | `weave check [--json]` | Is my conflict resolution right? Lost lines, duplicates, leftover markers, dangling names |
- | `weave preview <branch> [--file <path>]` | What would merging this branch look like? Nothing is written |
- | `weave patch extract <base-file> <changed-file>` / `weave patch apply <ops-file> <target-file>` | Apply an edit to a file that drifted: typed entity ops, merged three-way against the ops' base |
- | `weave stats [--bench] [--repo <path> --limit N]` | How has weave done? Lifetime counters if you opted in with `WEAVE_STATS=1`; `--bench` runs the 31-scenario synthetic benchmark; `--repo` replays real merge commits from a clone (see [Real-World Benchmarks](#real-world-benchmarks)) |
- Every earlier command name still works, with the same output. At a terminal weave prints a one-line note on stderr with the new spelling; in `--json` mode or when output is piped it prints nothing extra.
- | Old | New |
- |---|---|
- | `weave unsetup` | `weave setup --off` |
- | `weave summary <file>` | `weave explain <file> --summary` |
- | `weave bench` | `weave stats --bench` |
- | `weave bench-repo <path>` | `weave stats --repo <path>` |
- | `weave claim`, `release`, `status`, `apply` | `weave experimental claim`, `release`, `status`, `apply` |
- The `weave experimental` group (hidden from `--help`) is the live-editing prototype: it claims and releases entities and applies edits held in the `.weave/state.automerge` CRDT document, the same document the MCP coordination tools below use. Claims are advisory. That document lives in the repo's working tree but is never repo content: the first time weave writes it, it adds `.weave/` to the repo's local `.git/info/exclude` (never your own `.gitignore`), so it never shows up in `git status` or gets swept into `git add -A`.
- ## MCP Server
- For agent frameworks that speak [MCP](https://modelcontextprotocol.io):
- ```bash
- # Claude Code
- claude mcp add --scope user weave -- weave-mcp
- # Any MCP client, via stdio (~/.config/claude/claude_desktop_config.json etc.)
- { "mcpServers": { "weave": { "command": "weave-mcp" } } }
- ```
- The server discovers the repo from each tool call's absolute file path, else the
- `WEAVE_REPO` env var, or its working directory. It lists six tools, one per
- `weave` command (each tool's own description states when to call it and what an
- empty result means):
- - `weave_preview`: dry-run a merge of two branches, as per-file verdicts, a
- findings document, or the strategy weave used on each entity.
- - `weave_edit`: change code by entity, written straight to disk: replace an entity, edit
- text inside it, add one before or after it, delete it, or create a file. A batch is all or
- nothing, and an edit that breaks the parse or quietly renames an entity is refused.
- - `weave_explain`: why a file conflicted, from the merge's three stages.
- - `weave_check`: is the resolution right, plus the cross-file breakage a per-file
- merge driver can't see (a rename in `a.py` whose surviving caller lives in `b.py`).
- - `weave_land`: label every file of a stopped merge PROVEN, VERIFIED or REFUSED, and
- write the ones that pass.
- - `weave_patch`: carry an edit to a file that drifted, as a three-way entity merge.
- For callers, dependencies and blast radius, use [sem](https://github.com/Ataraxy-Labs/sem)'s
- MCP server. The live multi-agent CRDT tools (`weave_claim_entity`,
- `weave_update_entity_content`, ...) are listed only with `WEAVE_EXPERIMENTAL=1`. Every
- older tool name still answers when called, so existing clients keep working.
- ## Architecture
- ```
- weave-core # Library: entity extraction, entity-level 3-way merge, reconstruction
- weave-driver # Git merge driver binary (called by git via %O %A %B %L %P)
- weave-cli # CLI: `weave setup`, `weave explain`, `weave check`, `weave patch`, ...
- weave-crdt # Automerge-backed CRDT: live multi-agent coordination state only
- weave-mcp # MCP server exposing weave to agent frameworks (one tool per command)
- weave-github # GitHub webhook service behind the hosted PR-comment integration
- # (publish = false, not a binary you install; runs weave's merge
- # analysis on pull_request events and posts the result as a comment)
- ```
- Uses [sem-core](https://github.com/Ataraxy-Labs/sem) for entity extraction via tree-sitter grammars.
- The merge algorithm (`weave-core`) and the coordination state (`weave-crdt`) are
- deliberately separate concerns with different data models: the merge is a pure
- function over three file revisions, run fresh on every `git merge`/`weave preview`/
- `weave check` call. The CRDT is the thing that persists; it's what lets two live
- agents see each other's claims and in-flight edits *before* either one commits,
- via `weave_claim_entity`/`weave_update_entity_content` or `weave experimental claim`/`weave experimental apply`.
- Nothing in the merge path depends on the CRDT ever having run.
- ## How It Works
- ```
- base
- / \
- ours theirs
- \ /
- weave merge
- ```
- 1. **Parse** all three versions into semantic entities via tree-sitter
- 2. **Extract regions**, alternating entity and interstitial (imports, whitespace) segments
- 3. **Match entities** across versions by ID (file:type:name:parent), detecting renames
- 4. **Resolve** each entity: one-side-only changes win, both-changed attempts intra-entity 3-way merge
- 5. **Reconstruct** file from merged regions, preserving ours-side ordering
- 6. **Fallback** to line-level merge for files >1MB, binary files, or unsupported types
- ## Limitations
- - **Vue, Svelte, ERB, Haskell** parse, but their per-file entity model is too coarse to merge
- well, so they take Git's line merge, always (see [Supported Languages](#supported-languages)).
- - **Files over 1MB, binary files, and file types with no parser** fall back to Git's line-level
- merge automatically.
- - **Entity claims are advisory, not enforced.** `weave_claim_entity` and `weave experimental claim` are
- cooperative locks inside the CRDT coordination layer; weave does not stop a second agent
- (or you) from editing a claimed entity anyway.
- - **Crashed agents aren't reaped.** `weave_agent_heartbeat`'s liveness timestamp is informational;
- weave does not currently expire or release a claim automatically when an agent stops
- heartbeating, so a crashed agent's claims stay visible until another call to
- `weave_release_entity`/`weave experimental release`.
- - **`weave stats` is empty until you opt in.** Lifetime merge counters are off by default; set
- `WEAVE_STATS=1` in the environment your git/jj merges run in to start accumulating them.
- ## Contributing
- Bug reports and issues are welcome. This is a small team maintaining a merge engine that
- runs inside other people's git workflows: incoming PRs get read, but are reviewed and
- adapted before merge rather than merged as-is. Open an issue first for anything beyond a
- small, obviously-correct fix, so the approach can be agreed on before you write the code.
- ## License
- Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option.
- ## Star History
- [](https://star-history.com/#Ataraxy-Labs/weave&Date)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.