Installing CodeGraph: a basic guide

Goal

By the end you'll have CodeGraph installed, connected to your coding agent through MCP, and your first project indexed, so the agent can answer structural questions ("what calls this?", "what breaks if I change it?") from a graph instead of grepping around.

CodeGraph is a local code knowledge graph. It parses your repository, stores symbols and their relationships in a SQLite database inside the project (.codegraph/), and exposes them to agents through an MCP server and a CLI. Everything runs on your machine.

Prerequisites

• macOS, Linux, or Windows.
• Node.js (a current LTS) and npm. The project also documents installer scripts for machines without Node; check the official docs.
• A coding agent that supports MCP. This guide uses Claude Code. codegraph install also lists Cursor, Codex CLI, opencode, Gemini CLI, Antigravity IDE, Kiro, GitHub Copilot, and Hermes Agent as targets.
• A local project (ideally a git repository) to index.

This guide covers CodeGraph v1.6 as of October 2026.

Steps

1. Install the CLI

npm install -g @colbymchenry/codegraph

Open a new terminal afterwards so the codegraph command resolves.

2. Verify the install

codegraph --version

Expected check: it prints a version number.

3. Connect it to your agent

codegraph install

It asks which agents to configure and whether to install globally or locally. For an unattended setup:

codegraph install --yes          # auto-detect agents, install globally
codegraph install --yes --init   # same, then index the current project

For Claude Code, the installer also asks whether to front-load CodeGraph on "how / where / trace" prompts. This adds a hook: when you ask a structural question, CodeGraph injects the relevant source and call paths into the prompt up front, so the agent needs fewer steps. It adds a moment of latency to those prompts. Answering yes is a good default; you can turn it off later (see Troubleshooting).

4. Index your project

From the root of the repository:

cd path/to/your/project
codegraph init

This creates the .codegraph/ directory and builds the initial index. The index can be large on big repos, so add .codegraph/ to your .gitignore: each person indexes their own copy.

5. Check the index

codegraph status

Expected check: non-zero counts of files, nodes, and edges, plus a breakdown of nodes by kind (functions, methods, classes, routes...).

6. Try a query from the CLI

codegraph explore "login authentication"
codegraph callers authenticate
codegraph impact authenticate

CodeGraph has no AI inside: it searches by keywords against symbol names, signatures, and docstrings, then walks the graph. Use terms that actually appear in your code (usually English). A query like "how does login work" works because login is in the code; "inicio de sesión" would not match a login function.

7. Ask your agent a structural question

Open your agent in the project and ask something like "how do reservations work?". The agent should call CodeGraph (codegraph_explore) and answer with source code, call paths, and a blast-radius summary in one step. The agent is the part that turns your natural language into good keywords.

Expected result

• codegraph --version prints a version.
• codegraph status shows a populated index for your project.
• codegraph explore "<keywords>" returns symbols, source, and call paths.
• Your agent uses CodeGraph when you ask structural questions.

Troubleshooting

Next step

Learn how to keep the index fresh as your code changes.