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](https://weavatrix.com)
- Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
- npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix <repoRoot>`

This package is the complete offline engine under the MIT license and initiates no outbound HTTP.
Every network capability lives in the separately versioned `weavatrix-online` superset, which depends
on this core through a supported extension API. The 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 -- npx -y weavatrix <repoRoot>

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

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

```sh
git clone https://github.com/sergii-ziborov/weavatrix
cd weavatrix && npm install
claude mcp add -s user weavatrix -- node <path-to>/weavatrix/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/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 |

```sh
# hard-pin one repository and expose no cross-repo tools:
claude mcp add -s user weavatrix -- npx -y weavatrix <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, 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 comman