vectora

The completeness guardrail for AI coding agents — catches the files you forgot and the calls you broke, before you ship them.

Works with Claude Code, Cursor, Windsurf, Codex, Kiro, OpenCode, and Gemini CLI. Commit it once; every agent on the repo gets the map.

The one failure mode every AI agent has

AI agents are locally brilliant and globally forgetful. They make a correct local edit and miss the second call site, the coupled file, the stale test. That's the bug that ships broken. That's the mistake that makes you distrust the agent.

vectora is the safety net. At the end of every task it asks: did you touch all the files this edit required? It knows three things the agent structurally cannot compute from source text alone:

1. Git co-change history — files repeatedly edited together in real commits. Lives only in git log, invisible to grep and embeddings.
2. Symbol consumers — which files import and use a specific exported symbol you just changed.
3. Confirmed arity breaks — call sites that provably pass the wrong number of arguments to a function whose signature you just changed.

No skeletonization, nothing hidden, no invented "tokens saved" math. vectora hands over the map and gets out of the way.

The loop

You:    /vectora add a required userId param to parseConfig

vectora map  →  [VECTORA MAP]
                CO-CHANGE (edited together in git — grep can't see this):
                  config/parser.ts + config/validator.ts   8× together
                  config/parser.ts + auth/session.ts       4× together
                START HERE (open by your own judgment):
                  config/parser.ts    [142 lines · in:6]   (filename match)
                NEIGHBORHOOD (graph-connected — may be relevant):
                  config/index.ts     [in:4]   imports parser.ts
                  billing/charge.ts   [in:1]   imports parser.ts

Agent edits config/parser.ts — adds userId to parseConfig(env, userId, opts)

vectora check →  [VECTORA CHECK]
                you edited: config/parser.ts

                ✗ BROKEN — fix before finishing:
                ✗ billing/charge.ts calls parseConfig() with 2 args but it now requires 3 — fix this call.
                ✗ auth/session.ts calls parseConfig() with 2 args but it now requires 3 — fix this call.

                ⚠ config/validator.ts co-changes with config/parser.ts (git 8×) but was not edited — worth a look?

Two things happened there that no amount of grepping or context-window size could replicate: vectora proved that two call sites are now broken (confirmed arity mismatch, from the live AST), and it surfaced a co-change partner from git history that the agent would never have known to check. Both would have shipped broken.

Setup — one command, then one command in your agent

npx vectora@latest        # detects your agent(s), installs the skill

Then, once, inside your agent:

/vectora init

init is fully offline, deterministic, and costs zero tokens — it shells out to Node, parses your code's AST, builds the import graph, and reads your git history for co-change pairs. No LLM call, no network, no telemetry. It writes .vectora/graph.json.

Commit .vectora/graph.json to git. Everyone who clones the repo gets the map on day one, in whatever agent they use.

After that, just describe tasks with /vectora <task> and the agent maps → navigates → checks automatically.

Why this is honest (and the last version wasn't)

vectora 1.x claimed to save tokens by "skeletonizing" files. It was measured on a real task and it cost ~3× more tokens while burying the actual edit targets. The token-savings number was invented. 2.0 deletes all of that.

The only numbers vectora reports are ones it can prove on your repo: the co-change/caller links it surfaced that your edits used or missed, and arity mismatches it confirmed from the live AST. You don't have to trust a benchmark — vectora check verifies it live, against your own code.

• No "tokens saved" claim anywhere. The metric is incomplete edits flagged, per-task, per-repo.
• vectora receipts for the honest lifetime count. Every entry in .vectora/ledger.json is a real, inspectable event. Wording is always "flagged" — we can't claim you acted on it.
• Nothing hidden from the agent. No skeletons, no "don't open this."
• No hardcoded rule tables. No package→domain dictionaries. Just the graph and the git history.
• Zero-token, offline init. No LLM in the indexing path.

Commands

Inside your agent:

From the shell (the agent runs these for you; you rarely need them directly):

npx vectora init             # build the graph (offline)
npx vectora map "<task>"     # print the structural map for a task
npx vectora check            # the receipt, against your current git diff
npx vectora why <file>       # centrality, importers, co-change peers
npx vectora status           # graph staleness
npx vectora doctor           # health check + config validation

Institutional memory (optional)

vectora can carry architectural rules that the map surfaces when relevant. Create .vectora/decisions.json:

{
  "global": ["Use dayjs, never moment.js."],
  "domains": { "auth": ["JWT expiry is 15 minutes for compliance."] }
}

This is always user-in-the-loop — the agent proposes a rule and asks before writing it. /vectora learn "<rule>" and /vectora unlearn "<rule>" manage it explicitly.

Danger zone annotations

Co-locate critical constraints with the code they guard so AI agents see them exactly when relevant:

// @vectora danger: changing this signature requires a DB migration — see ADR-42
// @vectora danger: called by mobile app v2.x with 2-week deploy lag — no breaking changes

# @vectora danger: JWT secret rotation required if auth flow changes here

Works in any language. At map time, if a seed or co-change partner carries a danger annotation, vectora surfaces it first:

⚠ DANGER ZONES — constraints on files in your edit scope:
  auth/session.ts: "called by mobile app v2.x with 2-week deploy lag — no breaking changes"
  config/parser.ts: "changing this signature requires a DB migration — see ADR-42"

Language support

TypeScript path aliases (@/components/Button, webpack/Vite alias) aren't resolved yet — those edges are dropped. Run npx vectora why <file> to see which edges were captured. Co-change history doesn't depend on aliases and always works.

Configuration

Optional vectora.config.js in your project root:

module.exports = {
  pivotThreshold:      0.15,  // top N% by centrality flagged as pivots
  coChangeMaxFiles:    15,    // ignore commits touching more than N files (kills "format everything" noise)
  refreshAfterHours:   24,    // auto-diff if the graph is older than N hours
  refreshAfterChanges: 10,    // auto-diff after N changed files
  forcePivots:         [],    // paths always treated as pivots
  exclude:             [],    // globs to skip, e.g. ['**/*.generated.ts']
  domains:             null,  // explicit domain map: { 'src/billing/**': 'payments' }
};

The coChangeMaxFiles filter is what makes the receipt trustworthy: a giant "reformat the whole repo" commit would otherwise link every file to every other file. vectora drops commits that touch more than 15 source files so the co-change signal stays meaningful.

Privacy

vectora runs entirely offline. It reads your source and git history locally, builds the graph, and writes .vectora/graph.json. Nothing leaves your machine — no telemetry, no analytics, no API calls, no LLM in the indexing path.