TypeScript graph tool cuts AI coding tokens by ~90%

@ttsc/graph is an MCP (Model Context Protocol) server that gives AI agents a code graph instead of source files. It works by indexing a TypeScript codebase into a graph of declarations and their relationships, with every node and edge resolved by the TypeScript compiler itself. When an agent asks a code question, the server answers from the graph through a single tool interface, returning names, signatures, relationships, and source spans—never file bodies.

Traditionally, coding agents answer code questions by grepping the repository and reading file after file into context. This file-reading dominates the token bill. The graph removes that need: because neither the agent's question nor the server's answer grows with repository size, the token cost falls proportionally. In a benchmark across eight real TypeScript repositories using the onboarding question (a plain code tour), an agent answering through @ttsc/graph spends only 4% of what it spends without the server. This flat, low cost contrasts sharply with competing tools like codegraph and serena, whose costs swing with repository size.

The setup is straightforward: `npm install -D @ttsc/graph` and configure the MCP server in the client. The project needs ttsc and typescript installed. Because the graph is a byproduct of TypeScript's type-check—which the compiler runs anyway—there is no separate index step and no static-parser fallback. The graph either comes from a successful type-check or is not built at all.

The tool's most striking advantage appears in indexing time. On a codebase of three million lines, @ttsc/graph builds in 29 seconds (tested on VS Code), while codegraph takes 12 minutes and serena takes 4.5 minutes. At that scale, the index question stops being academic. The tool answers seven request types from a single interface: tour (architecture and code orientation), entrypoints (where execution starts), lookup (locate a symbol), trace (follow calls or data flow, or find a path between two symbols), details (signatures, members, and implementations), overview (project layers), and escape (when the answer is outside the graph). An agent entering the tool with a code question must first state the question, draft the smallest request type that could answer it, then review and finalize the request. This chain-of-thought structure is embedded in the API's required fields, forcing the agent to reason on entry rather than guessing. If the graph cannot answer or the evidence lies outside it, the review field can flip the draft to an escape, backing out cleanly in one small call instead of derailing the session.

The contract the tool offers is radical: returned graph facts are infallible for the current source snapshot. The compiler has already validated every name, span, edge, signature, and step, and the server explicitly forbids the agent from re-reading files or making extra graph calls to verify. This design keeps the agent on the graph path, because verification reads are what destroy token savings. By contrast, serena and codegraph each offer dozens of tools around their graph, inject 100–150 lines of instructions (mostly forbidding file reads), and include source snippets inline; agents often pick the wrong tool, and the injected constraints feel restrictive. @ttsc/graph opts for precision over restriction: answers carry compiler-resolved facts that the agent accepts as final, so nothing is forbidden—grep and file reads remain available, but the agent uses them only when they are the right move.

The core problem @ttsc/graph solves is token waste. When an AI agent answers code questions by grepping a repository and reading files into context, nearly all the token cost comes from file I/O. The tool's insight is that file bodies are rarely the answer — the agent usually just needs names, signatures, relationships, and line numbers. By indexing the codebase once and answering from a graph instead, both sides of the exchange stay small: the agent makes fewer calls, and each answer is compact.

What separates @ttsc/graph from earlier tools like codegraph and serena is that its cost does not scale with repository size. Because the graph is built as a byproduct of TypeScript's own type-check (which must run anyway), the index overhead is negligible. The agent on the benchmarked onboarding task spends only 4% of baseline tokens, and that ratio holds steady across repositories. In contrast, tools that require separate indexing steps face a steep build-time penalty that grows with codebase size — a problem that becomes acute at three million lines.

The tool's design also addresses agent behavior. By making graph results authoritative (compiler-verified), the agent stops querying and verifies once it has an answer, rather than double-checking with file reads. This is enforced through clear API design: the graph returns only what the compiler can certify, and the interface explicitly forbids the agent from re-reading files to "verify" results.