weavatrix-js

# Weavatrix JS

> This is the JavaScript engine of Weavatrix, continued as `weavatrix-js`.
> The [`weavatrix`](https://www.npmjs.com/package/weavatrix) npm package ships
> the native Rust engine from
> [weavatrix-rust](https://github.com/sergii-ziborov/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](https://weavatrix.com)
- Source: [github.com/sergii-ziborov/weavatrix-js](https://github.com/sergii-ziborov/weavatrix-js)
- npm: [`weavatrix-js`](https://www.npmjs.com/package/weavatrix-js) — `npx -y weavatrix-js <repoRoot>`

## Primary native Rust engine

[`weavatrix-rust`](https://github.com/sergii-ziborov/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.

```sh
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](https://github.com/sergii-ziborov/weavatrix-rust/blob/main/docs/benchmarks.md).

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`](https://github.com/sergii-ziborov/weavatrix-refactor) (Apache-2.0) to apply
hash-verified, reversible edits, or [`weavatrix-online`](https://github.com/sergii-ziborov/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.

```sh
# 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>
```

```toml
# 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:

```sh
git clone https://github.com/sergii-ziborov/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](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`):

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

```sh
# 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.
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 match