AI Guides › Step-by-step guides

Build a Codebase Map Claude Reads Before It Reads Your Files

By Nigel Guy · 6 min read

On a large project, the usual pattern is that Claude Code explores the code again in every fresh session: searching, opening files, piecing together how things connect, before it touches your actual question. Each of those file reads lands in the context window, and a bigger context makes every later message in the session heavier. It feels harmless because the answers still arrive, so the waste never shows up as an error.

Graphify is a free, open-source tool that builds a map of your project once, saves it to disk, and nudges Claude Code to query that map before opening files one by one. It is worth setting up, but it is not magic, and one trap in particular catches people (Step 5).

The rule: Build the map once, keep it fresh cheaply, and treat it as a guide to which files to open, never as a replacement for opening them when the answer matters.

Before you start

You need:

Cost at time of writing: Graphify is free and dual-licensed (Apache-2.0 and MIT). For code, it parses files locally with tree-sitter, with no model calls and nothing leaving your machine. If you also point it at documents, PDFs or images, those are sent to your AI assistant's model for extraction, so that part uses your normal Claude usage. Claude Code itself is billed by token use, so a Pro or Max plan or API credit applies as usual; check the £ price on Anthropic's pricing page at checkout rather than trusting a figure in a guide.

One naming quirk: the package on PyPI is spelled graphifyy, with two Ys. The command you run afterwards is graphify, with one.

Step 1 — Install the package

In a terminal:

uv tool install graphifyy

If you do not use uv, the project also documents pipx install graphifyy and pip install graphifyy. On macOS, if you hit environment conflicts, the project suggests pipx. On Windows you may need to add Python's Scripts folder to your PATH yourself.

Step 2 — Register it with Claude Code

graphify claude install

According to the project, this writes configuration telling Claude Code to prefer the knowledge graph for codebase questions, and installs a PreToolUse hook that nudges Claude towards graphify query before it reads files individually. The project's technical notes say the manual setup writes a skill to ~/.claude/skills/graphify/SKILL.md and edits ~/.claude/CLAUDE.md. That is your global file, so open it afterwards and read what was added.

There is also a plain graphify install, which registers the skill without the hook behaviour. If you want the skill but not the nudge, use that instead.

Step 3 — Build the map inside your project

Open Claude Code in the project folder and run:

/graphify .

The project's README shows the trailing . (the current folder). The commonly shared shorthand is /graphify on its own, so if one form is rejected, try the other. When it finishes you should find a graphify-out/ folder containing:

File What it is
graph.json The queryable graph itself
GRAPH_REPORT.md Key concepts, surprising connections, suggested questions
graph.html An interactive visualisation you can open in a browser

The first build on a big project takes the longest. Results are cached by file hash, so later runs only reprocess files that changed.

Step 4 — Keep it fresh

A stale map is worse than none, because it answers confidently from old code. The project documents three options:

For most people the commit hook is the least-effort choice. Run it once and forget it.

Step 5 — Use the map, and know the trap

Ask architecture questions the graph is built for. The documented query commands are:

You can also ask Claude directly. Fill in the bracketed parts:

You are helping me understand a codebase using its Graphify map in graphify-out/.

Goal: explain how [FEATURE_OR_FLOW] works, and name the specific files I should open to confirm it.

Steps:
1. Query the graph first (graphify query, then path or explain where useful). Do not scan the whole repository.
2. Summarise the flow in plain English, in order.
3. For every claim, say whether the graph labels the link EXTRACTED, INFERRED or AMBIGUOUS.
4. List the files and functions I should read to verify anything INFERRED or AMBIGUOUS.

Constraints: if graphify-out/ is missing or looks older than the latest commit, tell me and stop rather than guessing. If my question is too vague to query, ask me one clarifying question first.

Before answering, check that every file path you mention appears in the graph output.

Fill in: the feature or flow you want explained.

The trap. Graphify tags every relationship EXTRACTED (found directly in the code), INFERRED (deduced) or AMBIGUOUS (uncertain). Only the first is a fact. Reading a summary built on inferred links as if it were gospel is the way a map saves tokens and still costs you a wrong edit. The second trap is staleness, covered in Step 4.

Check it worked

  1. graphify-out/graph.json and GRAPH_REPORT.md exist in the project.
  2. Open GRAPH_REPORT.md. Does it name concepts you recognise from your own project? If it is full of things you have never heard of, the wrong folder was mapped.
  3. Run /hooks in Claude Code to confirm the hook is registered (Claude Code's own docs describe /hooks for this).
  4. Start a fresh session, ask a structural question, and watch whether Claude queries the graph before opening files.
  5. Compare before and after with /usage and /context, which Claude Code's cost documentation describes for tracking token use. Do this on your own project. The project's headline claim of "71.5x fewer tokens per query" is the author's measurement on a mixed corpus of repositories, papers and images, so it is not a promise for yours.

What to skip

Guardrails

Sources

All 751 AI guides · JulieMango plans from £17/mo