Weavatrix Git

weavatrix-git gives AI coding agents fast, bounded, read-only Git evidence. Install it from npm as a native MCP server or embed its dependency-free Rust core. Both paths parse repository storage directly: no git subprocess, C library, hooks, filters, network access, checkout, or mutation.

On the checked-in exact-parity benchmark, 1,000 warm history entries took 0.355 ms with Weavatrix, 0.884 ms with gix, and 1.552 ms with libgit2. Across eight repositories, Weavatrix won all five measured p50 contracts. These are engine measurements from release builds; the MCP transport is deliberately not hidden inside the claim.

Run the MCP server

No Rust toolchain is required:

npx -y [email protected] --repository /absolute/path/to/repository

Generic stdio client configuration:

{
  "mcpServers": {
    "weavatrix-git": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "--repository",
        "/absolute/path/to/repository"
      ]
    }
  }
}

The npm package contains verified native binaries for Windows x64, Linux x64 and ARM64, and macOS x64 and ARM64. Node only selects and launches the matching binary; repository parsing and MCP handling stay in safe Rust.

Tools for agents

| MCP tool | Evidence returned | | --- | --- | | git_head | repository identity, hash kind, symbolic HEAD, exact target ID, pack count | | git_history | paginated commit IDs, trees, parents, signatures, timestamps, summaries | | git_diff | paginated added/deleted/modified/type-changed paths with old/new object IDs | | git_status | tracked index and worktree state; untracked files are intentionally excluded | | git_snapshot | canonical immutable path, mode, kind, and object-ID manifest for a revision |

Every list tool returns nextCursor, exact object IDs, and a truncated flag. Non-UTF-8 paths retain their exact bytes in pathHex; display text is never silently presented as exact evidence.

Runtime limits

The MCP binary uses mcport's controlled, Tokio-free runtime:

• 256 KiB maximum request and 1 MiB maximum response;
• four in-flight handlers and bounded request/output queues;
• 30-second handler deadline with cooperative cancellation checks;
• panic isolation and atomic response-overflow errors;
• bounded Git object, history, tree, bitmap, reflog, and index reads;
• optional progress notifications and configurable response batching.

Defaults are suitable for interactive stdio. --help exposes overrides for byte budgets, concurrency, queues, deadline, and batch size. The server writes only newline-delimited UTF-8 JSON-RPC to stdout; diagnostics go to stderr.

Native Cargo installation is also available:

cargo install weavatrix-git --version 0.3.1 --features mcp \
  --bin weavatrix-git-mcp
weavatrix-git-mcp --repository /absolute/path/to/repository

Why a separate crate?

A scanner discovers files. A code graph models relationships. This crate owns version-control evidence. Keeping that boundary independent lets any Rust application reuse Git intelligence without importing a larger product.

Supported contract

| Area | Support | | --- | --- | | Layouts | worktree, bare, .git indirection, linked worktree commondir | | Hashes | SHA-1 and SHA-256 object identifiers | | Refs | loose, symbolic, detached HEAD, packed refs, reflogs | | Objects | commit, tree, blob, annotated tag | | Loose storage | bounded zlib/DEFLATE decoded by this crate | | Packed storage | PACK v2/v3, index v2, OFS_DELTA, REF_DELTA | | Object lookup | alternates, classic MIDX, caches, shared zero-copy snapshots | | Commit acceleration | monolithic and split commit-graph chains | | Path acceleration | changed-path Bloom filters v1/v2 | | Reachability | pack and MIDX EWAH bitmaps with RIDX ordering | | Index | DIRC v2/v3/v4, auto-refreshing shared snapshots | | Queries | typed reads, lazy revwalk, history, tracked status, tree diff | | Immutable views | canonical commit snapshots with path, mode, and object evidence | | Scale-out | parallel open, revision-aware timelines, change sets, correlation | | Extension | ordered, thread-safe, read-only custom ODB backends |

All public reads are in-process. Library code contains no subprocess fallback. Unsupported data returns a typed error rather than an approximate answer.

Rust library

use weavatrix_git::{PathBloom, Repository};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repository = Repository::open(".")?;
    let head = repository.resolve("HEAD")?;

    for id in repository.revwalk().push_head()?.take(100) {
        println!("{}", id?);
    }

    if repository.commit_maybe_changed_path(head, b"src/lib.rs")?
        == Some(PathBloom::DefinitelyNot)
    {
        println!("the commit definitely did not change src/lib.rs");
    }

    if let Some(objects) = repository.bitmap_reachable(head)? {
        println!("{} reachable objects", objects.len());
    }
    Ok(())
}

Custom stores use the same object contract:

use std::sync::Arc;
use weavatrix_git::{Limits, MemoryObjectBackend, Repository};

let backend = Arc::new(MemoryObjectBackend::default());
let repository =
    Repository::open_with_backends(".", Limits::default(), vec![backend])?;
# Ok::<_, weavatrix_git::GitError>(repository)

For cross-repository analysis, RepositorySet keeps object stores isolated and returns deterministic serial or parallel results:

use weavatrix_git::{HistoryOptions, RepositorySet};

let repositories = RepositorySet::open_parallel([
    ("service", "/code/service"),
    ("client", "/code/client"),
])?;
let histories =
    repositories.histories_from_parallel("HEAD", HistoryOptions::default())?;
let snapshots = repositories.snapshots_parallel("HEAD")?;
let timeline = repositories.timeline("HEAD", HistoryOptions::default())?;
let shared = repositories.shared_commits(HistoryOptions::default())?;
# Ok::<_, weavatrix_git::GitError>((histories, snapshots, timeline, shared))

The diagnostic CLI uses the library:

weavatrix-git [-C repository] head
weavatrix-git [-C repository] log [revision] [max-count]
weavatrix-git [-C repository] cat <object>
weavatrix-git [-C repository] diff <old-commit> <new-commit>

Architecture

Repository
  +-- refs + reflog
  +-- commit-graph chain + changed-path Bloom
  +-- index -> tracked status
  +-- custom ODB backends
  +-- object directories + alternates
        +-- loose object -> bounded zlib
        +-- MIDX -> pack -> bounded delta chain
        +-- pack/MIDX bitmap -> reachable object IDs

Limits bounds object bytes, cache bytes, delta/ref/tree depth, tree and index entries, reflog/history length, parent count, and bitmap expansion. The crate forbids unsafe Rust. The default library feature set remains dependency-free; only the separate mcp feature adds mcport.

The source tree follows explicit modular boundaries:

| Layer | Responsibility | | --- | --- | | model | object IDs, typed Git objects, errors, and validation contracts | | storage | loose/pack/MIDX/commit-graph decoding, bounded inflate and caches | | repository | refs, history, diffs, status, snapshots, trees, and revwalks | | workspace | deterministic multi-repository queries and correlation | | mcp | optional read-only protocol adapter over the library | | facade / CLI | stable Rust exports and diagnostic command entry points |

The checked-in strict architecture contract rejects files over 300 physical lines, functions over 100 physical lines, runtime cycles, mixed foo.rs plus foo/ module ownership, and any dependency from the protocol-independent library into the optional MCP adapter. It has no baseline or exceptions.

Correctness

The suite creates real Git repositories and verifies:

• loose and aggressively packed OFS/REF delta objects;
• SHA-1 and SHA-256 repositories;
• bare and linked-worktree layouts;
• classic MIDX lookup;
• multi-layer split commit-graphs and changed-path Bloom answers;
• pack and MIDX bitmap reachability against git rev-list --objects;
• index v2 and v4, reflog order, revwalk hide/reset, and tracked status;
• deterministic parallel and cross-repository results;
• immutable revision snapshots, merged timelines, and batch change sets;
• hostile format and configured-limit failures.

Current core line coverage is 85.27%. CI runs Rust 1.88 on Linux, Windows, and macOS, Clippy with warnings denied, coverage, audit, docs, and package verification.

Performance

Release measurements on Windows, 2026-07-27. Every row materializes the result and proves exact identifier, path, object-byte, or status parity before timing:

| Exact-parity operation | weavatrix-git p50 | git.exe p50 | | --- | ---: | ---: | | 6,000-object bitmap reachability | 0.431 ms | 72.656 ms | | one-entry index read | 0.033 ms | 60.758 ms | | clean tracked status | 0.186 ms | 72.735 ms | | cached commit lookup | 0.001 ms | 65.267 ms | | 1,000-commit history, reused repository | 0.086 ms | 66.961 ms |

Direct in-process comparison on the same packed 2,000-commit fixture:

| Exact-parity operation | Weavatrix p50 | gix 0.86 p50 | git2 0.21 p50 | | --- | ---: | ---: | ---: | | 1,000-commit history, warm | 0.355 ms | 0.884 ms | 1.552 ms | | 1,000-commit history, reopen | 2.521 ms | 3.940 ms | 10.483 ms | | 1,000 cached object reads | 0.082 ms | 0.068 ms | 5.640 ms | | history plus 1,000 raw objects | 0.494 ms | 0.992 ms | 1.375 ms |

On a separate 10,000-path index, warm reads measured 1.160/1.100/1.489 ms respectively; reopen measured 5.225/7.745/11.251 ms. The benchmark rotates engine order and proves exact history IDs, raw object bytes, and canonical index paths before timing. See BENCHMARKS.md.

On eight independent repositories with 8,000 selected commits, Weavatrix measured 5.667 ms serial history, 4.080 ms parallel history, 11.810 ms reopen, 4.148 ms shared-commit correlation, and 1.736 ms immutable manifests. It won all five p50 contracts against gix and libgit2; exact per-repository history order, shared locations, paths, and object IDs were proven first.

Position among alternatives

| Capability | weavatrix-git | Git CLI | gix | libgit2 | | --- | --- | --- | --- | --- | | In-process | yes | no | yes | yes | | Pure safe Rust | yes | no | yes | no, C core | | Crate dependencies | zero | n/a | many modular crates | native library | | Object/delta caches | yes | yes | yes | yes | | MIDX and reachability bitmap reads | yes | yes | yes | yes | | Split commit-graph and path Bloom reads | yes | yes | yes | commit-graph | | Custom read-only ODB | yes | n/a | store abstractions | yes | | Lazy revwalk, reflog, index, tracked status | yes | yes | yes | yes | | First-class cross-repository evidence queries | yes | application code | application code | application code | | Canonical immutable commit manifest | yes | application code | traversal API | tree walk API | | Network and mutation | no | yes | yes | yes |

The deliberate remaining exclusions are pack index v1, reftable, incremental MIDX chains, split/sparse index extensions, shallow and replace-object semantics, revision-expression grammar, untracked/ignore/filter-aware status, submodule worktree status, network operations, and mutation.

Use Git, gix, or libgit2 for a complete client. Use this crate when bounded local evidence, a small audit surface, deterministic reads, and zero dependencies matter.

License

MIT