Weavatrix

Weavatrix

Local repository intelligence for AI coding agents — understand an application fast, then change it with evidence.

Weavatrix builds a reusable living graph of any local repository — files, symbols, imports, calls, inheritance, Health findings, clone families and Git-history coupling — and gives Claude Code, Codex or any MCP client a bounded map for fast understanding and low repeated context. The same graph then answers change impact, Health, dead-code review, duplicates, history and intended-architecture questions. 34 network-free tools. No repository data leaves your machine.

• Website: weavatrix.com
• Source: github.com/sergii-ziborov/weavatrix
• npm: weavatrix — npx -y weavatrix

This package is the complete offline engine under the MIT license: it reads and analyzes your code, initiates no outbound HTTP, and never edits your source. It is the read-only base of a layered stack — add weavatrix-refactor (Apache-2.0) to apply hash-verified, reversible edits, or weavatrix-online for authorized Cloud or self-hosted sync. Each is an optional superset that depends on this core through a supported extension API; the offline/online split is documented in [docs/adr/0001-v0.3-offline-online-split.md](docs/adr/0001-v0.3-offline-online-split.md).

Install

Requires Node ≥ 18.

# Claude Code
claude mcp add -s user weavatrix -- npx -y weavatrix 

# Codex CLI
codex mcp add weavatrix -- npx -y weavatrix 

# or in ~/.codex/config.toml
[mcp_servers.weavatrix]
command = "npx"
args = ["-y", "weavatrix", "C:/path/to/repo"]
startup_timeout_sec = 20
tool_timeout_sec = 60

Or run from a clone:

git clone https://github.com/sergii-ziborov/weavatrix
cd weavatrix && npm install
claude mcp add -s user weavatrix -- node /weavatrix/bin/weavatrix-mcp.mjs 

` is the repository to start with. Graphs are derived data and never live in your repo: they are stored in the per-user registry at ~/.weavatrix/graphs//graph.json (with a stable .repository-id beside them). No graph yet? Ask the agent to call rebuild_graph`, or just use a tool — graph and Health reads auto-reconcile the working graph before answering.

An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install it as ~/.claude/skills/weavatrix/SKILL.md (Claude Code) or ~/.codex/skills/weavatrix/SKILL.md (Codex).

Configure

Security profile — pass a profile as the final positional argument (omitted = offline):

| Profile | Local repository switching | Cross-repo graph reads | Network requests | Tools | |---|---:|---:|---:|---:| | offline (default) | Yes, only via open_repo | Yes, only via trace_api_contract | None | 34 | | pinned | No | No | None | 31 |

# hard-pin one repository and expose no cross-repo tools:
claude mcp add -s user weavatrix -- npx -y weavatrix  pinned

Advanced registrations may pass an exact comma-separated capability set instead: graph,search,source,health,build,retarget,crossrepo. A custom list must include crossrepo to expose trace_api_contract. Legacy online/osv/hosted/full names fail loudly and point to weavatrix-online.

Semantic precision — a bounded, read-only TypeScript/JavaScript language-server overlay is on by default for new graphs and upgrades confirmed references to EXACT_LSP. Turn it off for parser-only operation with WEAVATRIX_PRECISION=off (env), precision:"off" on rebuild_graph/open_repo, or the MCPB installer's precision choice. Java and Rust have no bundled language server; their edges stay parser-derived.

The startup prewarm queries 32 ranked symbols (never more than 64) by default. For a deliberate high-budget pass, set WEAVATRIX_PRECISION_MAX_SYMBOLS above 64 or WEAVATRIX_PRECISION_PREWARM=full to cover every eligible target up to a 10,000-symbol ceiling; WEAVATRIX_PRECISION_MAX_REFERENCES, WEAVATRIX_PRECISION_MAX_LINKS and WEAVATRIX_PRECISION_TIMEOUT_MS tune the budgets. Repositories that exceed a hard ceiling stay honestly PARTIAL.

Repository config files (all optional, repository-root):

• .weavatrixignore — analysis-only exclusions that should stay tracked in Git (*, **, ?,

root-anchored /patterns, directory suffixes, ordered ! re-includes).

• .weavatrix.json — cross-repository HTTP client/wrapper contracts (httpContracts) and

classify.product overrides.

• .weavatrix-deps.json — entrypoints, nonRuntimeRoots, and Python managedDependencies /

ignoreDependencies for conventions that cannot be inferred safely.

Test execution — verified_change is read-only by default. Running an existing package test/check/verify script requires both run_tests:true and WEAVATRIX_ALLOW_TEST_RUNS=1; arbitrary commands are always rejected.

After an upgrade, reconnect the MCP server or start a new agent task before checking the tool list — many clients snapshot tools/list for the lifetime of a connection. graph_stats reports the running version, enabled capabilities and registered-tool count so a cached process is distinguishable from the installed package.

Tools

The 34 methods project the same reusable graph into the smallest view a task needs.

• graph — graph_stats, get_node, get_neighbors, query_graph, god_nodes, shortest_path,

get_community, list_communities, module_map, get_dependents, change_impact, verified_change, git_history, graph_diff, get_architecture_contract, prepare_change. Runtime, TypeScript type-only and language compile-only edges are reported separately; every edge carries versioned provenance (EXTRACTED / RESOLVED / INFERRED, upgraded to EXACT_LSP only by the bundled TS/JS overlay, CONFLICT when evidence disagrees).

• search / source — search_code (ripgrep-backed with a pure-Node fallback and

repository-relative path globs), read_source, context_bundle, inspect_symbol, list_endpoints (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum & actix-web/Spring), trace_endpoint.

• health — find_dead_code, run_audit (capability matrix + unused files/exports/dependencies,

missing/duplicate deps, offline OSV vulnerabilities, typosquats, lockfile drift; base_ref + debt: new|existing|all for review-scoped results), find_duplicates (MOSS winnowing, catches renamed clones), coverage_map, hot_path_review, verify_architecture, explain_architecture_violation, propose_architecture_exception.

• build — rebuild_graph (reports the structural delta, keeps the prior state as graph.prev.json).
• retarget (in offline, absent from pinned) — open_repo, list_known_repos.
• crossrepo (in offline, absent from pinned) — trace_api_contract (joins routes to client

call-sites across registered local graphs; reads no source).

Every finding is review evidence, never an auto-delete verdict: find_dead_code / run_audit category=unused always return REVIEW_REQUIRED with autoDelete:false. Typecheck, tests and runtime checks remain the release authority.

Always-fresh graph

There is no watcher daemon to run and no manual refresh step: every graph/health call reconciles the graph before answering. A Git-token freshness probe (HEAD + dirty/untracked content, debounced 2 s) decides whether anything changed; when it did, a bounded incremental refresh reparses only the changed files plus their reverse importers (≤ 24 changed / ≤ 80 reparsed JS/TS files) and merges the scoped result into the previous graph under a file lock. Config/lockfile edits, export-surface changes, barrel files and non-JS/TS languages fall back to a full rebuild — correctness always wins over speed. Each refreshed answer carries a structured refresh record (none / incremental / full, changed file count), so an agent can tell exactly which repository state it is reasoning about. The same guarantees hold across concurrent MCP clients sharing one canonical graph.

Benchmarks

Two gates ship in the repository:

• npm run benchmark — a reproducible golden suite for TypeScript, JavaScript, Python, Go, Java and

Rust, plus cross-repository HTTP matching, framework conventions and the MCP graph lifecycle.

• npm run benchmark:real — compares revision-pinned local snapshots against the checked-in 0.2.1

relation baseline; it fails on unexplained signal loss (MISSING/STALE/UNBASELINED stay incomplete, not green).

Representative local regression run (Windows x64, Node 24.15.0):

| Gate | Result | Selected evidence | |---|---:|---| | Six language fixtures | 6/6 PASS | exact symbols/edges and complete edge provenance | | Cross-repo fixture | PASS, ~432 ms cold | endpoint match, typed wrapper, external use | | Lifecycle | PASS | full → incremental → none → reconnect/none | | Total fixture cold build | ~1.31 s | all six language graphs | | Real-repository baseline | 6/6 PASS | TS, JS, Python, Go, Java and Rust snapshots |

Real snapshots ranged from 473 nodes / 1,165 edges in 0.22 s (Go) to 8,192 nodes / 21,814 edges in 9.44 s (TypeScript). These are regression measurements on one machine, not competitor benchmarks. See [benchmark/cases.mjs](benchmark/cases.mjs) and [docs/benchmarking.md](docs/benchmarking.md).

Security model

Socket capability alerts describe the expected powers of a local code-analysis tool; they are not vulnerability findings. Where each comes from and how it is bounded:

| Capability alert | Why it exists | Activation and boundary | |---|---|---| | Network access | None in the MIT core | offline/pinned expose only local tools; online integration is a separate package | | Shell access | Local git (staleness/impact), rg (search), the bundled tsserver for JS/TS semantics, Windows child-tree termination, optional verified_change test scripts | The semantic provider never runs repository code; test execution needs run_tests:true + WEAVATRIX_ALLOW_TEST_RUNS=1 and rejects arbitrary commands | | Debug / dynamic loading | Cache-busted import() hot-reloads watched MCP tool modules; createRequire loads package metadata and parser deps | Loads files from the installed package only; no eval | | Environment access | Reads local WEAVATRIX_* settings; children inherit a credential-stripped env | Connector secrets are removed; tsserver receives only allowlisted OS/temp/locale values | | Filesystem access | Reads the active repository, graph, lockfiles and coverage; writes derived graphs and caches | Realpath containment blocks traversal and symlink escapes; pinned removes open_repo | | URL strings | Advisory findings may contain fixed OSV documentation links | The core has no outbound request implementation |

read_source accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or realpath escapes. Report suspected vulnerabilities privately as described in [SECURITY.md](SECURITY.md).

Languages

JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · Solidity · HTML · CSS — parsed with web-tree-sitter WASM grammars; no Python install and no native compilation.

SQL is indexed without a grammar: .sql files contribute tables, views, columns, functions, indexes and triggers as first-class graph symbols, and SQL found in string literals of any other language links the enclosing function to the table it queries. That makes schema objects visible to change_impact/get_dependents (who touches this table?) and lets the dead-code check flag columns no statement references — conservatively: verdicts require literal-SQL evidence in the repo, and SELECT *-consumed tables never have their columns judged by name (ORM-generated SQL stays invisible and is therefore never judged either).

Test surfaces are classified per file (path conventions plus .weavatrix.json overrides) and, for Rust, per symbol: #[cfg(test)] modules and #[test]/#[bench] items inside production .rs files carry a node-level test_surface flag, so dead-code, query, hot-path and hub tools treat them as tests rather than production code.

Development

npm install
npm test                 # unit/integration tests plus the quick golden benchmark
npm run benchmark        # full TS/JS/Python/Go/Java/Rust + MCP lifecycle gate
npm run benchmark:real   # locally available real repos vs source-free 0.2.1 baselines

Maintained JavaScript/TypeScript under src, bin, scripts, test has a hard 300-line physical ceiling enforced by the release suite; larger concerns split into owner-focused modules behind slim facades. The weavatrix.com landing site lives in its own repository (weavatrix-site).

Release history

Per-version patch notes live in [docs/releases/](docs/releases/) — start with the newest entry there. The release process and gates are in [scripts/verify-release.mjs](scripts/verify-release.mjs).

License

The Weavatrix source in this repository is [MIT licensed](LICENSE) © 2026 Sergii Ziborov. Third-party dependencies retain their own licenses. See the public license page for the same notice.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sergii-ziborov
• Source: sergii-ziborov/weavatrix
• License: MIT
• Homepage: https://weavatrix.com

Install and usage instructions live in the source repository linked above.