Coregraph

CoreGraph

[](https://www.npmjs.com/package/@coregraph/cli) [](LICENSE)

One queryable code graph for multi-language and monorepo codebases — find callers, impact, dead code, and cross-file inconsistencies, with every relationship tagged by how much you can trust it.

CoreGraph is a Rust CLI (coregraph, v0.1.3, MIT). It indexes your source once, serves the graph from a background daemon, and answers questions over an IPC socket, an MCP bridge for LLM agents, an LSP bridge for editors, and an optional HTTP API. Because every answer comes from the precomputed graph instead of re-reading files, results are precise, fast to return, and small enough to hand straight to an LLM — a few hundred tokens where grepping and pasting files would cost thousands.

---

What is CoreGraph

CoreGraph builds an in-memory symbol graph of your codebase by combining two analysis layers into a single result:

• tree-sitter extracts symbols — functions, methods, structs, classes,

enums, config keys, doc comments — from each file.

• stack-graphs resolves names across files — so a call site in one file

links to the definition it actually binds to in another, not just to anything with the same name.

Both run inside one coregraph index pass — no language servers, build system, or compiler toolchain required.

Every edge in the graph carries a confidence score (0.0–1.0), the origin that produced it (e.g. resolved by stack-graphs vs. matched syntactically), and a trust model. That means a consumer — an LLM agent or a human — can tell a compiler-grade fact from a heuristic guess, and filter by --min-confidence when it matters.

---

Highlights

• Token-efficient — built for LLM agents. Every answer comes from the

precomputed graph, so CoreGraph returns the exact symbols and edges a question touches instead of whole files. --output-format llm emits compact, structured text; results are paged against a --token-budget (default 8000; --fast caps it at 2000, --full raises it to 16000) with a live budget: used/total counter; and --min-confidence filters low-trust noise before it ever reaches the model. A caller lookup that would otherwise mean pasting several files lands in a few hundred tokens.

• Fast, and stays fast. A single index pass builds the whole graph (~280

files in ~2.3s on this repo), then a background daemon serves every later query from memory over an IPC socket — no re-indexing per command. Idle projects are snapshotted to disk and warm-load on the next query (skipping tree-sitter extraction) unless a source file changed, so repeat queries are effectively instant and never stale.

• Many languages, one graph. Java, TypeScript, JavaScript, Python, Go, Rust,

and Kotlin each get both symbol extraction and cross-file name resolution, alongside config (YAML/TOML/JSON) and Markdown layers — all unified into one index you query identically regardless of language.

• Monorepo-native. One graph spans every package, service, and language in

the repo at once: a reference that crosses a directory or language boundary resolves to its real definition, so cross-package call paths and shared definitions are reachable in a single query rather than scattered across per-language indexes. The daemon caches multiple projects under an LRU with an optional heap budget, keeping a large polyglot repo responsive.

---

Why CoreGraph

| Tool | What it gives you | What it misses | |------|-------------------|----------------| | grep / ripgrep | Fast text matches | No symbols, no call edges, no cross-file resolution | | ctags | A symbol index | No callers/callees, no impact, single-pass only | | Single-language LSP | Rich nav in one language | One language at a time; nothing across a polyglot monorepo | | CoreGraph | A typed, cross-file, multi-language graph with confidence-tagged edges | — |

CoreGraph is built for codebases where the answer spans files and languages: a TypeScript route that maps to a Go handler, a Spring bean wired by config, an enum value duplicated across services. It answers "who calls this", "what breaks if I change this", "what is dead", and "where do these disagree" — across all of it at once.

---

Quick start

# Install the CLI from npm — puts `coregraph` on your PATH
npm install -g @coregraph/cli
# ...upgrade later to the latest:   npm install -g @coregraph/cli@latest
# ...or run it without installing:  npx @coregraph/cli@latest 
# ...or build from source:          cargo build --release  (binary in target/release/)
# Check the installed version:      coregraph --version

# Index the current project (creates .coregraph/config.toml on first run)
coregraph index --stats

> Updating: re-run npm install -g @coregraph/cli@latest to move to the newest > release; coregraph --version confirms the result and the npm version badge > shows the latest published version. A background daemon already running from an > older version keeps serving until restarted — run coregraph server restart to > load the new binary.

coregraph: skipped 1 minified/generated file(s) (e.g. ./vscode-extension/media/cytoscape.min.js)
Index complete — 281 files, 3396 symbols, 21342 edges (2337ms)

The first query auto-spawns a background daemon and reuses the cached graph for every subsequent command.

Find who calls a function

coregraph query compute_impact \
  --direction incoming --edge-kind calls --hop-limit 1

── query: compute_impact ──────────────────────────────────

✓ compute_impact [crates/query/src/impact.rs:27]
  kind: Function | package: query (cargo)

  Incoming (14):
  ├── calls ← run [Function] @ crates/cli/src/commands/diff.rs      [0.85] ✓
  ├── calls ← run [Function] @ crates/cli/src/commands/impact.rs      [0.85] ✓
  ├── calls ← cached_impact [Function] @ crates/cli/src/dispatch.rs      [0.85] ✓
  ├── calls ← api_impact [Function] @ crates/server/src/handlers.rs      [0.85] ✓
  └── ... (14 total)
  ✓ trust: all paths verified

── page 1/1 | 14 edges total | budget: 506/5600 tokens ──
   [n]ext page | [e]xpand  | [f]ilter --edge-kind | [q]uit

The [0.85] ✓ on each edge is its confidence score.

See the blast radius of a change

coregraph impact build_router --risk

Impact of 'build_router': 1251 reachable symbols, 1251 edges, depth 3
  Risk Score: 0.96 (Critical)
  Blast Radius: Critical (16 modules, 910 callers)
  Confidence-Weighted Impact: 653.500
  Affected tests: 334
    test_app (distance 2, path_confidence 0.90) — ./crates/server/src/handlers.rs
    create_app_returns_router (distance 2, path_confidence 0.90) — ./crates/server/src/lib.rs
    ... (more affected tests)

Find dead-code candidates

coregraph orphans --exclude-tests

Orphan symbols (12): 7 likely dead, 5 library API surface, 0 test code
  as_kebab [Method] — crates/cli/src/commands/query.rs
  strip_api_path_prefix [Function] — crates/extractor/src/string_literal_extractor.rs [library API]
  unregister [Method] — crates/graph/src/hooks.rs [library API]
  outputChannel [Constant] — vscode-extension/src/extension.ts
  ...

Symbols tagged [library API] are public surface — reachable from outside the crate, so flagged with lower confidence than truly unreferenced symbols.

Detect cross-file inconsistencies

coregraph inconsistencies

Inconsistencies (63):
  [enum-mismatch] 'admin' appears in:
    - Permission.ADMIN (./tests/e2e/golden/04-inconsistencies/src/permissions.ts)
    - Role.ADMIN (./tests/e2e/golden/04-inconsistencies/src/roles.ts)
  [api-path] /a.rs vs /b.rs
    ...

Narrow the report with --category . Detectors are tunable per project via the [inconsistencies] config section: disable = ["api-path"] turns a category off in run-everything mode (useful in a frontend-only repo where route literals have no server counterpart — an explicit --category still runs it), and api_path_min_segments (default 2) floors the near-miss segment count.

Get oriented in an unfamiliar codebase

coregraph stats --breakdown

symbols: 4136
edges:   24993

## Symbol kinds
  Function         1480
  DocComment        709
  Method            473
  ...

## Per-package symbol/edge counts
  package                           symbols    edges
  (no package)                         1391     8058
  coregraph                             736     5634
  coregraph-extractor                   510     3902
  ...

## Top 20 most-referenced symbols (in-degree; containers excluded)
    250  SymbolId    [Struct] @ ./crates/core/src/symbol.rs
    149  clone       [Method] @ ./crates/graph/src/bloom.rs
    122  nodes       [Method] @ ./crates/graph/src/symbol_graph.rs
    ...

## Top 20 files by symbol count
    133  ./crates/cli/src/dispatch.rs
    116  ./crates/extractor/src/lib.rs
    110  ./crates/graph/src/symbol_graph.rs
    ...

Packages come from the project's own manifests (Cargo workspaces, npm/pnpm workspaces, Maven/Gradle modules); the in-degree ranking counts only impact-bearing edges between real symbols, so file containers and doc nodes don't drown the actual hubs.

Start here on a repo you don't know — the most-referenced symbols and densest files are where the architecture actually lives.

Look up a symbol by file:line

coregraph inspect crates/query/src/impact.rs:33

── inspect: crates/query/src/impact.rs:33 ──
  compute_impact [Function] bytes 1128..3581
  doc::compute_impact [DocComment] bytes 531..1128

      32 /// depends on (outgoing) does not break when X changes.
  →   33 pub fn compute_impact(graph: &SymbolGraph, seed_id: SymbolId, max_depth: usize) -> ImpactResult {
      34     let mut visited: HashSet = HashSet::new();

Resolves whatever symbol sits at a cursor position — its name, kind, byte range, and surrounding source (default 5 lines, --context-lines). A doc::… [DocComment] line appears only when the queried position lands inside a doc comment's own span (as in the example above); inspecting a line in a symbol's body does not pull in that symbol's doc comment, and the JSON output and the editor/IPC inspect path carry no doc-comment data.

See what a function depends on

coregraph query compute_impact \
  --direction outgoing --edge-kind calls --hop-limit 1

── query: compute_impact ──────────────────────────────────

✓ compute_impact [crates/query/src/impact.rs:27]
  kind: Function | package: query (cargo)

  Outgoing (3):
  ├── calls → incident_edges [Method] @ crates/graph/src/symbol_graph.rs    [0.85] ✓
  ├── calls → is_impact_bearing [Function] @ crates/query/src/impact.rs     [0.85] ✓
  └── calls → clone [Method] @ crates/graph/src/bloom.rs                     [0.85] ✓
  ✓ trust: all paths verified

Same query as "who calls a function", flipped: --direction outgoing walks to callees/dependencies, incoming walks to callers.

Pipe results into scripts or your AI assistant

coregraph query build_router --direction outgoing --edge-kind calls \
  --output-format json | jq -r '.edges[] | "\(.other_name)  [\(.current_confidence)]"'

new        [0.95]
route      [0.95]
post       [0.95]
clone      [0.95]
dispatch   [0.95]
... (22 total)

Every analysis command (query, impact, diff, orphans, inconsistencies, stats, inspect, index) takes --output-format json, so results drop straight into scripts and CI gates (llm is honored by the commands that route through the LLM renderer; stats/inspect/index fall back to human text for it). For live editor/agent use, run coregraph lsp or coregraph mcp — see [Integrations](#integrations).

---

Key features

• Token-budgeted, LLM-ready output. --output-format llm emits compact

structured text, every result is paged against --token-budget, and --min-confidence drops low-trust noise — so an agent spends a few hundred tokens per answer instead of ingesting whole files.

• Multi-language, one graph. Seven code languages plus config and Markdown,

unified into a single index — built for monorepos.

• Cross-file name resolution. stack-graphs binds references to the

definitions they actually resolve to, across files.

• Confidence and trust on every edge. Each relationship is scored and

origin-tagged; filter with --min-confidence (default 0.70).

• Impact and risk analysis. Transitive reachability plus a risk score,

blast radius, and the tests a change affects.

• Dead-code detection. Orphan symbols, separating likely-dead from public

library surface.

• Cross-file inconsistency checks. Enum-value mismatches, API path drift,

config-key drift, and doc-drift (@param/:param naming a parameter the signature no longer has — with rename candidates suggested from the actual signature). Categories are tunable per project via [inconsistencies] in config.toml.

• Config self-tuning. coregraph config recommend measures the indexed

graph and suggests config.toml tuning (exclude lists, string-match cap, category disabling); --write applies it without clobbering comments.

• Background daemon. Auto-spawns on first use, caches the graph, and

self-terminates when idle — fast repeat queries, no resident cost when unused.

• Built-in integrations. MCP for LLM agents, LSP for editors, and an

optional HTTP API.

• 3D visualization. coregraph viz opens an interactive in-browser atlas

of the whole graph, fed live from the daemon.

---

Visualize: coregraph atlas

coregraph viz            # serves http://127.0.0.1:7321 and opens the browser
coregraph viz --detach   # same, in the background; logs to viz.log
coregraph viz --stop     # stop the detached server

coregraph viz starts a local server (127.0.0.1 only, token-guarded) with a 3D force-directed view of the symbol graph, served straight from daemon memory — no export step. If the daemon isn't running it is started for you, and a project picker lists everything already loaded. --detach runs the server outside the terminal session (it survives the terminal closing) and returns once the port answers; --stop terminates the instance recorded by the last --detach.

What you can do in the viewer:

• Explore — fuzzy symbol search, isolate a neighborhood (depth 1–3),

inspect any symbol with its incident edges and a source preview.

• Cluster by unit — group nodes by module/package/crate (derived from the

path structure) inside translucent boundary spheres, as shown above.

• Run analyses on the graph — impact paints the blast radius as a

hop-distance gradient with the risk score and affected tests; dead code, cross-file inconsistencies, git-diff impact, and shortest path between two symbols are one click away.

• Filter — symbol/edge kinds, analysis origin, minimum confidence,

min-degree and hub trimming, color by kind / directory / unit.

• Share & export — copy a link that restores the exact view, download a

PNG capture or the visible subgraph as json-graph.

• Stay fresh — the viewer polls the daemon and offers a one-click reload

when the graph changes on disk; it never resets your camera behind your back.

---

How it works

source files
     │
     ▼
 tree-sitter ──► symbols (functions, structs, config keys, doc comments, …)
     │
     ▼
 stack-graphs ─► cross-file name resolution (calls, imports, references)
     │
     ▼
 symbol graph (in memory) ──► confidence/trust-tagged edges
     │
     ▼
 background daemon ──► IPC socket │ MCP │ LSP │ HTTP

coregraph index runs both analysis layers in one pass. The resulting graph is held by a background daemon that:

• Auto-starts on the first thin-client command (query, stats, impact,

orphans, inconsistencies, `

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: simplecore-inc
• Source: simplecore-inc/coregraph
• License: MIT

Install and usage instructions live in the source repository linked above.