Weavatrix JS

CI npm MIT

Part of the Weavatrix ecosystem. This repository preserves the explicit JavaScript engine line.

This is the JavaScript engine of Weavatrix, continued as weavatrix-js. The weavatrix npm package ships the native Rust engine from weavatrix-rust starting with 1.0.0; pin weavatrix@0.3.14 or install weavatrix-js to stay on the JavaScript implementation (including its LSP-assisted TypeScript path).

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/Weavatrix/weavatrix-js
• npm: weavatrix-js — npx -y weavatrix-js <repoRoot>

Primary native Rust engine

weavatrix-rust is the pure-Rust read-only MCP and library implementation. Its default build exposes 39 tools, covers the 34 read-only capabilities of this JavaScript line and adds cross-repository Git, vector search, semantic/SEO linking, and temporal-memory context through independent MIT crates.

cargo install weavatrix-rust
weavatrix mcp <repoRoot> --profile=code

The Rust engine does not invoke git, rg, Node.js, Python, a language server, or code from the analyzed repository. Use --profile=all, code, or seo to expose one bounded view without running duplicate MCP servers. Same-revision benchmarks and limitations are published in its benchmark report.

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.

Install

Requires Node ≥ 18.

# Claude Code
claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot>

# Codex CLI
codex mcp add weavatrix-js -- npx -y weavatrix-js <repoRoot>

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

Or run from a clone:

git clone https://github.com/Weavatrix/weavatrix-js
cd weavatrix-js && npm install
claude mcp add -s user weavatrix-js -- node <path-to>/weavatrix-js/bin/weavatrix-mcp.mjs <repoRoot>

<repoRoot> 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/<repository-storage-key>/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 — install it as ~/.claude/skills/weavatrix-js/SKILL.md (Claude Code) or ~/.codex/skills/weavatrix-js/SKILL.md (Codex).

Configure

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

# hard-pin one repository and expose no cross-repo tools:
claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot> 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, typosquats and 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). Results are compact and paginated by default (page_size, opaque cursor, and bounded per_item_limit samples); response_detail="full" is an explicit opt-in and remains paginated.

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. Outside a Git working tree there is no probe to read, so freshness cannot be proven and the debounce window alone bounds the work: one rebuild per window rather than one per call. 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):

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 and 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:

Dependency vulnerability matching, advisory refresh and installed-package malware review are not part of this package. Those networked/security-review workflows live in weavatrix-online, so the local JS engine does not advertise a security verdict it cannot establish.

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/ — start with the newest entry there. The release process and gates are in scripts/verify-release.mjs.

License

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