Skip to content
Shekhar Kumar

All projects

Open source · Active

NeatCode

A code graph that answers coding agents' structural questions over MCP instead of making them read whole files.

Role
Author & maintainer
Period
Apr 2026 – present
Updated

TL;DR

  1. Indexes 131k lines of TypeScript in 3.8s and answers structural queries in under 300ms.
  2. 11 deterministic MCP tools. In a published benchmark (mcp-evals), GPT-6.1 Sol used 61% less tool-result context with NeatCode than with a file-reading MCP server, at the same 100% task success.
  3. Open source on npm as @neatcodeai/cli, with 510 tests at a 0.68:1 test-to-code ratio.
to index 131k LOC
3.8s
structural queries
<300ms
incremental re-index
0.49s
less context than a file-reading MCP server (GPT-6.1 Sol)
61%
MCP tools
11
tests
510

This website, indexed by NeatCode

Real data

  • routes (app/)
  • components/
  • content/
  • lib/

66 files · 127 links · indexed in 1.3s

Pick a question above, or select any file in the graph to see what it uses and what uses it.

Built from the graph.db NeatCode produced for this site's own source. Each dot is a file; each line is an import, render or call between files. Pick a question or select a file to see what query_graph returns.

The problem

Coding agents spend most of their context window rediscovering the codebase. Every turn they grep, open files, and read far more than they need, and they still miss the structural answer: who calls this, what renders that, where the event gets published.

They also ignore the conventions a repo already follows, because nothing tells them what those conventions are until a reviewer complains.

My role · Author and maintainer: architecture, the parser and graph engine, the MCP server, the CLI, tests and npm releases (v0.1.4 published October 2026).

How it works

  1. Parse with the TypeScript compiler

    ts-morph walks every .ts/.tsx file, and the TypeChecker resolves calls across files, so edges point at the real symbol rather than a name match.

  2. Store a code graph in SQLite

    Files and symbols become nodes; imports, calls, renders and containment become edges, each tagged EXTRACTED, INFERRED or AMBIGUOUS so the agent knows how much to trust it.

  3. Re-index only what changed

    A content-hash sync layer re-parses only edited files, cutting re-index cost from 3.8s to 0.49s on an unchanged 1,821-file repository.

  4. Mine the repo's conventions

    A heuristic miner proposes rules from patterns the code already follows; accepted rules live in .neatcode/skills.yaml and validate_diff checks planned changes against them.

  5. Serve it to agents over MCP

    A stdio MCP server exposes 11 tools (query_graph, find_node, trace_flow, validate_diff and more), and `neatcode claude install` wires it into Claude Code in one command.

Key decisions

  • Embedded SQLite for the graph

    instead of: A graph database or a hosted service

    Zero ops and local-first: the engine ships as an npm package, and the index is a single file in the repo's .neatcode/ folder.

  • Deterministic graph queries, no LLM in the hot path

    instead of: Embedding search over code chunks

    Structural questions have exact answers. Graph edges are reproducible, cost nothing per query, and never hallucinate a caller.

  • stdio MCP transport

    instead of: An HTTP server

    Editors spawn the server as a local process: no ports, no auth, no daemon to babysit.

  • TypeScript first

    instead of: Shallow multi-language parsing from day one

    The TypeChecker gives precise cross-file call graphs. Depth on one language beats guesses across five; other languages are on the roadmap.

Outcomes

  • 131k LOC indexed in 3.8s (~35k LOC/s, single-threaded ts-morph with batched transactions).
  • Structural queries answered in under 300ms.
  • In the mcp-evals benchmark (144 runs, published with traces), GPT-6.1 Sol solved all 24 runs both with NeatCode and with the filesystem MCP server, using 61% less tool-result context (median 3,235 vs. 8,390 tokens) and 46% lower cost per task with NeatCode. Two smaller flash models scored lower with NeatCode than without it, so the gain depends on the model.
  • This portfolio indexed in 1.3s to power the demo above (66 linked files shown).
  • 510 tests at a 0.68:1 test-to-code ratio, full suite green in 12s.

What's next

  • v0.2: Cursor and Codex installers, import-forbidden and edge-forbidden rule mining, agent-proposed rules.
  • v0.3: watcher mode, JavaScript indexing, TypeScript LSP integration.
  • Later: Python and Go, with multi-language graphs joined by import-edge inference.

Stack

  • TypeScript
  • ts-morph
  • SQLite
  • MCP

Links