weave

The weave repository is organized as a Cargo workspace with several specialized packages:

• weave-core: The core merge engine, responsible for entity matching and the inner merge logic.
• weave-crdt: The CRDT (Conflict-free Replicated Data Type) coordination layer.
• weave-driver: The Git merge driver binary that is invoked directly by Git.
• weave-cli: The command-line interface providing weave setup, weave bench, and weave preview.
• weave-mcp: An MCP (Model Context Protocol) server providing 15 tools for agent coordination.
• weave-github: Integration for GitHub workflows.

When a real semantic conflict occurs, Weave provides enriched context in the conflict markers, identifying exactly which entity is causing the collision and why. This is more descriptive than standard Git line-based markers.

Example Conflict Marker:

<<<<<<< ours — function `process` (both modified)
export function process(data: any) {
    return JSON.stringify(data);
}
=======
export function process(data: any) {
    return data.toUpperCase();
}
>>>>>>> theirs — function `process` (both modified)

In this example, the marker explicitly states that the entity process is a function and that it was both modified.

Unlike standard Git which performs line-based merges, weave is an entity-level semantic merge driver. It resolves conflicts at the function or class level.

The merge lifecycle:

1. Extraction: sem-core extracts entities from the base, ours, and theirs versions of a file.
2. Matching: Entities are matched by name across the different versions.
3. Classification: Each entity is categorized as unchanged, added, deleted, or modified.
4. Inner Merge: For modified entities, an inner merge is performed by chunking the content by indentation and matching by name.
5. Conflict Resolution: Conflict markers are only produced when a true semantic conflict occurs, significantly reducing noise compared to line-based merging.

You can install Weave using Homebrew or by building it from source using Rust/Cargo.

Using Homebrew:

brew install weave

Building from source: Requires Rust and Cargo. Clone the repository and install the CLI and driver components.

git clone https://github.com/Ataraxy-Labs/weave
cd weave
cargo install --path crates/weave-cli
cargo install --path crates/weave-driver

You can install the weave CLI using Homebrew via the Ataraxy Labs tap.

brew install ataraxy-labs/tap/weave

To use Weave for semantic merging in your Git repositories, use the weave setup command. This configures Git to use Weave for all supported file types. Once set up, you can use git merge as normal.

Standard Setup (per repository): Configures .gitattributes in the current repository.

weave setup

Local Setup (per user, per repository): Configures .git/info/attributes so the settings are only applied to your local machine and not committed to the repo.

weave setup --local

Global Setup (every repository): Configures your global ~/.gitconfig and global attributes file. This makes Weave the default driver for all your repos without needing per-repo setup. Ensure weave-driver is in your PATH.

weave setup --global

Revert Setup: To stop using Weave and return to standard Git line-based merging:

weave unsetup

To build all binaries in the workspace and run the test suite, use cargo from the repository root.

cargo build --release                # all binaries
cargo test --workspace               # 124 tests

To use Weave as a merge tool in Jujutsu, add the following configuration to your jj config (e.g., via jj config edit --user):

[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"

You can then resolve conflicts using jj resolve --tool weave, or set it as your default merge editor with:

jj config set --user ui.merge-editor "weave"

The weave-mcp server provides a suite of Model Context Protocol (MCP) tools designed for agentic software development. These tools allow AI agents to perform semantic analysis, manage entity-level locks (claims) to prevent conflicts, coordinate with other agents, and perform advanced merge analysis.

Key capabilities include:

• Semantic Extraction: List functions, classes, and other entities within files.
• Agent Coordination: Register agents, send heartbeats, and claim specific entities to signal active work.
• Dependency & Impact Analysis: Query what an entity depends on or what might be affected by a change.
• Conflict Management: Detect potential merge conflicts and summarize structured conflict markers.
• Semantic Diffing: Compare changes between git refs at the entity level rather than the line level.

To prevent multiple agents from editing the same code simultaneously, use the claim/release pattern:

1. weave_claim_entity: Signals that an agent is working on a specific entity. It returns predictive warnings if the entity's dependencies or dependents are already claimed by other agents.
2. weave_release_entity: Releases the advisory lock on the entity once the work is complete.

This mechanism uses an advisory lock system to coordinate work across different agents.

The weave-driver executable is compatible with Jujutsu (jj) as a merge tool. Unlike the Git driver mode, jj typically uses explicit flags for output and marker length.

Jujutsu invocation pattern: weave-driver $base $left $right -o $output [-l $marker_length] [-p $path]

• $base: Ancestor (base) file path
• $left: Current (ours) file path
• $right: Other (theirs) file path
• -o $output: Path to write the merged result
• -l $marker_length: Explicitly set the marker length to use standard Git-compatible markers
• -p $path: The file path being merged