Graphify: give your AI a map and stop burning tokens

In the previous article we talked about how AI doesn't "live" all the time: it spins up when you talk to it, handles your request, and goes idle. That idea has a very practical consequence almost nobody mentions: every time you open a new conversation, your AI arrives at your project as if it were its first day on the job. It doesn't know which files you have, how they connect to each other, or why you wrote something a certain way.

And that's where tokens start burning. A token is, roughly, a small piece of text (a word or part of one) that the AI reads or writes, and both usage limits and costs for these tools are measured in them. The more text the AI has to read to understand your project, the more tokens it spends, and the more resources each question consumes. If last week we talked about what every prompt costs the planet, today we're talking about a way to stop wasting them.

A tourist without a map

Imagine you arrive in a city you don't know and ask someone: "help me find this address." If that person has no map, they have no choice but to walk street by street until they find it. They'll get there, but they'll spend a lot of time and energy. With a map, they plot the route in seconds.

That's exactly what happens to AI with your code. If you say "I have a bug somewhere in the project, figure it out," it opens file after file looking for a place to start, and every file it reads counts as tokens. In a small project you barely notice. In one with hundreds or thousands of files, you do.

What is Graphify?

Graphify is an open source tool that turns your project (code, documentation, PDFs, images, even video) into a knowledge graph that your AI assistant can query instead of reading files one by one. It installs as a skill inside tools like Claude Code, Cursor, Codex, Gemini CLI, or GitHub Copilot, among more than twenty supported platforms, and it already has over 120 thousand stars on GitHub.

And what's a graph? Think of a subway map: stations and the lines that connect them. In Graphify, the "stations" are classes, functions, files, and concepts, and the "lines" are the relationships between them: this file imports that one, this function calls that one, this class inherits from that one. Your project, drawn as a map.

How it works, without the jargon

According to its documentation, Graphify processes your project in three passes:

• Code (free and local): it parses your code with tree-sitter, which breaks it down into its structure: which classes, functions, and imports exist and how they call each other. It's deterministic, uses no AI model, and nothing leaves your machine.
• Audio and video (local): it transcribes them on your own computer with faster-whisper.
• Documents, PDFs, and images (uses AI): this pass does use your assistant's model to extract concepts and relationships, which is why it does consume tokens. That's why the .graphifyignore file exists (it works just like .gitignore): to leave out what adds nothing, like node_modules or dist. Two design details are worth highlighting. First: every relationship in the graph is tagged EXTRACTED (found directly in the code), INFERRED (deduced), or AMBIGUOUS (uncertain), so you always know what was read and what was guessed. Second: it uses no embeddings or vector databases; it's a real graph you traverse, and the project's subsystems are grouped using a community detection algorithm (Leiden).

What you get

When you run /graphify . on your project, you get a graphify-out/ folder with three files:

• graph.html: an interactive visualization of the graph that you open in any browser.
• GRAPH_REPORT.md: a report with the "god nodes" (the most connected concepts, where everything flows through), surprising connections between modules, and suggested questions.
• graph.json: the full graph, which can be queried at any time without re-reading your files. And yes, there's a .md doing important work again. On top of that, commands like graphify claude install (or the equivalent for your tool) write instructions into your CLAUDE.md or AGENTS.md so the AI consults the graph before it starts reading files. It's the same principle from the article about .md files: context written down so the AI doesn't have to guess.

With the graph built, you can ask your project things directly:

• graphify query "what connects authentication to the database?" returns a subgraph with the relevant parts.
• graphify path "UserService" "DatabasePool" traces how two things connect.
• graphify explain "RateLimiter" explains a concept and everything around it.

Why it's worth using

• Fewer tokens on large projects: instead of reading whole files, the AI queries only the piece of the graph it needs. According to the project's own benchmarks, on a mixed corpus of 52 files the savings were 71.5x fewer tokens per query.
• Understanding a project you don't know: the report shows you at a glance what matters most and which modules connect in unexpected ways. Useful for inherited repos or when you join a new team.
• Answers with a trail: path and explain don't just answer, they also show where the connection passed through, with its confidence tag.
• The "why," not just the "what": comments like # NOTE: and # WHY:, and references to ADRs or RFCs, become nodes linked to the code they explain.
• It doesn't start from scratch every time: the graph persists between sessions, and a hash-based cache only reprocesses files that changed. With graphify hook install, it also rebuilds itself on every commit (code only, no API cost).
• Your code stays on your machine: code analysis is local. Only documents, PDFs, and images go through your assistant's model.

The honest part: it's not magic

Before you run off to install it, something important needs saying. Graphify's own documentation acknowledges that the savings depend on the size of the project:

With six files, everything already fits in the AI's context window, so there the graph brings clarity, not savings.

And there's more. In mid-May 2026, a patch was merged in response to a problem reported by several users: Claude Code was using more tokens with Graphify installed than without it. The cause was that the install instructions told the AI to always read GRAPH_REPORT.md before any search, and in real projects that report weighs between 12 and 25 thousand tokens. In a test on a Go monorepo of about 1,500 files, the previous version needed 5 calls and 34 thousand tokens, versus 4 calls and 30 thousand without Graphify. With the patch, which tells the AI to query with graphify query first, the same question was resolved in a single call and 30 thousand tokens.

In another issue, a user with a project of around 1,484 files commented that each query ran around 2 thousand tokens, and that chaining three or four added up to more than 8 thousand, comparable to what Claude Code spent using traditional searches.

The takeaway: measure it on your own project. And notice something that closes the loop with last week's article: even a tool built to save tokens needed real people to notice the problem, report it, and fix it. Behind every prompt there's a human being, and behind every tool too.

How to get started

You need Python 3.10 or higher and, preferably, uv. Then:

# <span id="sec-7-install-the-cli-heads-up-the-official-package-has-a-double-y" class="scroll-mt-28"></span>Install the CLI (heads up: the official package has a double "y")
uv tool install graphifyy
 
# <span id="sec-8-register-the-skill-with-your-ai-assistant" class="scroll-mt-28"></span>Register the skill with your AI assistant
graphify install

Then, in your assistant, inside your project:

/graphify .

A couple of notes so you don't trip: the official package on PyPI is graphifyy (with a double "y"), and other packages starting with graphify are not affiliated with the project. In PowerShell use graphify . without the leading slash, and in Codex the command is $graphify.

Some steps that help you get more out of it:

• Create a .graphifyignore to exclude folders that add nothing (dependencies, builds, generated files).
• Run graphify claude install (or your platform's command) so your assistant consults the graph by default.
• Install the hooks with graphify hook install so the graph updates with every commit, and run graphify update . after every git pull.
• If you use Claude Code, add graph.json and graphify-out/ to your .claudeignore, because according to the documentation, those files can invalidate the prompt cache every time they change.

When yes and when no?

It makes a lot of sense if you work with large projects with many modules, if you inherit code you didn't write, if your repo mixes code with documentation, PDFs, or diagrams, or if your team wants to share a single graph (you can version graph.json for that).

It makes less sense for scripts or projects with only a few files. There, the AI can already read everything without trouble, and all you gain is clarity.

The graph tells you what exists, you decide why

Graphify doesn't replace the ARCHITECTURE.md you write by hand. The graph shows you what exists and how it connects; your documentation explains why it was decided that way. A tool that draws maps doesn't know where you want to go, and that's still up to you. That's why everything we've covered in this series, from architecture to .md files, fits together: a solid foundation, good context, and a good tool so AI works in your favor and not the other way around.

In the next article we'll talk about something that changes everything and almost nobody takes care of: how to talk to an AI well, and why the same model can give you a brilliant answer or a mediocre one depending on how you ask.

Have a great weekend, and remember: progress isn't something we should fear, but something we should learn to work with.