weavatrix-git

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 weavatrix-git@0.3.1 --repository /absolute/path/to/repository

Generic stdio client configuration:

{
  "mcpServers": {
    "weavatrix-git": {
      "command": "npx",
      "args": [
        "-y",
        "weavatrix-git@0.3.1",
        "--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