Weavatrix Git

docs.rs

Part of the Weavatrix ecosystem: bounded Git evidence for AI software agents.

weavatrix-git gives AI coding agents fast, bounded, read-only Git evidence. The Rust crate, CLI, MCP server, and npm package are the same contract: parse repository storage directly. No git subprocess, C library, hooks, filters, network access, checkout, or mutation. There is no write API in any surface.

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.3 --repository /absolute/path/to/repository

Generic stdio client configuration:

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

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.3 --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

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:

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:

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

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

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