AI Guides › Step-by-step guides
By Nigel Guy · 6 min read
Most people fix "Claude Code keeps re-reading my whole repo" by writing a longer CLAUDE.md or by pasting file lists into the prompt. It feels productive, and it goes stale the first time you move a folder. The better fix is a map that is rebuilt from the code itself, so the assistant can ask "what connects to this?" instead of opening files one by one.
Graphify is an open-source tool that builds that map. This guide covers the setup, what the install changes on your machine, how to keep the map current, and the traps. One honest note first: the original social post this topic came from made claims about long-term use, and I could not verify those. Everything below comes from the tool's own PyPI page and GitHub README, checked on 2026-10-04.
The rule: a graph is only useful while it matches the code, and the install is only safe once you know exactly what it writes to your project.
graphifyy. The command you run is graphify, with one.In a terminal, run:
uv tool install graphifyy
If you do not use uv, pipx install graphifyy or pip install graphifyy are the listed alternatives. Run graphify --help afterwards. If the command is not found, your tool directory is not on your PATH; fix that before going further.
Run:
graphify claude install
According to the project's README, this does three things:
graphify query over reading raw files.graph.json merges without conflict markers when several people commit it.Read that list twice. It edits instruction and hook files in your project, and you should know which. After running it, open the project's CLAUDE.md and look at what was added. Then start Claude Code and type /hooks to open the hooks browser and see what is registered. Hook config lives in your .claude/settings.json or .claude/settings.local.json, as described in the Claude Code hooks guide.
Open Claude Code in the project folder and type:
/graphify .
The README describes three files landing in a graphify-out/ folder:
| File | What it is | Who it is for |
|---|---|---|
graph.html |
Interactive graph you open in a browser | You |
GRAPH_REPORT.md |
Highlights, communities, suggested questions | You and Claude |
graph.json |
The full queryable graph | Claude and the CLI |
Start with GRAPH_REPORT.md. The suggested questions are a quick way to see whether the structure matches how you think about your own code.
The README lists three query commands you can also run yourself in a terminal:
graphify query "how does login reach the database?" searches the graph.graphify path "NodeA" "NodeB" traces a connection between two things.graphify explain "concept" describes a node and what it touches.Once the hook and CLAUDE.md are in place, Claude Code should reach for these before reading files. You can also steer it directly. Fill in the square brackets:
You are helping me understand an unfamiliar part of my codebase.
This project has a Graphify graph in graphify-out/.
My question: [YOUR_QUESTION_ABOUT_THE_CODE]
Area I care about: [FOLDER_OR_FEATURE_NAME]
Steps:
1. Check GRAPH_REPORT.md and use `graphify query` or `graphify path`
to find the relevant nodes before opening any source file.
2. Open only the files the graph points to.
3. Answer in this format: a two-sentence summary, then a list of the
files involved with one line each on their role.
4. Say which statements came from the graph and which from reading code.
Rules: if the graph looks out of date (a file it mentions does not
exist, or a file I mention is missing), stop and tell me to rebuild
rather than guessing. Ask me if the question or area is unclear.
Before you answer, check that every file you name actually exists.
This is the step people skip, and it is the whole difference between a map and a stale drawing. The README lists these options:
/graphify ./path --update re-extracts only changed files.graphify watch ./src keeps the graph in sync as files change.graphify hook install adds post-commit and post-checkout hooks, so commits and branch switches rebuild the graph.git pull, run graphify update . yourself. Per the README, pulls are not covered by the hooks.--force overwrites graph.json even if the new graph has fewer nodes. Use it after a big refactor, not by habit.Pick one routine and stick to it. The simplest is graphify hook install plus graphify update . after every pull.
Create a .graphifyignore file in the project root using .gitignore-style patterns. Graphify already respects your .gitignore. When both exist the patterns are merged and .graphifyignore is evaluated last. Files your .gitignore excludes are never re-included by it. Put generated code, vendored folders and anything confidential here before the first build, not after.
graphify-out/ exists with the three files above./hooks in Claude Code shows the entries Graphify added.graphify command before opening files, and the files it names should exist.graph.json and queries instead.graphify extract with an API key unless you want CI use. It is a separate path that needs explicit credentials.~/.cache/graphify-queries.log if you set GRAPHIFY_QUERY_LOG_ENABLE=1..graphifyignore.graphify --help and the README.graphify uninstall removes it from all platforms. Add --purge to delete graphify-out/ too.