Why this matters
Every new Claude Code session starts without knowing how your project fits together. It greps, opens files one at a time, and rebuilds a mental map that disappears when the session ends.
On a small repo, that can be fine. As the project grows, an agent can miss a caller or edit a function other files depend on. The breakage may surface somewhere else, far from the change.
What CodeGraph is
CodeGraph is a free, open-source tool released under the MIT license. It parses a codebase into a local graph of functions, classes, callers, and imports. It stores the index in a SQLite database inside the project, then lets an agent query it over MCP instead of reading files one at a time.
A question like “How does checkout work?” can return relevant source, the call path, and the potential impact of changing it. Everything runs on your machine with no API keys. A file watcher re-indexes about two seconds after a save, and the tool lists Claude Code, Cursor, and Codex as supported clients.
How it fits with memory
CodeGraph is not memory, and that is useful. Your CLAUDE.md holds the why: conventions, decisions, and things to avoid. CodeGraph holds the where: the map of what calls what. Memory cannot hold a complete map of a large codebase, and a graph cannot explain why you chose a pattern. Use both.
| Layer | What it holds and who updates it |
|---|---|
CLAUDE.md / memory | Rules, decisions, conventions, and things to avoid. You or the agent keep it current when you make or clarify a decision. |
| CodeGraph | Symbols, call edges, and dependencies. Its file watcher keeps the index current. |
Setup in about five minutes
- Install the CLI. Run the one-time installer with npx, or install it globally with npm.
- Connect your agents. Run
codegraph installto connect Claude Code, Cursor, or Codex and add a short CodeGraph section toCLAUDE.md. Restart your agent afterwards. - Index each project. From the repo, run
codegraph init. The installer does not index projects; this step does. - Check the index. Run
codegraph statusto see what was indexed. - Keep the database out of Git. Add
.codegraph/to your.gitignore.
# 1. Install
npx @colbymchenry/codegraph
# Or install globally:
npm i -g @colbymchenry/codegraph
# 2. Connect your agents, then restart them
codegraph install
# 3. Index the project you are in
cd ~/code/your-project
codegraph init
# 4. Confirm the index
codegraph status
# 5. Keep the database out of Git
echo ".codegraph/" >> .gitignore
# Optional: turn off anonymous usage stats
codegraph telemetry off
If your repo contains committed vendor or generated code, add an exclude list in a codegraph.json at the project root so the graph does not fill up with code you do not own.
Prompts to add to your workflow
1. Expand the CLAUDE.md instructions
The installer adds a short section. This longer block explains when to query the graph, how to handle stale results, and how CodeGraph fits alongside your project rules.
## How to navigate this codebase
This project is indexed with CodeGraph. Treat it as a map of the code, and treat this file as the rules for working in it.
### Use CodeGraph first
- For structural questions ("how does X work", "where is Y defined", "what calls Z", "what breaks if I change this"), call codegraph_explore before grepping or opening files.
- Name the specific file, function, class, or route in your query. Specific queries return current source; vague ones return a survey.
- Treat the graph as your map. Verify source when the result warns that it is stale, pending re-index, or incomplete.
- If a response says a file is pending re-index, wait a moment or read that file directly.
### Before you change code
1. Ask CodeGraph for the blast radius of the function or file you are about to edit.
2. List callers that could break, and tell me if any are outside the area I asked you to work in.
3. If the change touches more than 5 files or crosses a module boundary, show me a plan before writing code.
4. After the change, ask CodeGraph which tests are affected and run those first.
### When CodeGraph is not the right tool
- Config files, docs, env files, and anything over 1 MB are not in the graph. Read those directly.
- CodeGraph tells you where things are and how they connect. It does not tell you why we built them that way. For the why, check the Decisions section of this file, and ask me if it is not there.
### Keep this file useful
- When I correct you, add a one-line rule to this file so you do not repeat the mistake.
- Never copy code structure into this file. The graph already knows it, and copies go stale.
2. Run the first-session tour
Run this once in a fresh session after codegraph init. It checks the index, gives you an architecture overview to review, and records key decisions where future sessions can find them.
We just indexed this repo with CodeGraph. I want you to learn the codebase before we build anything, and leave notes so future sessions start smarter.
STEP 1: CONFIRM THE GRAPH WORKS
Run a codegraph_explore query on the main entry point of the app. Tell me what you found and whether anything looked stale or incomplete.
STEP 2: MAP THE ARCHITECTURE
Using CodeGraph, not grep or reading files one by one, give me:
- The main modules or areas of the app and what each is responsible for
- The 3 to 5 most important flows, traced end to end (for example: signup, checkout, or the main API request), with the key function at each hop
- The most connected functions or files, meaning the ones with the most callers. These are where a careless change can do the most damage.
- Anything that looks like dead code, a circular dependency, or two modules doing the same job
STEP 3: ASK ME ABOUT THE WHY
List up to 8 questions about decisions you can see in the code but cannot explain from the code alone (why this library, why this pattern, why this is split up this way). Ask one at a time and wait for my answers.
STEP 4: WRITE IT DOWN
Add a "## Decisions" section to CLAUDE.md with my answers, one line each. Then add a "## High-risk areas" section listing the most connected files and what to check before touching them.
RULES
- Do not paste code or file trees into CLAUDE.md. Only decisions, rules, and risk notes.
- Keep the whole CLAUDE.md under 200 lines. If it is already longer, tell me what you would cut.
- If CodeGraph and the source code disagree, say so instead of picking one quietly.
What the numbers say
The maker reports 88% fewer tool calls and 62% fewer tokens across seven repos, using Claude Opus 4.8 with the median of four runs per repo. Those are the maker's benchmarks, and results varied: cost dropped 13% on Django and was roughly even on Gin. An independent write-up measured a median 70% drop in tool calls and 59% fewer tokens across four real repos over a week.
The practical question is whether it helps with your codebase. Larger and more connected repos have more relationships for a graph to map.
The catches
- More context in long sessions. Graph results stay in the context window, so long sessions on smaller-window models may fill up faster. Start a fresh session when needed.
- Some files are skipped. The source says files over 1 MB and files in
.gitignoreare not indexed. - Vendor code needs excluding. Otherwise, the graph can fill with code you do not own.
- Telemetry is a choice. The installer asks. Run
codegraph telemetry offto turn it off.
When to skip it
A single script, a weekend prototype, or a repo your agent can read in one pass probably does not need a graph. Consider it once you notice the agent repeatedly grepping for the same connections.
Do this next
Pick one question about your repo, such as “How does auth work?” Ask it in a session before and after installing CodeGraph, then compare the calls and files needed. That is your own benchmark.