# Weavatrix Git
[](https://github.com/sergii-ziborov/weavatrix-git/actions/workflows/ci.yml)
[](https://crates.io/crates/weavatrix-git)
[](https://www.npmjs.com/package/weavatrix-git)
[](https://docs.rs/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:
```bash
npx -y weavatrix-git@0.3.1 --repository /absolute/path/to/repository
```
Generic stdio client configuration:
```json
{
"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
| `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`](https://crates.io/crates/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:
```bash
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
| 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
```rust
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:
```rust
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:
```rust
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:
```text
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
```text
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:
| `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:
| 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:
| 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](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
| 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