{
  "markdown": "# Weavatrix Git\n\n[![CI](https://github.com/Weavatrix/weavatrix-git/actions/workflows/ci.yml/badge.svg)](https://github.com/Weavatrix/weavatrix-git/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/weavatrix-git.svg)](https://crates.io/crates/weavatrix-git)\n[![npm](https://img.shields.io/npm/v/weavatrix-git.svg)](https://www.npmjs.com/package/weavatrix-git)\n[![docs.rs](https://docs.rs/weavatrix-git/badge.svg)](https://docs.rs/weavatrix-git)\n[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nPart of the [Weavatrix ecosystem](https://weavatrix.com/ecosystem): bounded Git evidence for AI software agents.\n\n`weavatrix-git` gives AI coding agents fast, bounded, **read-only** Git evidence.\nThe **Rust crate, CLI, MCP server, and npm package** are the same contract:\nparse repository storage directly. No `git` subprocess, C library, hooks,\nfilters, network access, checkout, or mutation. There is no write API in any\nsurface.\n\nOn the checked-in exact-parity benchmark, 1,000 warm history entries took\n**0.355 ms** with Weavatrix, **0.884 ms** with `gix`, and **1.552 ms** with\n`libgit2`. Across eight repositories, Weavatrix won all five measured p50\ncontracts. These are engine measurements from release builds; the MCP\ntransport is deliberately not hidden inside the claim.\n\n## Run the MCP server\n\nNo Rust toolchain is required:\n\n```bash\nnpx -y weavatrix-git@0.3.3 --repository /absolute/path/to/repository\n```\n\nGeneric stdio client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"weavatrix-git\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"weavatrix-git@0.3.3\",\n        \"--repository\",\n        \"/absolute/path/to/repository\"\n      ]\n    }\n  }\n}\n```\n\nThe npm package contains verified native binaries for Windows x64, Linux x64\nand ARM64, and macOS x64 and ARM64. Node only selects and launches the matching\nbinary; repository parsing and MCP handling stay in safe Rust.\n\n### Tools for agents\n\n| MCP tool | Evidence returned |\n| --- | --- |\n| `git_head` | repository identity, hash kind, symbolic HEAD, exact target ID, pack count |\n| `git_history` | paginated commit IDs, trees, parents, signatures, timestamps, summaries |\n| `git_diff` | paginated added/deleted/modified/type-changed paths with old/new object IDs |\n| `git_status` | tracked index and worktree state; untracked files stay on `Repository::worktree_safety()` |\n| `git_snapshot` | canonical immutable path, mode, kind, and object-ID manifest for a revision |\n| `git_worktree_safety` | Clean / IgnoredOnly / HasUntracked / DirtyTracked / Unknown; untracked and ignored counts |\n\nEvery list tool returns `nextCursor`, exact object IDs, and a `truncated` flag.\nNon-UTF-8 paths retain their exact bytes in `pathHex`; display text is never\nsilently presented as exact evidence.\n\n### Runtime limits\n\nThe MCP binary uses [`mcport`](https://crates.io/crates/mcport)'s controlled,\nTokio-free runtime:\n\n- 256 KiB maximum request and 1 MiB maximum response;\n- four in-flight handlers and bounded request/output queues;\n- 30-second handler deadline with cooperative cancellation checks;\n- panic isolation and atomic response-overflow errors;\n- bounded Git object, history, tree, bitmap, reflog, and index reads;\n- optional progress notifications and configurable response batching.\n\nDefaults are suitable for interactive stdio. `--help` exposes overrides for\nbyte budgets, concurrency, queues, deadline, and batch size. The server writes\nonly newline-delimited UTF-8 JSON-RPC to stdout; diagnostics go to stderr.\n\nNative Cargo installation is also available:\n\n```bash\ncargo install weavatrix-git --version 0.3.3 --features mcp \\\n  --bin weavatrix-git-mcp\nweavatrix-git-mcp --repository /absolute/path/to/repository\n```\n\n## Why a separate crate?\n\nA scanner discovers files. A code graph models relationships. This crate owns\nversion-control evidence. Keeping that boundary independent lets any Rust\napplication reuse Git intelligence without importing a larger product.\n\n## Supported contract\n\n| Area | Support |\n| --- | --- |\n| Layouts | worktree, bare, `.git` indirection, linked worktree `commondir` |\n| Hashes | SHA-1 and SHA-256 object identifiers |\n| Refs | loose, symbolic, detached HEAD, packed refs, reflogs |\n| Objects | commit, tree, blob, annotated tag |\n| Loose storage | bounded zlib/DEFLATE decoded by this crate |\n| Packed storage | PACK v2/v3, index v2, OFS_DELTA, REF_DELTA |\n| Object lookup | alternates, classic MIDX, caches, shared zero-copy snapshots |\n| Commit acceleration | monolithic and split commit-graph chains |\n| Path acceleration | changed-path Bloom filters v1/v2 |\n| Reachability | pack and MIDX EWAH bitmaps with RIDX ordering |\n| Index | DIRC v2/v3/v4, auto-refreshing shared snapshots |\n| Queries | typed reads, lazy revwalk, history, tracked status, worktree safety, tree diff |\n| Immutable views | canonical commit snapshots with path, mode, and object evidence |\n| Scale-out | parallel open, revision-aware timelines, change sets, correlation |\n| Extension | ordered, thread-safe, read-only custom ODB backends |\n\nAll public reads are in-process. Library code contains no subprocess fallback.\nUnsupported data returns a typed error rather than an approximate answer.\n\n## Rust library\n\n```rust\nuse weavatrix_git::{PathBloom, Repository};\n\nfn main() -> Result<(), Box<dyn std::error::Error>> {\n    let repository = Repository::open(\".\")?;\n    let head = repository.resolve(\"HEAD\")?;\n\n    for id in repository.revwalk().push_head()?.take(100) {\n        println!(\"{}\", id?);\n    }\n\n    if repository.commit_maybe_changed_path(head, b\"src/lib.rs\")?\n        == Some(PathBloom::DefinitelyNot)\n    {\n        println!(\"the commit definitely did not change src/lib.rs\");\n    }\n\n    if let Some(objects) = repository.bitmap_reachable(head)? {\n        println!(\"{} reachable objects\", objects.len());\n    }\n    Ok(())\n}\n```\n\nCustom stores use the same object contract:\n\n```rust\nuse std::sync::Arc;\nuse weavatrix_git::{Limits, MemoryObjectBackend, Repository};\n\nlet backend = Arc::new(MemoryObjectBackend::default());\nlet repository =\n    Repository::open_with_backends(\".\", Limits::default(), vec![backend])?;\n# Ok::<_, weavatrix_git::GitError>(repository)\n```\n\nFor cross-repository analysis, `RepositorySet` keeps object stores isolated and\nreturns deterministic serial or parallel results:\n\n```rust\nuse weavatrix_git::{HistoryOptions, RepositorySet};\n\nlet repositories = RepositorySet::open_parallel([\n    (\"service\", \"/code/service\"),\n    (\"client\", \"/code/client\"),\n])?;\nlet histories =\n    repositories.histories_from_parallel(\"HEAD\", HistoryOptions::default())?;\nlet snapshots = repositories.snapshots_parallel(\"HEAD\")?;\nlet timeline = repositories.timeline(\"HEAD\", HistoryOptions::default())?;\nlet shared = repositories.shared_commits(HistoryOptions::default())?;\n# Ok::<_, weavatrix_git::GitError>((histories, snapshots, timeline, shared))\n```\n\nThe diagnostic CLI uses the library:\n\n```text\nweavatrix-git [-C repository] head\nweavatrix-git [-C repository] log [revision] [max-count]\nweavatrix-git [-C repository] cat <object>\nweavatrix-git [-C repository] diff <old-commit> <new-commit>\n```\n\n## Architecture\n\n```text\nRepository\n  +-- refs + reflog\n  +-- commit-graph chain + changed-path Bloom\n  +-- index -> tracked status\n  +-- custom ODB backends\n  +-- object directories + alternates\n        +-- loose object -> bounded zlib\n        +-- MIDX -> pack -> bounded delta chain\n        +-- pack/MIDX bitmap -> reachable object IDs\n```\n\n`Limits` bounds object bytes, cache bytes, delta/ref/tree depth, tree and index\nentries, reflog/history length, parent count, and bitmap expansion. The crate\nforbids unsafe Rust. The default library feature set remains dependency-free;\nonly the separate `mcp` feature adds `mcport`.\n\nThe source tree follows explicit modular boundaries:\n\n| Layer | Responsibility |\n| --- | --- |\n| `model` | object IDs, typed Git objects, errors, and validation contracts |\n| `storage` | loose/pack/MIDX/commit-graph decoding, bounded inflate and caches |\n| `repository` | refs, history, diffs, status, snapshots, trees, and revwalks |\n| `workspace` | deterministic multi-repository queries and correlation |\n| `mcp` | optional read-only protocol adapter over the library |\n| `facade / CLI` | stable Rust exports and diagnostic command entry points |\n\nThe checked-in strict architecture contract rejects files over 300 physical\nlines, functions over 100 physical lines, runtime cycles, mixed `foo.rs` plus\n`foo/` module ownership, and any dependency from the protocol-independent\nlibrary into the optional MCP adapter. It has no baseline or exceptions.\n\n## Correctness\n\nThe suite creates real Git repositories and verifies:\n\n- loose and aggressively packed OFS/REF delta objects;\n- SHA-1 and SHA-256 repositories;\n- bare and linked-worktree layouts;\n- classic MIDX lookup;\n- multi-layer split commit-graphs and changed-path Bloom answers;\n- pack and MIDX bitmap reachability against `git rev-list --objects`;\n- index v2 and v4, reflog order, revwalk hide/reset, and tracked status;\n- deterministic parallel and cross-repository results;\n- immutable revision snapshots, merged timelines, and batch change sets;\n- hostile format and configured-limit failures.\n\nCurrent core line coverage is 85.27%. CI runs Rust 1.88 on Linux, Windows, and macOS,\nClippy with warnings denied, coverage, audit, docs, and package verification.\n\n## Performance\n\nRelease measurements on Windows, 2026-07-27. Every row materializes the result\nand proves exact identifier, path, object-byte, or status parity before timing:\n\n| Exact-parity operation | `weavatrix-git` p50 | `git.exe` p50 |\n| --- | ---: | ---: |\n| 6,000-object bitmap reachability | 0.431 ms | 72.656 ms |\n| one-entry index read | 0.033 ms | 60.758 ms |\n| clean tracked status | 0.186 ms | 72.735 ms |\n| cached commit lookup | 0.001 ms | 65.267 ms |\n| 1,000-commit history, reused repository | 0.086 ms | 66.961 ms |\n\nDirect in-process comparison on the same packed 2,000-commit fixture:\n\n| Exact-parity operation | Weavatrix p50 | `gix` 0.86 p50 | `git2` 0.21 p50 |\n| --- | ---: | ---: | ---: |\n| 1,000-commit history, warm | 0.355 ms | 0.884 ms | 1.552 ms |\n| 1,000-commit history, reopen | 2.521 ms | 3.940 ms | 10.483 ms |\n| 1,000 cached object reads | 0.082 ms | 0.068 ms | 5.640 ms |\n| history plus 1,000 raw objects | 0.494 ms | 0.992 ms | 1.375 ms |\n\nOn a separate 10,000-path index, warm reads measured 1.160/1.100/1.489 ms\nrespectively; reopen measured 5.225/7.745/11.251 ms. The benchmark rotates\nengine order and proves exact history IDs, raw object bytes, and canonical\nindex paths before timing. See [BENCHMARKS.md](BENCHMARKS.md).\n\nOn eight independent repositories with 8,000 selected commits, Weavatrix\nmeasured 5.667 ms serial history, 4.080 ms parallel history, 11.810 ms reopen,\n4.148 ms shared-commit correlation, and 1.736 ms immutable manifests. It won\nall five p50 contracts against `gix` and `libgit2`; exact per-repository\nhistory order, shared locations, paths, and object IDs were proven first.\n\n## Position among alternatives\n\n| Capability | `weavatrix-git` | Git CLI | `gix` | `libgit2` |\n| --- | --- | --- | --- | --- |\n| In-process | yes | no | yes | yes |\n| Pure safe Rust | yes | no | yes | no, C core |\n| Crate dependencies | zero | n/a | many modular crates | native library |\n| Object/delta caches | yes | yes | yes | yes |\n| MIDX and reachability bitmap reads | yes | yes | yes | yes |\n| Split commit-graph and path Bloom reads | yes | yes | yes | commit-graph |\n| Custom read-only ODB | yes | n/a | store abstractions | yes |\n| Lazy revwalk, reflog, index, tracked status | yes | yes | yes | yes |\n| First-class cross-repository evidence queries | yes | application code | application code | application code |\n| Canonical immutable commit manifest | yes | application code | traversal API | tree walk API |\n| Network and mutation | no | yes | yes | yes |\n\nThe deliberate remaining exclusions are pack index v1, reftable, incremental\nMIDX chains, split/sparse index extensions, shallow and replace-object\nsemantics, revision-expression grammar, untracked/ignore/filter-aware status,\nsubmodule worktree status, network operations, and mutation.\n\nUse Git, `gix`, or `libgit2` for a complete client. Use this crate when bounded\nlocal evidence, a small audit surface, deterministic reads, and zero\ndependencies matter.\n\n## License\n\nMIT\n",
  "bytes": 12384,
  "sha": "b695c0ef33811646631f1b87b15f1e5ba04687a08d702269aa06849bf091d1da",
  "repo_slug": "sergii-ziborov/weavatrix-git",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sergii_ziborov_weavatrix_git_232f35a0/readme"
}