The repository crawl loop

• Each hop replays context.
• Text matches do not resolve aliases, re-exports, or types.
• Broad questions grow with repository size.

The compiler already knows the graph

@ttsc/graph reads the resident TypeScript-Go compiler session.

Compiler-exact relationships

• tsconfig path aliases land on the real declaration.
• Barrel re-exports preserve symbol identity.
• pnpm workspace packages and project references resolve normally.
• Symlinks and module-resolution rules are already settled.
• Diagnostics and graph facts describe the same Program.

A syntax index can infer these edges. The compiler has already proved them.

It returns an index, never source bodies

CheckoutService.place
  signature  place(input: IOrderInput): Promise<IOrder>
  declared   src/checkout/CheckoutService.ts:41-88
  calls      Inventory.reserve, Payment.authorize
  testedBy   test_checkout_place

• Names, signatures, edges, decorators, tests, and source spans
• No implementation body in the MCP response
• Read the smallest span only when body text is actually needed

Why “index only” matters

One MCP surface

inspect_typescript_graph({
  question,
  draft: { type, reason },
  review,
  request,
});

The request is a discriminated union. Choosing its type chooses the operation.

The schema carries the reasoning path

• draft names the smallest operation that looks sufficient.
• review can correct an over-broad or off-graph plan.
• request commits exactly one typed operation.

Free prose can skip a step. A required schema field cannot.

Seven request types

Escape is a first-class success

Use the graph when the answer depends on TypeScript symbols, calls, or types.

Use escape when the answer depends on:

• exact implementation text;
• configuration or documentation;
• runtime state or external systems;
• a non-TypeScript project.

Fresh on every operation

• No separate init command
• No repository-local index to remember or commit
• Unchanged calls reuse warm in-memory indexes
• Safe edits reuse the incremental compiler Program
• Config, roots, deletion, or resolution changes trigger a reload
• Refresh failure returns an error, never a stale graph

The same graph is visible in 3D

Every node is a declaration. Every edge is a compiler-resolved relationship.

Benchmark design

• Eight TypeScript repositories, from 51k to 3.1M lines
• Common onboarding prompt and repository-specific prompts
• Empty-MCP baseline plus @ttsc/graph, codegraph, codebase-memory, and serena
• Codex and Claude Code model lanes at high reasoning effort
• One published run per cell; repository breadth is the sample

This is one person's bounded benchmark. It is not a universal performance guarantee.

The headline

Answer quality was manually inspected; free-text matching was not used as an oracle.

Cost stays flat as repositories grow

small TypeScript project  ─┐
medium monorepo           ├─ answer-sized graph response
3M-line VS Code           ┘

• Baseline and comparator costs swing with repository size.
• @ttsc/graph stays near the cost of the requested index.
• Some comparator cells cost more than running with no MCP.

Cold time matters too

On the three-million-line VS Code fixture:

The published chart adds index readiness and LLM answer time in the order a developer waits.

The trade

Add it in four lines

npm install -D ttsc @ttsc/graph typescript

{
  "mcpServers": {
    "ttsc-graph": {
      "command": "npx",
      "args": ["-y", "@ttsc/graph"]
    }
  }
}

Explore your graph in the browser

npx @ttsc/graph view

• Opens the project graph in a 3D viewer.
• Color and filter by declaration or edge kind.
• Inspect incoming and outgoing relationships.
• Export a snapshot for sharing.

Boundaries are deliberate

• TypeScript only: compiler depth is tied to one language.
• An index is not the implementation body.
• Graph evidence cannot answer config, prose, runtime, or external-state questions.
• The benchmark result can be lower or negative on a different workload.

The tool steps aside when its evidence is not the right evidence.