Supercharge Claude Code with CodeGraph

Cut Claude Code token usage 89% with a pre-indexed code knowledge graph.

Introduction

30 Second Summary

Every time you ask an AI coding assistant about your project's architecture, it starts from scratch. It greps through files, reads them one by one, and burns through tokens reconstructing knowledge it already had five minutes ago.

In this project, you will install CodeGraph and wire it into Claude Code as an MCP server, then run a controlled before-and-after comparison on a real open-source codebase to see how a pre-indexed knowledge graph eliminates this exploration overhead.

What You'll Build

You'll ask Claude Code a structural question about a 640-file TypeScript project, watch it answer instantly from a pre-built knowledge graph, and query the graph yourself from the command line for zero-cost code intelligence.

By the end of this project, you'll have:

A pre-indexed knowledge graph of the Excalidraw codebase that Claude Code queries instantly instead of scanning files one by one.
A measured before-and-after comparison showing dramatically fewer tool calls, tokens, and response time on the exact same question.
CLI-powered code intelligence queries (caller tracing, impact analysis, affected tests) that work without consuming any AI tokens.
Secret Mission: A git pre-push hook that automatically identifies which tests are affected by your changes.

Are there any prerequisites?

You need Claude Code installed and working, plus Git installed on your machine. No Node.js is required.

Before We Start

Before We Start...

Before we dive in, let's lock in what you're about to build and why it matters for your coding workflow.

Set Up CodeGraph and Clone Excalidraw

Claude Code has no persistent memory of your codebase structure. Every time you ask an architectural question, it rebuilds its understanding by reading files one by one from scratch.

In this step, you'll install the CodeGraph CLI and clone a real codebase. This gives you everything you need to experience the exploration problem firsthand in the next step.

In this step, get ready to:

Install the CodeGraph CLI on your machine.
Clone the Excalidraw open-source repository.
Verify both are working correctly.

Install the CodeGraph CLI

CodeGraph is a standalone CLI that builds a local knowledge graph of your code. The standalone installer bundles its own runtime, so you don't need Node.js installed.

Install CodeGraph by running this command:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

What does this command do?

This downloads the CodeGraph installer script and pipes it directly to your shell. The -fsSL flags tell curl to fail silently on HTTP errors, suppress progress bars, show errors if they occur, and follow redirects.

The installer detects your operating system and downloads the correct pre-built binary. No compilation or package manager needed.

Open a new terminal window after the installation finishes.
Press Cmd+N (macOS) or open a new terminal window from the Start menu (Windows). The installer adds codegraph to your PATH but doesn't update your current shell session.

Installation failed or permission denied?

If you see a permission error, make sure you're not running the command with sudo. The installer writes to a user-local directory.
If curl can't reach the URL, check your internet connection and try again.
help me troubleshoot my CodeGraph installation

Clone the Excalidraw repository

Excalidraw is a ~640-file TypeScript project used in CodeGraph's own benchmarks. It's large enough to show the exploration problem clearly.

Move to your Desktop by running this command:

cd ~/Desktop

Clone the Excalidraw repository and move into it by running these commands:

git clone --depth 1 https://github.com/excalidraw/excalidraw.git
cd excalidraw

What do these commands do?

The --depth 1 flag creates a shallow clone with only the latest commit. This is faster and saves disk space since you don't need the full Git history for indexing.

After cloning, cd excalidraw moves you into the cloned repository so all future commands run from inside it.

Confirm the files are present by running:

ls

You should see folders like packages/ and files like package.json and tsconfig.json in the output.

Clone failed or directory not found?

If git clone fails with a network error, check your internet connection and try again.
If you see fatal: destination path 'excalidraw' already exists, you already have a copy. Run rm -rf excalidraw and try the clone again.
help me troubleshoot cloning the Excalidraw repository

Verify your setup

Before you run the next command, what do you think will happen? Will your new terminal recognize codegraph as a command?

Check your CodeGraph version by running:

codegraph version

✔️ I see v1.5.0 or later

CodeGraph is installed and ready. You're all set for the next step.

ⓧ I see an older version

You have an older version of CodeGraph installed. Upgrade it by running:

codegraph upgrade

Run codegraph version again to confirm you now see v1.5.0 or later.

ⓧ Command not found

Your shell doesn't know where codegraph lives yet. Make sure you opened a brand new terminal window after running the installer.

Close your current terminal completely.
Open a fresh terminal window.
Navigate back to the Excalidraw directory by running:

cd ~/Desktop/excalidraw

Try codegraph version again. If it still fails, re-run the installer from the first substep.

Confirm you're in the right directory by running:

pwd

You should see a path ending in /excalidraw. You're inside the repository and ready to go.

Your tools are in place. Next up, you'll ask Claude Code an architectural question and watch it struggle without a knowledge graph.

Experience the Exploration Tax

Your tools are ready. CodeGraph is installed and the Excalidraw codebase is cloned. Now it's time to see what happens when Claude Code tackles a large codebase without any help.

Claude Code has no memory of your codebase between sessions. Every time you ask a structural question, it must scan files from scratch, reading them one by one until it pieces together an answer. Let's experience this exploration cost firsthand.

In this step, get ready to:

Open Claude Code inside the Excalidraw directory.
Ask an architectural question and watch Claude scan files one by one.
Record the session metrics as a baseline for comparison.

Launch Claude Code

Start a Claude Code session inside the excalidraw directory by running this command:

claude

You should see the Claude Code interactive prompt appear, ready for input.

Don't see the Claude Code prompt?

Make sure you have Claude Code installed. Run claude --version in a regular terminal to check.

If it shows command not found, Claude Code is not installed. Visit the Claude Code documentation to install it before continuing.

help me install Claude Code so I can continue this project

Ask an architectural question

You're about to ask Claude Code a structural question about how Excalidraw works internally. This is the exact query used in CodeGraph's published benchmarks, so your results will be directly comparable.

Before you send it, think: how many tool calls do you think Claude will need to answer a question about code architecture in a 640-file TypeScript project?

Type this question into your Claude Code session and press Enter:

How does Excalidraw render and update canvas elements?

Watch what happens next. Claude spawns Explore agents that use grep, glob, and Read calls to crawl through dozens of files, piecing together the answer from scratch.

This takes a while. Let it finish completely before moving on.

What is happening right now?

Claude Code has no index of the codebase. It literally cannot answer your question without opening files and reading them.

Each tool call you see ticking up is a separate file operation. A grep to find a keyword, a Read to pull in a file's contents, a glob to discover which files even exist. This is the exploration tax you pay every single session.

Record your baseline metrics

Claude Code just finished answering. Before you look at the totals, take a guess: how many tool calls do you think it made?

Check your session metrics by typing this command inside Claude Code:

/cost

You should see a summary showing total tool calls (likely 20 or more), tokens consumed, and elapsed time.

Write down these three numbers somewhere you can find them later:

Total tool calls.
Tokens consumed.
Wall-clock time elapsed.

Why record these numbers?

In a later step, you'll ask the exact same question with CodeGraph enabled. The difference between these two sets of numbers is the entire point of this project.

Exit your Claude Code session by typing:

/exit

You're back in your regular terminal, still inside the excalidraw directory.

Can't find the metrics?

If /cost does not show tool call counts, look at the end of Claude's response output. Claude Code displays a summary line after each response showing the number of tool calls and tokens used.

If you accidentally closed the session before noting the numbers, that's fine. Open a new session with claude, ask the same question again, and record the metrics when it finishes.

help me find my Claude Code session metrics

That's the exploration tax. Every structural question costs dozens of tool calls, thousands of tokens, and noticeable wait time. Next up, you'll build a knowledge graph that eliminates it entirely.

Build the Knowledge Graph

In the last step, you watched Claude Code burn through dozens of tool calls and thousands of tokens just to answer a single architectural question about Excalidraw.

Now you will build a pre-indexed knowledge graph of every symbol, call edge, and dependency in the codebase. Once built, Claude can query the graph instantly instead of reconstructing the structure from scratch.

In this step, get ready to:

Wire CodeGraph into Claude Code as an MCP server.
Index the entire Excalidraw codebase into a knowledge graph.
Verify the graph is ready for queries.

Wire CodeGraph into Claude Code

CodeGraph works as an MCP server that gives Claude Code direct access to the pre-built graph. The first step is wiring them together so Claude Code knows where to find the graph data.

The installer is interactive. It will show a multi-select prompt asking which agents to configure. Make sure Claude Code is selected (it should be pre-selected if detected on your machine).
It will also ask whether configs should apply to all your projects or just the current one. Choose the global option (all projects).
Connect CodeGraph to Claude Code by running this command:

codegraph install

What does this command do?

The installer detects Claude Code on your machine and writes two pieces of configuration:

An MCP server entry in ~/.claude.json that tells Claude Code how to launch the CodeGraph server.
Auto-allow permissions in ~/.claude/settings.json so CodeGraph tools work without prompting for approval every time.

After the installer finishes, you should see a confirmation message that Claude Code was configured successfully.

Installer not detecting Claude Code?

Make sure Claude Code is installed on your machine. The installer looks for it in standard locations.
If Claude Code appears as "(not found)" in the multi-select list, you can still select it manually. The config will be written and will work once Claude Code is available.
help me troubleshoot why codegraph install is not detecting Claude Code on my machine

Index the Excalidraw codebase

With the MCP connection in place, you can now build the actual knowledge graph. This is the step that transforms raw source files into a queryable structure of symbols and relationships.

Make sure you are still inside the excalidraw directory. Confirm with pwd if you are unsure.
Build the knowledge graph for the Excalidraw codebase by running:

codegraph init

Watch the progress output as it indexes 600+ files in seconds.

What does this command do?

This parses every source file using tree-sitter (a fast, incremental parser). It extracts functions, classes, methods, imports, and call relationships from across the entire codebase.

Everything is stored in a local SQLite database at .codegraph/codegraph.db. No data leaves your machine.

You did not need to install Excalidraw's dependencies or run any build step. CodeGraph indexes source files directly using static analysis.

Confirm the .codegraph/ directory was created by running:

ls .codegraph/

You should see codegraph.db listed in the output.

Not seeing a .codegraph directory?

Make sure you ran codegraph init from inside the excalidraw folder, not from a parent directory.
Check that codegraph init completed without errors. If it printed an error about missing permissions, try running it again.
help me figure out why codegraph init did not create the .codegraph directory

Verify the index

Before you run the next command, how many symbols (functions, classes, methods) do you think CodeGraph extracted from a 640-file TypeScript project?

Check the graph statistics by running:

codegraph status

You should see output showing the number of indexed files (600+), nodes (thousands of symbols), and edges (relationships between them).

What do these numbers mean?

Files: the number of source files CodeGraph parsed. For Excalidraw, this should be 600+.
Nodes: every function, class, method, and exported symbol extracted. These are the things Claude can look up instantly.
Edges: the call relationships, imports, and dependencies between nodes. These let Claude trace how code flows through the project without reading files.

Seeing 0 files or an error?

Run pwd and confirm you are inside the excalidraw directory (not inside a subdirectory like excalidraw/packages).
If codegraph status says no index found, run codegraph init again from the project root.
help me troubleshoot why codegraph status shows 0 files or an error

Your knowledge graph is built and ready. Next up, you will ask Claude Code the exact same question from Step 2 and see the difference firsthand.

See the Payoff

Your knowledge graph is built. Every function, class, import, and call relationship in the Excalidraw codebase is indexed in a local SQLite database, ready to answer structural questions instantly.

Now you will ask Claude Code the exact same question from Step 2 and see it answer from the graph instead of scanning files. The difference in tool calls, tokens, and speed is the entire point of this project.

In this step, get ready to:

Start a fresh Claude Code session with the knowledge graph active.
Ask the same architectural question and watch Claude query the graph.
Compare metrics against your Step 2 baseline.

Start a fresh Claude Code session

Claude Code needs a brand-new session so it starts with a clean context. When it detects the .codegraph/ directory in the project, it connects to the CodeGraph MCP server automatically.

Launch a fresh Claude Code session by running this command:

claude

Claude Code starts up and connects to the CodeGraph MCP server. You may see a brief message about MCP tools being available.

Claude Code not detecting CodeGraph?

Confirm you are inside the excalidraw directory by running pwd. The .codegraph/ folder must exist in the current working directory.

If Claude Code still does not use CodeGraph tools, try prompting it with "use codegraph tools before exploring files" to nudge the behaviour.

Help me troubleshoot Claude Code not detecting my CodeGraph MCP server.

Ask the same architectural question

In Step 2, Claude burned through 20+ tool calls, reading file after file to piece together an answer. Before you ask the question again, think about what you expect to happen now that the knowledge graph exists.

Do you think Claude will still open dozens of files? Or will it find the answer a different way?

Type the exact same question into your Claude Code session:

How does Excalidraw render and update canvas elements?

Watch what happens this time. Instead of spawning Explore agents that grep through files, Claude makes a single codegraph_explore call that returns the relevant symbols, source code, and call paths from the pre-built index.

What just happened?

Claude Code queried the knowledge graph through the codegraph_explore MCP tool. The graph already knows which symbols relate to rendering and canvas updates, so it returned the answer directly.

No file scanning. No grepping through 640 files. The pre-indexed graph eliminated the entire exploration step.

Compare the metrics against your baseline

Now for the numbers. You recorded tool calls, token usage, and elapsed time in Step 2. Time to see how this session stacks up.

Check the session summary by typing /cost in your Claude Code session.
Compare these three values against your Step 2 notes:

Tool calls: should drop from 20+ to 1-3.
Tokens consumed: significant reduction (benchmarks show 89% fewer tokens).
Response time: noticeably faster.

The graph answered the question directly. No file scanning. No exploration tax.

Why is this such a big difference?

Without the graph, Claude Code has no memory of your codebase between sessions. Every structural question triggers a fresh scan from scratch. With the graph, the answer is pre-computed and waiting.

CodeGraph's published benchmarks on this exact Excalidraw query show 3 vs 55 tool calls, 0 vs 24 file reads, and 78% lower cost. Your results may vary, but the pattern holds.

Exit your Claude Code session by typing /exit.

Metrics look similar to Step 2?

If Claude Code still used many file reads, it may not have connected to the CodeGraph MCP server. Run codegraph status to confirm the graph exists, then start a new session and prompt Claude with "use codegraph tools to answer this" before asking the question.

Help me figure out why Claude Code is not using my CodeGraph knowledge graph.

You have hard evidence now. The knowledge graph transforms Claude Code from a file-by-file explorer into a tool that answers instantly from pre-indexed structure. Next up, you will use CodeGraph's CLI to query the graph directly for caller tracing and impact analysis, with zero AI tokens spent.

Query Code Intelligence from the CLI

You just proved that a pre-indexed knowledge graph transforms Claude Code's exploration efficiency. Tool calls dropped from 20+ to 1-3, tokens plummeted, and the answer arrived faster.

CodeGraph is not just an MCP server for Claude Code. Its CLI lets you query the knowledge graph directly for caller tracing, impact analysis, and affected test detection. These queries hit the local SQLite index and consume zero AI tokens.

In this step, get ready to:

Search for symbols and trace their callers from the command line.
Run impact analysis to see the blast radius of a code change.

Search for a symbol by name

The codegraph query command searches the knowledge graph for symbols matching a name. You can find functions, classes, methods, and imports instantly without opening a single file.

Search for the renderScene symbol by running this command:

codegraph query "renderScene"

You should see a list of matching symbols with their file paths and types (function, method, etc.). The graph found them instantly from the index.

Now the interesting question: what calls this function?

Trace everything that calls renderScene by running:

codegraph callers "renderScene"

You should see a list of every function and file that calls renderScene. This is caller tracing, pulled directly from the graph's edge data.

What's the difference between these two commands?

codegraph query finds symbols by name. It answers "where is this thing defined?"

codegraph callers follows the graph edges backward. It answers "what depends on this thing?" Both run against the local index with no network calls or token costs.

Seeing no results?

Make sure you are inside the excalidraw directory (run pwd to confirm). CodeGraph looks for the .codegraph/ directory in your current working directory.

If you see the symbol but no callers, try a different symbol name. The symbol must be called by other code in the repo for codegraph callers to return results.

Why is codegraph query returning no results for renderScene?

Run impact analysis on a symbol

Knowing who calls a function is useful. But the bigger question is: if you changed renderScene, what else in the codebase would break? That's impact analysis.

Before you run the next command, what do you think the blast radius of renderScene looks like? A handful of files, or something much wider?

Run impact analysis on renderScene by running this command:

codegraph impact "renderScene"

You should see a list of every symbol and file that would be affected if you changed renderScene. This is the full blast radius, traced through the graph's dependency edges.

Why does this matter?

This is the same information Claude Code gets when it calls codegraph_explore through the MCP server. The difference is you just got it from the command line at zero token cost.

Impact analysis is invaluable for refactoring. Before you rename a function or change a return type, you can see exactly how far the ripple extends.

Impact output looks empty or too short?

Some symbols have a shallow call graph. If your output seems sparse, the symbol may not be heavily depended upon. Try running codegraph impact "App" for a symbol with a wider reach to see a bigger result set.

Why is my codegraph impact result smaller than expected?

Secret mission

Smart Test Selection with Git Hooks

You have a pre-indexed knowledge graph that knows every dependency relationship in the codebase. What if you could automatically identify which tests are affected by your changes before you push? Wire CodeGraph into a git hook for smart test selection.

Clean Up Your Resources

This project runs entirely locally, so there are no ongoing costs. Decide whether to keep your resources in place, remove CodeGraph from this project only, or delete everything entirely.

Resources you used:

CodeGraph CLI (installed on your machine via standalone installer).
Excalidraw repository clone (local folder containing .codegraph/ database and .git/hooks/pre-push hook).
CodeGraph MCP server configuration (registered in ~/.claude.json).

Keep everything running

No action needed. Choose this if you plan to keep working with Excalidraw or want CodeGraph ready for your next project.

The .codegraph/ directory auto-syncs when files change. The graph stays fresh without any manual intervention.
To add CodeGraph to a different project, run codegraph init inside that project's directory.
The CodeGraph MCP server remains available to Claude Code in every session automatically.

Pause - I'll come back to this later

Remove CodeGraph from this project while keeping the CLI installed for use elsewhere.

Make sure you are inside the excalidraw directory, then run:

codegraph uninit

This deletes the .codegraph/ directory and its database. The CodeGraph CLI and MCP server config remain installed for other projects. You can re-index anytime by running codegraph init again.

Delete - I don't want to use this again

Remove all project resources and uninstall CodeGraph completely.

Navigate out of the Excalidraw directory and delete it:

cd ..
rm -rf excalidraw

On Windows, use rmdir /s /q excalidraw instead.

Uninstall CodeGraph from all configured agents and remove the CLI:

codegraph uninstall

This removes the MCP server entry from ~/.claude.json, removes auto-allow permissions, and deletes the CodeGraph binary from your system.

That's a Wrap!

Nice work! You've supercharged Claude Code with a pre-indexed knowledge graph that eliminates the exploration tax on every future coding session.

You've learned how to:

Wire CodeGraph into Claude Code as an MCP server and run a controlled before-and-after comparison showing 89% fewer tokens and dramatically fewer tool calls on a real codebase.
Build a knowledge graph of a ~640-file TypeScript project in seconds using tree-sitter parsing, giving Claude Code instant access to every symbol, call edge, and dependency.
Query the graph directly from the CLI for caller tracing, impact analysis, and affected test detection at zero token cost.
Secret Mission: Created a git pre-push hook that automatically identifies affected tests using CodeGraph's dependency tracing.

Ready to quiz yourself?