What it is
A measurement instrument for your code
NorthGraph runs on the developer's machine. It parses source with compiler, parser, and Tree-sitter adapters, then builds a deterministic local index of covered symbols, routes, static effects, and analyzer limitations. Coding agents read from it before they propose a change. Reviewers read from it before they approve one. CI reads from it before it merges one. Same input, same output. Not probabilistic.
Example scoring a diff
- input
A diff
Uncommitted changes, a feature branch, or a pull request base. Resolved locally with the TypeScript compiler API, Python AST, or tree-sitter, whichever your repo speaks.
- classify
14 effect classes
Changed call sites covered by the configured analyzers are mapped to effects: DB writes, secrets, auth, payments, network, queues, more. Each carries the detector that found it and coverage warnings when analysis degrades.
- output
A verdict
Clean, warnings, or violations: each with the rule that fired, the missing test, the policy context, and analyzer limitations. Returned as JSON, stored as a PR-ready report, and usable as a CI gate.
Four surfaces one index
What you actually do with NorthGraph
North Ask Ask the codebase a question in plain English
For investigation, code review prep, and onboarding. Returns ranked candidates with the file and symbol that backs each one. Never an answer with no source.
# question$ vectorgraph north ask \ "where is workspace authorization enforced?"{ "answers": [ { "symbol": "requireWorkspaceRole", "file": "src/server/auth.ts:42", "confidence": "high" }, { "symbol": "assertWorkspaceMember", ... } ]}North Plan Scope a task before any code is written
For sprint commitment and agent pre-flight. The graph compiles a task brief: files to read, symbols to touch, routes and jobs at risk, tests to run, evidence still missing.
# compile a brief$ vectorgraph north plan --issue ENG-2189{ "files_to_read": 4, "symbols_to_touch": ["archiveIssue", "BulkPanel"], "routes_at_risk": ["POST /api/v1/issues/archive"], "tests_to_run": 18, "missing_evidence": ["coverage on bulk path"]}North Review Prepare a diff before a human opens the PR
For CI gates and agent self-review. Returns a verdict, the effects the change introduced, the policy results, and the tests that should have run. Straight from the local index, not a replacement for human review.
# score a diff$ vectorgraph north diff analyze --base main --json{ "verdict": "clean", "risk": "medium", "effects": ["db_write", "metrics_write"], "tests_impacted": 41, "policy_violations": 0}North Context Hand supported MCP clients local repo context
For Claude Code, Codex, Cursor, Windsurf, or your in-house agent. The local stdio MCP server returns repo plans, effects, tests, evidence summaries, and citations. Issue context loads through `/cli/v1` only when workspace credentials are configured.
# start local MCP for a supported client$ vectorgraph north mcplistening · stdio · tools registered# agent calls a toolagent → create_plan({ issueIdentifier: "ENG-2189" })server → { issueContext, files, effects, tests, missingEvidence }# issue context is fetched through scoped /cli/v1 credentials
Run on VectorGraph own source
Numbers from a real production monorepo
Every figure below came from running vectorgraph north index and vectorgraph north effects against the codebase that powers this product. Run the same commands on yours and the JSON looks the same.
- 783files indexedFirst index on a developer laptop completes in about six seconds.
- 10,085symbols mappedEvery function, type, and constant gets a stable ID so impact traces survive renames, moves, and refactors.
- 14effect classesThe supported taxonomy: DB, auth, secrets, network, file, queue, cache, payment, telemetry, and runtime configuration.
- 28tests impactedBy one example diff, surfaced before the test job even starts running.
Snapshot from 2026-05-17. Your numbers will reflect your repo's current state.
Language support
Deterministic where the analyzer has coverage and explicit where it does not
NorthGraph does not claim universal whole-program correctness. Every report carries analyzer mode, warnings, missing evidence, and degraded coverage when a file falls back from compiler or parser facts to text heuristics.
Uses the TypeScript compiler API for symbols, imports, local call targets, route detection, effects, and impacted tests.
Uses the Python stdlib AST when python3 is available, with explicit fallback warnings when it is not.
Uses the javac Compiler Tree API when Java and javac are available, with explicit degraded-mode warnings otherwise.
Uses Tree-sitter WASM adapters for symbols, imports, calls, and static effects where the grammar exposes them.
Indexes migrations, package/config files, and policy inputs for effects and verification context.
Indexed with text heuristics today. NorthGraph reports degraded coverage instead of pretending compiler-grade analysis.
Common vocabulary
One name for the same call in every surface
Your coding agent's pre-flight, your PR-ready report, and your CI gate all read from the same fourteen-class taxonomy. When one says payment_operation, the others say the exact same word, because they're reading from the same parsed graph. Disagreements stop being about vocabulary.
- Agent pre-flight
{ "effect": "payment_operation", "site": "src/checkout/charge.ts:42"} - PR-ready report
# NorthGraphTouches payment_operationat src/checkout/charge.ts:42Gated on @engineering review. - CI gate
# vectorgraph north policy checkpolicy.deny[payment_operation]exit 1
In your workflow
What changes when NorthGraph runs in your repo
Diffs get scoped for agents, reviewers, and CI
Verdict, risk grade, effects added, impacted tests, and limitations are produced locally as structured JSON. Agents, reviewers, and CI can consume the same report, with humans still owning approval.
How review works →Coding agents work from the same graph your reviewers do
The local stdio MCP returns file, symbol, effect, citation, and analyzer-mode metadata when available. Works with supported MCP clients including Claude Code, Cursor, Codex, Windsurf, or your in-house client.
Set up MCP →Onboarding answers come from the source
New hires ask the codebase a question in plain English. North Ask returns ranked local candidates with the file, symbol, line, and confidence instead of an unsupported final answer.
How North Ask works →Lands in your CI in one YAML block
GitHub Actions or any shell. `vectorgraph north diff analyze --base origin/main --json` exits non-zero on policy violation. No SDK, no API client, no version-skew.
CI setup →
What you control
Your binary your policy your audit
- The binary is signed and auditable. Ship it on your release cadence or pin a version in CI.
- The policy file lives in your repo. Reviewed in pull requests,
git blame-able, versioned with the code it governs. - The audit log is yours. Export it as JSON; retention is governed by your workspace settings, not ours.
- The MCP server runs over local stdio. No inbound network port, no third-party telemetry, no source uploaded.
Get started
Bring your team onto the shared work graph
Create an account, name a workspace, invite your team, connect your code, and point your agents at MCP. Start turning company context into shipped work from one shared workspace.