Skip to content
Back to search

https://github.com/Ataraxy-Labs/weave

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ataraxy-labs--weave/badge.svg)](/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

i

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.

  1. # weave
  2. Entity-level semantic merge driver for Git. Resolves conflicts at the
  3. function/class level instead of the line level, so two changes to different
  4. functions in the same file never conflict.
  5. ## Setup
  6. ```bash
  7. weave setup # this repo: registers weave as the merge driver + .gitattributes
  8. weave setup --global # every repo on this machine, no per-repo step
  9. weave setup --local # this repo only, writes .git/info/attributes instead
  10. ```
  11. `weave setup` auto-detects the `weave-driver` binary, writes
  12. `merge.weave.driver` to git config, and adds `*.ts merge=weave` (etc.) for
  13. every supported extension. The equivalent by hand, if you need it:
  14. ```bash
  15. git config merge.weave.name "Entity-level semantic merge"
  16. git config merge.weave.driver "weave-driver %O %A %B %L %P"
  17. echo '*.py merge=weave' >> .gitattributes # repeat per extension you want covered
  18. ```
  19. After setup, `git merge` / `git rebase` / `git cherry-pick` all route through
  20. weave automatically. No new commands to run to get a merge — only to resolve
  21. one that still conflicts.
  22. ## The resolve loop
  23. Most merges finish clean with no conflict markers. When one entity is
  24. genuinely disputed by both sides, weave leaves a marker box like git's, plus
  25. one line stating *why*:
  26. ```
  27. <<<<<<< ours — function `process` (T, confidence: high)
  28. // refused_by: statement_fold · collision: ` return data.upper()` +1 more
  29. def process(data):
  30. return data.upper()
  31. =======
  32. def process(data):
  33. return json.dumps(data)
  34. >>>>>>> theirs — function `process` (T, confidence: high)
  35. ```
  36. 1. **Read the `refused_by:` line first.** It names the guard that declined to
  37. auto-merge and quotes the exact line(s) both sides disagree about — that's
  38. usually enough to resolve on the spot.
  39. 2. **Still unclear? Run `weave explain <file>`.** It reads the three merge
  40. stages straight out of git's index and reports, per conflicted entity, the
  41. guard, the confidence, and the hunks *both* sides actually touched —
  42. narrower and more precise than diffing the whole file by eye.
  43. 3. **Edit.** Pick a side, merge by hand, or rewrite — same as any conflict.
  44. Remove the marker lines. The `weave explain` hint is written on the first
  45. box's closing marker, so it goes when the markers go. Older weave versions
  46. appended it as a separate trailing comment; `weave check` flags a leftover
  47. copy.
  48. 4. **Run `weave check`.** With no arguments it verifies the working tree —
  49. the file as you just edited it — against the three merge stages: markers
  50. left behind, lines both sides kept that went missing, anything stated more
  51. often than either side stated it, references that no longer resolve. One
  52. verdict line per file, always a sentence, never a bare empty result:
  53. ```
  54. OK: src/api.py — markers cleared, no unanimous-line loss, no duplicated
  55. definitions or lines, no dangling references
  56. ```
  57. A file with a real problem gets `FOUND: <file> — <what and where>` plus a
  58. suggested repair when one follows mechanically from the finding. Exit code
  59. is 0 clean / 1 findings, so it composes with a script or a pre-commit hook.
  60. `weave check --base <rev> --ours <rev> --theirs <rev>` runs the same checks
  61. between two revisions instead of the working tree (useful pre-merge, or with
  62. no git repo at all via `--base-dir`/`--ours-dir`/`--theirs-dir`), and emits
  63. JSON findings instead of the verdict sentence.
  64. ## MCP server (for agent frameworks)
  65. ```bash
  66. claude mcp add --scope user weave -- weave-mcp
  67. ```
  68. Or any MCP client, via stdio:
  69. ```json
  70. { "mcpServers": { "weave": { "command": "weave-mcp" } } }
  71. ```
  72. `weave-mcp` discovers the repo from the first tool call's file path, the
  73. `WEAVE_REPO` env var, or its working directory — set `WEAVE_REPO` if you
  74. launch it from outside the repo. It lists one tool per command:
  75. `weave_edit`, `weave_preview`, `weave_explain`, `weave_check`, `weave_land` and `weave_patch`.
  76. For callers and blast radius use sem's MCP server. The live claim/release CRDT
  77. layer (`weave_claim_entity`, `weave_status`, ...) is listed only with
  78. `WEAVE_EXPERIMENTAL=1`. Each tool's description says when to call it and what an
  79. empty result means — read that at call time, not here.
  80. ## Reference
  81. | Command | Does |
  82. |---|---|
  83. | `weave setup` / `setup --off` | register / remove the git merge driver |
  84. | `weave land` | land a merge: gate each conflicted file PROVEN / VERIFIED / REFUSED; `--onto origin/main --check sem` merges, gates, verifies and publishes |
  85. | `weave explain <file>` | per-entity conflict detail for one conflicted file |
  86. | `weave check` | verify the working tree (or two revisions) against the merge |
  87. | `weave preview <branch>` | dry-run a merge before running it |
  88. | `weave patch extract/apply` | typed entity ops — turn a diff into ops, apply them three-way to a drifted target |
  89. | `weave stats` | lifetime counters; `--bench` / `--repo <path>` compare weave with git |
  90. | `weave explain <file> --summary` | structured JSON summary of the markers in a file |
  91. | `weave experimental status` / `claim` / `release` | CRDT-backed multi-agent coordination state (prototype) |
  92. Run `weave --help` or `weave <command> --help` for full flags.
  93. ### Watching a lot of merges at once
  94. `WEAVE_EVENT=1` makes the merge driver write one JSON line per merge to
  95. stderr, behind a `weave-event: ` prefix:
  96. ```text
  97. weave-event: {"schema":"weave-event","schema_version":"1.0.0","file":"src/app.py",
  98. "outcome":"clean","exit_code":0,"confidence":"very_high","conflicts":0,"findings":0,
  99. "entities":{...},"bytes_out":481,"ms_merge":4.43,"ms_total":5.72,...}
  100. ```
  101. One line per merge, including the ones that fail — so "which files conflicted
  102. in this rebase, on what, and how long did each take" is one pass over the
  103. lines rather than four stderr channels joined by hand. Off by default; nothing
  104. is computed for it that the driver did not already have. The fields are
  105. described in `crates/weave-mcp/schema/weave-event.schema.json`.
  106. ## Supported languages
  107. 38 languages and data formats — TypeScript, JavaScript, Python, Go, Rust,
  108. Java, C/C++, Ruby, C#, PHP, Swift, Kotlin, SQL, Lua, Nix, JSON, YAML and more
  109. (see README for the full list). Anything else falls back to git's standard
  110. line-level merge, including `.vue`, `.svelte`, `.erb` and `.hs`, which weave
  111. can parse but does not yet merge well enough to claim.
  112. ## Build & test (contributors)
  113. ```bash
  114. cargo build --release && cargo test --workspace # weave, weave-driver, weave-mcp
  115. ```
  116. 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.

  1. > **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).
  2. >
  3. > Read the manifesto: https://ataraxy-labs.com/#thesis · Essays: https://ataraxy-labs.com/blogs · LLMs: https://ataraxy-labs.com/llms.txt
  4. <p align="center">
  5. <img src="assets/banner.svg" alt="weave" width="600" />
  6. </p>
  7. <p align="center">
  8. <strong>Entity-level semantic merge for Git.</strong><br>
  9. 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.
  10. </p>
  11. <p align="center">
  12. <a href="#how-weave-land-works">How weave land works</a> ·
  13. <a href="#install">Install</a> ·
  14. <a href="#quickstart">Quickstart</a> ·
  15. <a href="#how-weave-fixes-this">How It Works</a> ·
  16. <a href="#mcp-server">MCP Server</a> ·
  17. <a href="#cli-commands">CLI</a> ·
  18. <a href="https://github.com/Ataraxy-Labs/weave/releases/latest">Releases</a>
  19. </p>
  20. <p align="center">
  21. <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>
  22. <a href="https://formulae.brew.sh/formula/weave"><img src="https://img.shields.io/badge/homebrew-weave-orange" alt="Homebrew"></a>
  23. <img src="https://img.shields.io/badge/rust-stable-orange" alt="Rust">
  24. <img src="https://img.shields.io/badge/tests-441_passing-brightgreen" alt="Tests">
  25. <a href="LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT_OR_Apache--2.0-yellow" alt="License"></a>
  26. <img src="https://img.shields.io/badge/languages-38-blue" alt="Languages">
  27. </p>
  28. <p align="center">
  29. <img src="assets/merge-animation.gif" alt="Weave merge animation: two branches add different functions, git conflicts, weave merges cleanly" width="700" />
  30. </p>
  31. ## How weave land works
  32. `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.
  33. [Usage and safety](#landing-an-agents-merge-weave-land)
  34. ## Quickstart
  35. ```bash
  36. weave setup # this repo now merges through weave; git merge/rebase/cherry-pick unchanged
  37. git merge <branch> # real conflicts land as markers with a `refused_by:` line stating why
  38. weave explain <file> # per-hunk detail for one conflicted file, read off the actual git stages
  39. # ...edit to resolve...
  40. weave check # verify the working tree against the three merge stages; exits 1 on findings, 2 if it could not verify
  41. weave land --resolver <cmd> # or: land it, each conflicted file labelled PROVEN / VERIFIED / REFUSED
  42. ```
  43. See [Setup](#setup) for `--global`/`--local` variants, [CLI Commands](#cli-commands) for the rest of the
  44. `weave` binary, and [MCP Server](#mcp-server) for agent-framework integration.
  45. ## The Problem
  46. 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:
  47. ```
  48. <<<<<<< HEAD
  49. export function validateToken(token: string): boolean {
  50. return token.length > 0 && token.startsWith("sk-");
  51. }
  52. =======
  53. export function formatDate(date: Date): string {
  54. return date.toISOString().split('T')[0];
  55. }
  56. >>>>>>> feature-branch
  57. ```
  58. These are **completely independent changes**. There's no real conflict. But someone has to manually resolve it anyway.
  59. 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.
  60. ## How Weave Fixes This
  61. 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:
  62. 1. Parses all three versions (base, ours, theirs) into semantic entities: functions, classes, JSON keys, etc., using [tree-sitter](https://tree-sitter.github.io/)
  63. 2. Matches entities across versions by identity (name + type + scope), including renames
  64. 3. Merges at the entity level:
  65. - **Different entities changed** → auto-resolved, no conflict
  66. - **Same entity changed by both** → attempts intra-entity merge, conflicts only if truly incompatible
  67. - **One side modifies, other deletes** → flags a meaningful conflict
  68. Run the same scenario above through weave, and it merges cleanly with zero conflicts: both functions end up in the output.
  69. 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).)
  70. ## Weave vs Git Merge
  71. | Scenario | Git (line-based) | Weave (entity-level) |
  72. |----------|-----------------|---------------------|
  73. | Two agents add different functions to same file | **CONFLICT** | Auto-resolved |
  74. | Agent A modifies `foo()`, Agent B adds `bar()` | **CONFLICT** (adjacent lines) | Auto-resolved |
  75. | Both agents modify the same function differently | CONFLICT | CONFLICT (with entity-level context) |
  76. | One agent modifies, other deletes same function | CONFLICT (cryptic diff) | CONFLICT: `function 'validateToken' (modified in ours, deleted in theirs)` |
  77. | Both agents add identical function | **CONFLICT** | Auto-resolved (identical content detected) |
  78. | Both agents add different properties to same object | **CONFLICT** | Auto-resolved |
  79. | Different JSON keys modified | **CONFLICT** | Auto-resolved |
  80. 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.
  81. ## Weave vs Mergiraf
  82. 31 hand-crafted merge scenarios across 7 languages, comparable to [mergiraf](https://mergiraf.org/)'s own test corpus. Run `weave stats --bench` to reproduce:
  83. 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.
  84. | Tool | Clean merges (of 29 mergeable) | Correct outcomes (of 31) |
  85. |------|-------------------------------|--------------------------|
  86. | **Weave** | **29/29** (100%) | **31/31** (100%) |
  87. | Mergiraf (v0.16.3) | 26/29 (90%) | 28/31 (90%) |
  88. | Git | 15/29 (52%) | 17/31 (55%) |
  89. 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).
  90. ## Real-World Benchmarks
  91. 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).
  92. - **Win**: the line-based 3-way merge conflicted, weave resolved cleanly
  93. - **Regression**: the line-based 3-way merge resolved cleanly, weave conflicted
  94. - **Human match**: of weave's wins, how many are byte-identical (whitespace-normalized) to what the developer actually wrote
  95. > **Note (0.5.3):** regenerated on the 0.5.3 engine on 2026-09-01 (`weave stats --repo <clone>
  96. > --limit 500`, fresh full clones). Read against the previous table with three caveats, stated
  97. > rather than smoothed over. First, 0.5.3 conflicts on purpose where 0.5.2 sometimes resolved
  98. > silently (divergent same-name additions, tightened same-entity and gap verdicts) — most of the
  99. > regression increase is that tightening doing its job; on CPython, whose tested window is
  100. > identical between runs, all of it is. Second, the earlier run's exact commit window was not
  101. > recorded, and `stats --repo` walks the most recent N merges — for git, Go, and TypeScript the two
  102. > runs replay substantially different commit sets, so cross-run rate comparisons there are
  103. > indicative, not exact; this run's windows are current as of the date above. Third, audited
  104. > details: the "clean line merge" baseline is a diff3 implementation (`diffy`), which disagrees
  105. > with `git merge-file` on a small number of cases; 3 of the 86 regressions are a known guard
  106. > false-positive (files whose *source code contains conflict-marker string literals* — e.g.
  107. > TypeScript's own scanner); and in 2 regressions the line merge's "clean" result differs from
  108. > what the human actually committed, i.e. weave's refusal was arguably the safer verdict.
  109. | Repository | Language | File merges tested | Wins | Regressions | Human match |
  110. |------------|----------|--------------------:|-----:|-------------:|-------------:|
  111. | [git/git](https://github.com/git/git) | C | 1,701 | 183 | 23 | 72% |
  112. | [Flask](https://github.com/pallets/flask) | Python | 67 | 15 | 1 | 33% |
  113. | [CPython](https://github.com/python/cpython) | C / Python | 256 | 11 | 10 | 45% |
  114. | [Go](https://github.com/golang/go) | Go | 1,667 | 120 | 37 | 33% |
  115. | [TypeScript](https://github.com/microsoft/TypeScript) | TypeScript | 1,280 | 15 | 15 | 53% |
  116. Across all five repos: 344 wins on 4,971 file merges (0.5.2 measured 83 wins on 4,517), with 86 total
  117. regressions spread across every repo (0.5.2 measured 3, all on TypeScript). The jump in regressions is
  118. expected and by design, not a quality drop we're hiding: 0.5.3 now conflicts on genuinely divergent
  119. concurrent additions that 0.5.2 silently merged, and no longer resolves a case that could resurrect a
  120. deleted JSON key — both changes move cases from "weave resolves" into "weave conflicts" under this
  121. benchmark's own regression definition (git resolves cleanly, weave doesn't). Wins also rose substantially
  122. on every repo. File-merge counts and human-match rates shifted too, partly because "first 500 merge
  123. commits" is a moving window and all five repos have advanced since the 0.5.2 run. See the per-repo
  124. breakdown on the benchmarks page before relying on weave for large merges in any of these languages.
  125. ## Testing
  126. The open test suite in this repository, 441 unit and integration tests plus a five-scenario
  127. sweep per supported language in `crates/weave-core/tests/language_coverage.rs`, covers the
  128. documented merge properties and runs in CI (`cargo fmt --check`, `cargo clippy -D warnings`,
  129. `cargo test --workspace`) on Linux and Windows on every push and PR.
  130. ## Conflict Markers
  131. When a real conflict occurs, weave gives you context that Git doesn't: which
  132. entity, what type, and, on the line inside the box, which internal guard
  133. declined to auto-merge and exactly which lines both sides disagree about.
  134. ```
  135. <<<<<<< ours — function `process` (T, confidence: high)
  136. // refused_by: statement_fold · collision: ` return data.upper()` +1 more
  137. export function process(data: any) {
  138. return JSON.stringify(data);
  139. }
  140. =======
  141. export function process(data: any) {
  142. return data.toUpperCase();
  143. }
  144. >>>>>>> theirs — function `process` (T, confidence: high)
  145. ```
  146. Run `weave explain <file>` for more detail on every conflicted entity in the
  147. file, and `weave check` after editing to verify your resolution against the
  148. three merge stages; see [Quickstart](#quickstart).
  149. ## Supported Languages
  150. 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.
  151. `weave setup` derives its `.gitattributes` rules directly from the parser
  152. registry: every extension the tree-sitter grammars recognize gets a
  153. `merge=weave` line automatically, with no hand-maintained list to fall
  154. behind. Each language on it passes a five-scenario merge sweep (two sides
  155. adding different definitions merges clean, two sides rewriting the same
  156. definition conflicts, and nothing is dropped) in
  157. `crates/weave-core/tests/language_coverage.rs`, and a separate parity test
  158. (`crates/weave-core/tests/setup_extension_coverage.rs`) fails the build if a
  159. newly added grammar is ever left unclaimed and undeclined.
  160. INI files (`*.ini`, `*.cfg`) have no grammar but are claimed too
  161. (`weave_core::LINE_RULE_EXTENSIONS`): they take Git's line merge, plus the
  162. rule that unites keys two sides added to one section.
  163. Vue, Svelte, ERB and Haskell are parsed but deliberately **not** claimed:
  164. weave declines exactly these four (`weave_core::DECLINED_EXTENSIONS`), and
  165. nothing else. Their entity model treats a whole `<script>` block, template,
  166. or type signature as a single unit, so two people adding two different
  167. definitions conflict where they should merge cleanly, and the conflict
  168. marker can land mid-definition. Those files get Git's line-level merge
  169. instead, which is the better answer until the parser gains a real
  170. per-definition model for them. They're excluded from `weave setup`
  171. automatically; nothing to opt out of by hand.
  172. ## Install
  173. ```bash
  174. brew install weave
  175. ```
  176. Or build from source (requires Rust). Two binaries, both required: `weave`
  177. (the CLI you run: `setup`/`explain`/`check`/...) and `weave-driver` (the one
  178. git itself invokes on every merge; `weave setup` fails without it on `PATH`):
  179. ```bash
  180. git clone https://github.com/Ataraxy-Labs/weave
  181. cd weave
  182. cargo install --path crates/weave-cli # the `weave` binary
  183. cargo install --path crates/weave-driver # the `weave-driver` binary git calls
  184. ```
  185. Upgrading an existing source install? `cargo install` refuses to overwrite a
  186. binary it didn't put there itself, so add `--force` to either command above.
  187. ## Setup
  188. In any Git repo:
  189. ```bash
  190. weave setup
  191. ```
  192. This configures Git to use weave for all supported file types. Then use `git merge` as normal.
  193. To revert back to normal git merging:
  194. ```bash
  195. weave setup --off
  196. ```
  197. To set up for just yourself (without modifying `.gitattributes`), write the same supported file type rules to `.git/info/attributes` instead:
  198. ```bash
  199. weave setup --local
  200. ```
  201. ### Global (every repo)
  202. 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)):
  203. ```bash
  204. weave setup --global
  205. ```
  206. 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).
  207. The equivalent manual config, if you prefer:
  208. ```bash
  209. git config --global merge.weave.name "Entity-level semantic merge"
  210. git config --global merge.weave.driver "weave-driver %O %A %B %L %P"
  211. # then add `*.ts merge=weave` (etc.) to ~/.config/git/attributes
  212. ```
  213. ### Declaring a container a set (`weave-set`)
  214. When two branches each add an entry at the same point of one container,
  215. weave unites them only if the container's order carries no meaning: a
  216. Python dict or JS/TS object literal with constant keys, `__all__`, an
  217. `import`/`export` name list, the keys of one INI section, TOML/JSON/YAML
  218. keys. The union never depends on which side is "ours", and in a Python,
  219. JS/TS or INI container it is merged by key, so a fleet of branches that
  220. each add one entry lands on one tree whatever order they merge in (an entry
  221. under its own comment keeps its run together instead).
  222. A list, a statement sequence, match/switch arms, an INI multi-line value or
  223. a YAML sequence is ordered in general (the first matching arm wins, a
  224. parametrize list names test ids by position), so two insertions at one point
  225. stay a conflict. So do the entries two branches add to one section of a
  226. changelog: two differently worded bullets can describe one change, and
  227. telling them apart is not a set's job. If you know one of yours is really a
  228. set, say so with the `weave-set` gitattribute:
  229. ```gitattributes
  230. setup.cfg weave-set=console_scripts
  231. tests/test_*.py weave-set=parametrize
  232. src/cli.py weave-set=build_parser
  233. .pre-commit-hooks.yaml weave-set
  234. CHANGELOG.md weave-set=Unreleased
  235. ```
  236. A bare `weave-set` makes every container in the file a set; a value is a
  237. comma-separated list of container names: the variable a literal is assigned
  238. to, the key it is the value of, the function it is an argument of
  239. (`parametrize`), the function whose body or match arms it is, the INI key of
  240. a multi-line value, the YAML/JSON/TOML key of an array, the title of a
  241. changelog section or of a heading above it (brackets off, or its first word:
  242. `## [Unreleased]` is `Unreleased`, `## 1.2.0 - 2026-01-01` is `1.2.0`). The driver reads the
  243. attribute with `git check-attr` only when such a container is what stands
  244. between a conflict and a union. Every union is still checked: an entry
  245. edited, deleted or moved beside the insertion, one key with two values, or
  246. an answer that does not parse stays a conflict.
  247. ## Jujutsu (jj)
  248. Add to your jj config (`jj config edit --user`):
  249. ```toml
  250. [merge-tools.weave]
  251. program = "weave-driver"
  252. merge-args = ["$base", "$left", "$right", "-o", "$output", "-l", "$marker_length", "-p", "$path"]
  253. merge-conflict-exit-codes = [1]
  254. merge-tool-edits-conflict-markers = true
  255. conflict-marker-style = "git"
  256. ```
  257. Resolve conflicts with `jj resolve --tool weave`, or set as default:
  258. ```bash
  259. jj config set --user ui.merge-editor "weave"
  260. ```
  261. ## Preview
  262. Dry-run a merge to see what weave would do:
  263. ```bash
  264. weave preview feature-branch
  265. ```
  266. ```
  267. src/utils.ts — auto-resolved
  268. unchanged: 2, added-ours: 1, added-theirs: 1
  269. src/api.ts — 1 conflict(s)
  270. ✗ function `process`: both modified
  271. ✓ Merge would be clean (1 file(s) auto-resolved by weave)
  272. ```
  273. After a real conflict, `weave explain <file>` and `weave check` are the
  274. next two commands; see [Quickstart](#quickstart).
  275. ## Landing an agent's merge: `weave land`
  276. Resolve a merge in progress, check its result, and stage accepted files:
  277. ```bash
  278. weave land
  279. weave land --resolver '<resolver-command>' --certificate land.json
  280. ```
  281. 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.
  282. | Result | Meaning |
  283. |---|---|
  284. | **PROVEN** | The result satisfies the supported structural proof rules. |
  285. | **VERIFIED** | The result passed the merge gate, without a structural proof. |
  286. | **REFUSED** | The result was not accepted; resolve the reported findings. |
  287. 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.
  288. ### Integrate and publish
  289. `--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.
  290. ```bash
  291. weave land --onto origin/main --verify-cmd 'go build ./... && go test ./...'
  292. # Or use Sem's project checkers:
  293. weave land --onto origin/main --check sem
  294. ```
  295. **Configure validation before publishing.** A failed gate or configured validation refuses publication. Without `--onto`, `weave land` does not publish.
  296. 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.
  297. ## CLI Commands
  298. Seven commands. Each `--help` line says which question the command answers, and every flag has an example (`weave <command> --help`).
  299. | Command | The question it answers |
  300. |---|---|
  301. | `weave setup [--global] [--local] [--off]` | Make `git merge` use weave here (`--global`: every repo; `--off`: stop) |
  302. | `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 |
  303. | `weave explain <file> [--summary] [--json]` | Why did this file conflict? `--summary`: a structured summary of the weave markers in any file |
  304. | `weave check [--json]` | Is my conflict resolution right? Lost lines, duplicates, leftover markers, dangling names |
  305. | `weave preview <branch> [--file <path>]` | What would merging this branch look like? Nothing is written |
  306. | `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 |
  307. | `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)) |
  308. 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.
  309. | Old | New |
  310. |---|---|
  311. | `weave unsetup` | `weave setup --off` |
  312. | `weave summary <file>` | `weave explain <file> --summary` |
  313. | `weave bench` | `weave stats --bench` |
  314. | `weave bench-repo <path>` | `weave stats --repo <path>` |
  315. | `weave claim`, `release`, `status`, `apply` | `weave experimental claim`, `release`, `status`, `apply` |
  316. 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`.
  317. ## MCP Server
  318. For agent frameworks that speak [MCP](https://modelcontextprotocol.io):
  319. ```bash
  320. # Claude Code
  321. claude mcp add --scope user weave -- weave-mcp
  322. # Any MCP client, via stdio (~/.config/claude/claude_desktop_config.json etc.)
  323. { "mcpServers": { "weave": { "command": "weave-mcp" } } }
  324. ```
  325. The server discovers the repo from each tool call's absolute file path, else the
  326. `WEAVE_REPO` env var, or its working directory. It lists six tools, one per
  327. `weave` command (each tool's own description states when to call it and what an
  328. empty result means):
  329. - `weave_preview`: dry-run a merge of two branches, as per-file verdicts, a
  330. findings document, or the strategy weave used on each entity.
  331. - `weave_edit`: change code by entity, written straight to disk: replace an entity, edit
  332. text inside it, add one before or after it, delete it, or create a file. A batch is all or
  333. nothing, and an edit that breaks the parse or quietly renames an entity is refused.
  334. - `weave_explain`: why a file conflicted, from the merge's three stages.
  335. - `weave_check`: is the resolution right, plus the cross-file breakage a per-file
  336. merge driver can't see (a rename in `a.py` whose surviving caller lives in `b.py`).
  337. - `weave_land`: label every file of a stopped merge PROVEN, VERIFIED or REFUSED, and
  338. write the ones that pass.
  339. - `weave_patch`: carry an edit to a file that drifted, as a three-way entity merge.
  340. For callers, dependencies and blast radius, use [sem](https://github.com/Ataraxy-Labs/sem)'s
  341. MCP server. The live multi-agent CRDT tools (`weave_claim_entity`,
  342. `weave_update_entity_content`, ...) are listed only with `WEAVE_EXPERIMENTAL=1`. Every
  343. older tool name still answers when called, so existing clients keep working.
  344. ## Architecture
  345. ```
  346. weave-core # Library: entity extraction, entity-level 3-way merge, reconstruction
  347. weave-driver # Git merge driver binary (called by git via %O %A %B %L %P)
  348. weave-cli # CLI: `weave setup`, `weave explain`, `weave check`, `weave patch`, ...
  349. weave-crdt # Automerge-backed CRDT: live multi-agent coordination state only
  350. weave-mcp # MCP server exposing weave to agent frameworks (one tool per command)
  351. weave-github # GitHub webhook service behind the hosted PR-comment integration
  352. # (publish = false, not a binary you install; runs weave's merge
  353. # analysis on pull_request events and posts the result as a comment)
  354. ```
  355. Uses [sem-core](https://github.com/Ataraxy-Labs/sem) for entity extraction via tree-sitter grammars.
  356. The merge algorithm (`weave-core`) and the coordination state (`weave-crdt`) are
  357. deliberately separate concerns with different data models: the merge is a pure
  358. function over three file revisions, run fresh on every `git merge`/`weave preview`/
  359. `weave check` call. The CRDT is the thing that persists; it's what lets two live
  360. agents see each other's claims and in-flight edits *before* either one commits,
  361. via `weave_claim_entity`/`weave_update_entity_content` or `weave experimental claim`/`weave experimental apply`.
  362. Nothing in the merge path depends on the CRDT ever having run.
  363. ## How It Works
  364. ```
  365. base
  366. / \
  367. ours theirs
  368. \ /
  369. weave merge
  370. ```
  371. 1. **Parse** all three versions into semantic entities via tree-sitter
  372. 2. **Extract regions**, alternating entity and interstitial (imports, whitespace) segments
  373. 3. **Match entities** across versions by ID (file:type:name:parent), detecting renames
  374. 4. **Resolve** each entity: one-side-only changes win, both-changed attempts intra-entity 3-way merge
  375. 5. **Reconstruct** file from merged regions, preserving ours-side ordering
  376. 6. **Fallback** to line-level merge for files >1MB, binary files, or unsupported types
  377. ## Limitations
  378. - **Vue, Svelte, ERB, Haskell** parse, but their per-file entity model is too coarse to merge
  379. well, so they take Git's line merge, always (see [Supported Languages](#supported-languages)).
  380. - **Files over 1MB, binary files, and file types with no parser** fall back to Git's line-level
  381. merge automatically.
  382. - **Entity claims are advisory, not enforced.** `weave_claim_entity` and `weave experimental claim` are
  383. cooperative locks inside the CRDT coordination layer; weave does not stop a second agent
  384. (or you) from editing a claimed entity anyway.
  385. - **Crashed agents aren't reaped.** `weave_agent_heartbeat`'s liveness timestamp is informational;
  386. weave does not currently expire or release a claim automatically when an agent stops
  387. heartbeating, so a crashed agent's claims stay visible until another call to
  388. `weave_release_entity`/`weave experimental release`.
  389. - **`weave stats` is empty until you opt in.** Lifetime merge counters are off by default; set
  390. `WEAVE_STATS=1` in the environment your git/jj merges run in to start accumulating them.
  391. ## Contributing
  392. Bug reports and issues are welcome. This is a small team maintaining a merge engine that
  393. runs inside other people's git workflows: incoming PRs get read, but are reviewed and
  394. adapted before merge rather than merged as-is. Open an issue first for anything beyond a
  395. small, obviously-correct fix, so the approach can be agreed on before you write the code.
  396. ## License
  397. Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option.
  398. ## Star History
  399. [![Star History Chart](https://api.star-history.com/svg?repos=Ataraxy-Labs/weave&type=Date)](https://star-history.com/#Ataraxy-Labs/weave&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.