Weavatrix JS

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