Documentation

Architecture, merge algorithm, CRDT state, MCP tools, and CLI reference.

How It Works Architecture CRDT State MCP Server CLI Commands

How the merge driver works

When git encounters a merge, it calls weave-driver with three versions of the file: base, ours, theirs. Here's what happens inside.

Parse all three versions

tree-sitter extracts entities (functions, classes, methods) from base, ours, and theirs. Each entity gets a stable ID based on its type, name, and parent.

Extract regions

The file is split into alternating Entity and Interstitial regions. Interstitials are the whitespace, imports, and syntax between entities.

Match entities across versions

For each entity in base: did ours change it? Did theirs? Both? Neither? This is where weave understands that two agents editing different functions is not a conflict.

Resolve per-entity

Only ours changed? Use ours. Only theirs? Use theirs. Both changed identically? Use either. Both changed differently? Try 3-way merge via diffy. If that fails on a container (class/impl/trait), try inner entity merge: decompose into method-level chunks, match by name, merge each independently. Renames are detected via structural_hash (AST-normalized). Conflicts are classified using the ConGra taxonomy (Text/Syntax/Functional).

Reconstruct the file

Reassemble the merged file preserving ours-side ordering, with theirs-only additions placed at the correct positions. Write to the ours path per git convention.

Architecture

Five crates in a Cargo workspace. Each can be used independently.

weave-core

The merge algorithm. Takes three strings (base, ours, theirs) + file path, returns merged content + conflict list. Uses sem-core for entity extraction and diffy for line-level fallback.

↓

weave-driver

Git merge driver binary. Git calls it with %O %A %B %L %P. Reads three temp files, calls entity_merge(), writes result to %A. Exit 0 = clean, 1 = conflicts.

↓

weave-crdt

Automerge-backed entity state. Advisory claims, agent tracking, conflict detection. Persisted at .weave/state.automerge. Not committed to git — local coordination state.

↓

weave-mcp

MCP server with 15 tools. stdio transport for Claude Desktop/CLI integration. Wraps weave-crdt and weave-core into callable agent tools.

↓

weave-cli

Human-facing CLI. weave setup, weave preview, weave status, weave claim, weave release.

CRDT state

CRDT stands for Conflict-free Replicated Data Type — a data structure that multiple agents can edit simultaneously without conflicts. Think of it like a Google Doc that always merges correctly.

Why does weave need it?

The merge driver is reactive — it resolves conflicts after they happen. But if two agents are about to edit the same function, you want to know before they collide. The CRDT gives agents a shared "who's editing what" map. Agent A claims processData, Agent B sees the claim and picks a different function instead.

Advisory, not enforced

Claims are signals, not hard locks. If an agent ignores a claim and edits anyway, the merge still works — weave's merge driver handles it. This matches the optimistic concurrency model: trust agents to cooperate, handle it gracefully if they don't.

Document structure

The state is an Automerge document saved to .weave/state.automerge. It has three top-level maps:

{
  "entities": {                       // every code entity weave knows about
    "src/lib.ts::function::processData": {
      "name": "processData",
      "type": "function",
      "file_path": "src/lib.ts",
      "content_hash": "a1b2c3...",
      "claimed_by": "agent-1",          // advisory lock
      "claimed_at": 1706745600000,
      "last_modified_by": "agent-1",
      "version": 3
    }
  },
  "agents": {                         // registered agents
    "agent-1": {
      "name": "agent-1",
      "status": "active",
      "branch": "feature-auth",
      "last_seen": 1706745600000,
      "working_on": ["src/lib.ts::function::processData"]
    }
  },
  "operations": [...]               // audit log of claim/release/modify
}

Agent coordination flow

Agent registers

Calls weave_agent_register with its ID and branch. Gets added to the agents map.

Agent claims an entity

Calls weave_claim_entity. Gets back Claimed, AlreadyOwnedBySelf, or AlreadyClaimed { by }.

Agent edits the code

Periodically calls weave_agent_heartbeat with its working_on list. Other agents can check weave_who_is_editing before starting work.

Agent releases the claim

Calls weave_release_entity when done. If an agent crashes, cleanup_stale_agents releases its claims after a timeout.

Core operations

Operation	What it does
`claim_entity`	Set advisory lock on an entity for an agent
`release_entity`	Remove the lock (only the owner can release)
`record_modification`	Mark that an agent changed an entity, bump version
`detect_potential_conflicts`	Find entities being worked on by multiple agents
`register_agent`	Add an agent to the state with name and branch
`agent_heartbeat`	Keep-alive + update working_on list
`cleanup_stale_agents`	Release claims from agents that stopped heartbeating
`sync_from_files`	Extract entities from working tree files into CRDT state

MCP server

MCP (Model Context Protocol) lets AI agents call tools. weave-mcp exposes 15 tools over stdio transport. Add it to Claude Code, Claude Desktop, or any MCP-compatible client.

Setup

install

$ cargo install --git https://github.com/Ataraxy-Labs/weave weave-mcp

Claude Code (CLI)

# Add to Claude Code (available in all projects)
$ claude mcp add --scope user weave -- weave-mcp

# Restart Claude Code, then verify with /mcp

Claude Desktop

# Add to ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "weave": {
      "command": "weave-mcp",
      "args": []
    }
  }
}

Tools

weave_extract_entities

List all entities in a file — names, types, line ranges. Input: {file_path}

weave_claim_entity

Claim an entity before editing. Advisory lock. Input: {agent_id, file_path, entity_name}

weave_release_entity

Release claim after done editing. Input: {agent_id, file_path, entity_name}

weave_status

Entity list with claim and modification status. Input: {file_path}

weave_who_is_editing

Check if anyone is editing a specific entity. Input: {file_path, entity_name}

weave_potential_conflicts

Entities being edited by multiple agents. Input: {agent_id?}

weave_preview_merge

Dry-run merge analysis between branches. Input: {base_branch, target_branch, file_path?}

weave_agent_register

weave_agent_heartbeat

Keep-alive + update working state. Input: {agent_id, working_on}

weave_validate_merge

Detect semantic risks in a merge — entities that reference each other and were both modified. Input: {base_branch, target_branch, file_path?}

weave_get_dependencies

What does this entity call or reference? Uses cross-file dependency graph. Input: {file_path, entity_name}

weave_get_dependents

Who calls or references this entity? Reverse dependency lookup. Input: {file_path, entity_name}

weave_impact_analysis

Transitive blast radius if an entity changes. BFS through dependency graph. Input: {file_path, entity_name}

weave_diff

Entity-level semantic diff between two refs. Shows added, modified, deleted, renamed entities. Input: {base_ref, target_ref?, file_path?}

weave_merge_summary

Parse weave conflict markers into structured JSON. Entity names, conflict types, confidence, resolution hints. Input: {file_path}

Example: agent workflow

agent calls via MCP

// Agent starts up
weave_agent_register({ agent_id: "claude-1", branch: "feature-auth" })

// Check what's in the file
weave_extract_entities({ file_path: "src/auth.ts" })
// → [{name: "validateToken", type: "function", ...},
//     {name: "authenticate", type: "function", ...}]

// Claim before editing
weave_claim_entity({ agent_id: "claude-1", file_path: "src/auth.ts", entity_name: "validateToken" })
// → "Claimed"

// ... agent edits the function ...

// Release when done
weave_release_entity({ agent_id: "claude-1", file_path: "src/auth.ts", entity_name: "validateToken" })
// → "Released successfully"

CLI commands

The weave CLI wraps all functionality for human use.

weave setup Configure current git repo to use weave as merge driver

--driver <path> Path to weave-driver binary (auto-detected if omitted)

weave preview <branch> Preview what a merge would look like without actually merging

--file <path> Preview a specific file only

weave status Show entity and agent state from CRDT

--file <path> Show entities for a specific file

--agent <id> Show status for a specific agent

weave claim <agent> <file> <entity> Claim an entity before editing

weave release <agent> <file> <entity> Release a previously claimed entity

weave bench Run merge benchmarks comparing weave vs git line-level merge