On Graphify: Give AI a Map Before Letting It Read Your Code

This morning, my friend Mr. Liu—a full-stack engineer I’ve known for years—dropped a GitHub link in our chat. “Worth checking out,” he said. The repo was something called Graphify.

My first instinct was that it was probably a local MCP server, or maybe just a token-saving trick for AI coding assistants. After digging into it properly, I’d say it’s related to both of those things, but it’s not quite what I expected.

It’s better described this way: before letting AI read your code, Graphify draws it a map first.

What Graphify Actually Does

The core idea is straightforward. Graphify scans your project directory—code, docs, PDFs, images, the whole thing—and turns it into a queryable knowledge graph. Everything lands in a graphify-out/ folder with three main outputs:

• graph.json — the machine-queryable graph structure
• GRAPH_REPORT.md — a human-readable report of core nodes, surprises, and suggested questions
• graph.html — an interactive visual graph you can explore in a browser

Then it runs an MCP server (graphify serve) that exposes this graph to tools like Claude Code, Codex, Cursor, and Gemini CLI. Instead of reading your entire repo from scratch every session, the AI can query the graph first to figure out which files it actually needs to look at.

A side note on credibility: this project currently has 72k+ stars on GitHub. It’s not an early experiment—it’s an actively maintained tool with a real community ecosystem around it.

The Problem It’s Actually Solving

There’s a real frustration at the heart of this. When you use an AI coding assistant on anything larger than a toy project, the AI essentially has to re-learn the codebase every time. It reads the README, scans the directory structure, looks at models, services, config files, SQL schemas, XML—and you’ve burned a significant chunk of your token budget before any actual work happens.

Graphify tries to break this cycle. You pay the cost once upfront to build the graph. After that, when you ask “where’s the auth flow?” or “what views does this model touch?” or “where does this API endpoint up?”, the AI can navigate the graph to find the relevant nodes first, then read those specific files rather than doing a brute-force scan of everything.

That’s a reasonable approach. But it raises an important question: how accurate is the map?

Token Savings Aren’t the Point

If it saves tokens but degrades understanding, the tool is worthless.

The goal of an AI coding assistant isn’t to be cheap—it’s to accurately understand the code, make fewer wrong edits, and stop hallucinating files that don’t exist. Saving tokens at the cost of correctness is a bad trade.

What Graphify can demonstrate fairly clearly is context token reduction. Its benchmarks compare “how many tokens to load the full corpus” against “how many tokens to return a relevant subgraph query”—and on larger projects, the difference is substantial.

What it hasn’t rigorously demonstrated is the harder question:

After using Graphify, does the AI understand the codebase as well as it would have by reading the whole thing?

In other words: it shows you’re reading less, but not that reading less is equally good. Has it been tested against patch success rate? Against hallucination frequency? Against direct repo reading baselines? I haven’t seen that data.

This matters because token efficiency is an engineering metric. Accuracy is the metric that actually affects developer experience.

The Map Is Not the City

This is the most important framing I can offer: Graphify produces a map, not the city itself.

A map tells you roughly where the roads are, where the bridges are, where the core neighborhoods are. But when you’re actually doing construction, you still need to visit the real location and see what’s actually there.

In code terms: Graphify can help an AI quickly identify where to look, but it shouldn’t replace actually reading the real source files. The right workflow isn’t “AI reads graph.json, then edits code.” That’s too risky. The right workflow is:

1. Query the graph to find direction
2. Read the actual source files
3. Then write the code

Graphify should be the navigation layer, not the source of truth.

On Staleness—and Graphify’s Built-In Answer

graph.json is a snapshot of your project at a moment in time. If the code changes and the graph doesn’t get updated, the AI is navigating by an old map—which is potentially worse than no map at all.

The good news is that Graphify already has mechanisms for this. Running graphify hook install sets up a git post-commit hook that automatically rebuilds the graph after each commit. There’s also an --if-stale flag that lets the tool check whether its graph is out of date before answering queries. Incremental caching is built in too—only changed files get reprocessed, not the whole project.

So the staleness problem is real, but it’s not ignored. Whether this machinery integrates cleanly into your specific workflow is worth testing, but the tooling is there.

What Runs Locally, What Goes to an LLM

This is worth spelling out clearly, because it affects how you think about privacy.

The code analysis side of Graphify—class definitions, function call relationships, import chains, symbol indexing—all of this runs through tree-sitter and AST parsing locally. Your raw source code is never sent to any LLM.

Only semantic content like documentation, PDFs, and images gets sent to a model API (Claude, OpenAI, or a local setup like Ollama or LM Studio). Graphify doesn’t bundle its own model; it uses whichever API key your AI tool already has configured.

So “it’s fully local” isn’t quite accurate, and neither is “it sends your code to the cloud.” The accurate description is: code is analyzed locally, semantic content goes to a model as needed.

Project Size Determines Whether It’s Worth It

The single most important variable here is how large your project is.

It’s not a tool that makes things better by default. The value compounds with project complexity: the larger the project, the higher the cost of re-reading it repeatedly, and the more Graphify’s index layer earns its place.

The flip side also holds: the larger the project, the more damaging a wrong or stale graph becomes. So the bigger the project, the more you need Graphify—and the more rigorously you need to verify it.

Three Possible Futures for This Kind of Tool

I think tools in this category will evolve along three distinct paths.

Personal tool is where Graphify fits best right now. Local install, local scan, local graph, local MCP server—feeding into Codex, Claude, or Cursor for one person’s workflow. Deployment is minimal (pip install graphifyy and you’re mostly there). The upside is simplicity, privacy, and the ability to handle uncommitted changes. The downside is that the index isn’t shared across teammates.

Team tool works for larger engineering teams. The graph gets rebuilt in CI, graphify-out/ gets committed to the repo so everyone starts with the same project map, and PR reviews get automatic impact analysis. This is where containerization starts making sense, though it doesn’t necessarily require going microservices.

SaaS / platform is a different category entirely—connecting to GitHub/GitLab, background workers scanning repos, storing and serving graphs, providing a web UI and MCP endpoints with auth and audit trails. This is the right answer for enterprises with multiple repos and teams. It’s also expensive, complex, and substantially farther from the actual development environment.

None of these is inherently better. The right deployment model depends entirely on who you’re building for.

How I’d Design a More Mature Version

If I were architecting this from scratch, I’d make the separation between two layers explicit.

Deterministic core: file scanning, code parsing, symbol extraction, import/call/reference graph construction, incremental updates, graph queries. This layer should be as fast, stable, and reproducible as possible—no LLM involvement.

AI semantic layer: module intent summaries, business flow explanations, report generation, document/PDF/image processing, answers to higher-level architectural questions. This layer uses a model, either cloud or local.

The architecture roughly looks like this:

┌──────────────────────────┐
│ AI Coding Assistant       │
│ Codex / Claude / Cursor   │
└─────────────┬────────────┘
              │ MCP / CLI query
┌─────────────▼────────────┐
│ Graphify Adapter          │
│ CLI / MCP / report layer  │
└─────────────┬────────────┘
              │
┌─────────────▼────────────┐
│ Deterministic Index Core  │
│ scan / parse / graph      │
└─────────────┬────────────┘
              │
┌─────────────▼────────────┐
│ Local Graph Store         │
│ graphify-out/graph.json   │
└──────────────────────────┘

The key principle: AI doesn’t blindly scan everything. Graphify helps it find direction first. The AI reads real source files before making changes.

My Bottom Line

Graphify is a genuinely interesting approach, and it’s particularly well-suited to medium and large projects—especially ones where code, docs, database schemas, and configuration files are all tangled together. An Odoo plugin with Python models, XML views, CSV security files, manifests, and wizard imports is a good example: making an AI re-read all of that from scratch every session is wasteful. If Graphify can pre-map the relationships between those components, it’s providing real value.

But I wouldn’t treat it as a replacement for the AI actually reading your code. Its best positioning is: help the AI take fewer wrong turns. Not: let the AI skip reading the real files.

The safest operating rule is three steps: query the graph, read the relevant files, then write the code. Graphify tells the AI where to look. The actual source code tells the AI what’s really there.

Used that way, this tool is probably worth your time. Using it purely to save tokens, without validating accuracy? That’s not enough.