vectora

vectora proves your AI agent's edit is complete before you ship it.

It does two things no amount of context window can replicate:

1. Confirmed arity breaks — ✗ billing.js calls parseConfig() with 2 args but it now requires 3. Proven from the live AST. Not a guess.
2. Git co-change history — files edited together across real commits. config/parser.ts and config/validator.ts changed together 8 times. grep cannot see this. The agent cannot infer it.

Works with Claude Code, Cursor, Windsurf, Codex, Kiro, OpenCode, and Gemini CLI.

In 30 seconds

You:    /vectora add a required userId param to parseConfig

vectora map:
  context: 247 files indexed · 8 in task scope (6 seeds + 2 neighbors)

  CO-CHANGE (git history — grep can't see this):
    config/parser.ts + config/validator.ts   8× together
    config/parser.ts + auth/session.ts       4× together

  START HERE:
    config/parser.ts    [142 lines · in:6]   (filename match)

Agent edits config/parser.ts — adds `userId` as required param.

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

  ⚠ config/validator.ts co-changes with config/parser.ts (8×) but wasn't edited.

The agent was about to ship two broken call sites and miss a coupling partner. vectora caught all three — from the AST and git log, not guesses.

What it gives you

• ✗ BROKEN arity proofs — live AST re-parsed at check time. If a call site passes the wrong number of args, vectora proves it and names the file. Every ✗ must be fixed before declaring the task done.
• Git co-change history — files real engineers edited together in real commits. The "did you forget a partner file?" signal that lives only in git log.
• Symbol consumers — which files import and reference a specific symbol you changed. When you change RetryError, vectora knows the five files that use it.
• Context line — every map tells you: context: 247 files indexed · 8 in task scope. You see exactly how much of the codebase is covered and how many files are relevant to this task.
• Session coupling — files you edit together, tracked across sessions. On a repo with no git history, this stands in for co-change from day one.

None of this requires an LLM call. It's AST parsing + git log, fully offline.

Setup

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

Then, once, inside your agent:

/vectora init

init is fully offline, zero tokens — it parses your AST, builds the import graph, reads git history, writes .vectora/graph.json. No LLM, no network, no telemetry.

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

TypeScript / monorepo

Path aliases (@/, ~/, #lib/) and monorepo workspace cross-package imports resolve automatically. The init output confirms: aliases: 12 path aliases · 4 workspace pkgs. If aliases don't resolve, set tsConfigPath: 'tsconfig.app.json' in vectora.config.js.

The loop: map → navigate → check

/vectora <task> runs the full loop automatically:

/vectora prompt <task> is the guaranteed-trigger form — use it when you want vectora to run unconditionally, even for short or follow-up prompts. Same 6-step loop, no activation heuristics.

The receipt (vectora check)

After every edit, check reports four things — signals 2–4 need no git history:

✗ BROKEN — fix before finishing:
✗ billing/charge.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× · sessions 2×) but wasn't edited.

⚠ retry.ts imports errors.ts (uses RetryError) but wasn't edited — verify?

⚠ charge.ts changed but charge.test.ts wasn't — update the test?

• ✗ BROKEN = proven arity mismatch from the live AST. Fix every one before declaring done.
• ⚠ = probable miss. Investigate each. If it genuinely needs the change, make it.

check works even if you skipped map — it computes misses directly from the graph.

Commands

Core guardrails — run these on every coding task:

Exploration — understand the codebase:

Institutional memory — rules that persist across sessions:

Why this is honest

vectora 1.x claimed to save tokens by "skeletonizing" files. Measured on a real task (sindresorhus/got), it cost ~3× more tokens and buried the actual edit targets. The token-savings figure was invented.

2.0 deletes all of that. The only numbers vectora reports are ones it can prove on your repo:

• ✗ BROKEN — call count and current signature both re-parsed from disk at check time. It's the live AST. Either the numbers match or they don't.
• vectora receipts — lifetime count of incomplete edits flagged, stored in .vectora/ledger.json. Every entry is a real, inspectable event. Wording is always "flagged" — not "caught" or "saved."
• Nothing hidden from the agent. No skeletons, no "don't open this."
• Zero-token init. No LLM in the indexing path.

Danger zone annotations

Co-locate critical constraints with the code they guard so the agent sees 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 (JS/TS //, Python/Ruby #, Go/Rust //). 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"

Institutional memory

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."] }
}

Always user-in-the-loop — the agent proposes a rule and asks before writing it.

Auto-seeding on first init: When init runs for the first time, it emits a [VECTORA SEED] block. The agent then runs overview + why on the top pivot files, optionally runs migrate to pull rules from your CLAUDE.md or README, and proposes 3–7 architectural rules for you to approve.

Background capture: After tasks that establish a new coupling invariant or architectural pattern, the agent asks: "I noticed: <rule>. Add it to vectora's memory?" On approval: npx vectora learn "<rule>". Never written silently.

Language support

TypeScript path aliases (@/*, ~/, #lib/), jsconfig.json baseUrl, and monorepo workspace cross-package imports are all resolved — no configuration needed.

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 ("format everything" noise filter)
  refreshAfterHours:   24,    // auto-diff if graph is older than N hours
  refreshAfterChanges: 10,    // auto-diff after N changed files
  tsConfigPath:        null,  // point to a non-standard tsconfig, e.g. 'tsconfig.app.json'
  forcePivots:         [],    // paths always treated as pivots
  exclude:             [],    // globs to skip, e.g. ['**/*.generated.ts']
  domains:             null,  // explicit domain map: { 'src/billing/**': 'payments' }
};

coChangeMaxFiles is the noise filter that makes co-change trustworthy: a "reformat the whole repo" commit would otherwise link every file to every other. vectora drops commits touching more than 15 source files.

Privacy

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