Skip to content
Get packs

Guide · Open source

How to use CodeGraph: install, connect agents and index a project

Updated · written with AI from the project's own documentation and checked against our catalogue data

CodeGraph is an open-source command-line tool that builds a pre-indexed map of a software project's code, including functions, classes and how files reference each other, and keeps that map updated as files change. It connects to AI coding agents such as Claude Code, Cursor, Codex and GitHub Copilot through MCP, so the agent can look up code relationships instead of reading many files. This guide shows how to install it, connect your agents, index a project and check that it is working.

CodeGraphcolbymchenry/codegraph · ★ 76.2k · MIT

Quick start

  1. 1Install the CLI. Run the curl command on macOS or Linux, or the PowerShell command on Windows. Open a new terminal afterward.
  2. 2Connect your agents. Run codegraph install to wire the CodeGraph MCP server into the supported agents you use.
  3. 3Go to your project. Change into the root folder of the codebase you want the agent to explore.
  4. 4Build the graph. Run codegraph init, which creates the .codegraph/ directory and builds the full graph.
  5. 5Work as usual. Keep editing with your agent. Auto-sync updates the graph when files change.
  6. 6Upgrade or remove when needed. Use codegraph upgrade to update, or codegraph uninstall to remove the agent configurations and CLI.

Install the CodeGraph CLI on macOS, Linux or Windows

Run the one-line installer for your operating system. The README says no Node.js is required because CodeGraph bundles its own runtime. The installer puts the codegraph command on your PATH but does not change your current shell, so open a new terminal before the next step.

  • macOS or Linux: use the curl command shown in the code block.
  • Windows: use the PowerShell command shown in the code block.
  • If you already have Node, the README lists an npm alternative: npm i -g @colbymchenry/codegraph.
# macOS / Linux curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh # Windows (PowerShell) irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Connect CodeGraph to your AI agents

Installing the CLI does not connect it to your agent on its own. Run codegraph install in a new terminal to detect and configure supported agents. According to the README, it wires the CodeGraph MCP server into each one. It does not index any code.

The README lists the agents it can detect: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot (VS Code, Copilot CLI, JetBrains IDEs).

  • Run codegraph install after the CLI is on your PATH.
  • Restart or reopen your agent if it was already running (general practice; the README does not specify this).
codegraph install

Index a project with codegraph init

Go to the root of the project you want to work on and run codegraph init. The README says it creates a local .codegraph/ directory and builds the full graph in the same step.

Repeat this for each project. The graph is built per project, not once for your whole machine.

cd your-project codegraph init

Understand automatic syncing

Auto-sync is enabled by default. CodeGraph watches the project and updates the graph whenever a file changes, including when your agent edits code or when you add, modify or delete files. The README states that you do not need to re-run anything to keep the index current.

  • Auto-sync is on by default; the README does not describe a setting to turn it off.

Update, check and uninstall CodeGraph

To update, run codegraph upgrade. Add --check to see whether an update is available, or pass a version number to pin one. The README says upgrade detects how you installed CodeGraph and updates in place.

To remove CodeGraph, run codegraph uninstall. It removes the MCP configuration from each agent and the CLI itself, showing you every install it finds before deleting anything. Use --keep-cli to remove only the agent configurations. Your project indexes in .codegraph/ are left untouched; remove those per project with codegraph uninit.

  • codegraph upgrade --check: see if an update exists.
  • codegraph uninstall --keep-cli: remove agent configs but keep the CLI.
  • codegraph uninit: remove a project's .codegraph/ index.
  • codegraph uninstall --yes: run without prompts.
codegraph upgrade codegraph upgrade --check codegraph uninstall codegraph uninstall --keep-cli

Check which languages and platforms are supported

The README lists supported languages in a Language Support section, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++ and Objective-C, and says each receives the same structural extraction and cross-file resolution. The README also has sections on supported platforms and agents. Check the full list there before you rely on CodeGraph for a project in a language not named in the README.

  • The README's Supported Languages section is the authoritative list.
  • Mixed-language projects are covered only for the languages listed.

What people use it for

  • Letting Claude Code or Cursor look up how functions and files reference each other in a medium or large existing codebase.
  • Sharing one local code index across several AI agents, such as Codex and GitHub Copilot, on the same machine.
  • Working on a mixed-language project whose languages are all on the README's supported list.
  • Keeping code indexing on local machines for a team that does not want code sent to a hosted service.

Frequently asked questions

Is CodeGraph free to use?

CodeGraph is released under the MIT licence, according to the README and its badge. The README also mentions a hosted platform that is a waitlist beta, which is separate from the local tool.

Do I need Node.js to install CodeGraph?

No. The README says the curl and PowerShell installers bundle their own runtime, so Node.js is not required. If you already use Node, you can install with npm instead.

Does CodeGraph send my code to the cloud?

The README says CodeGraph runs 100% locally and builds its index in a local .codegraph/ directory. It also has a Telemetry section, which you should read before deciding how it fits your privacy needs.

Which AI agents does CodeGraph work with?

The README lists Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot. Running codegraph install connects the MCP server to the ones it detects.

Why doesn't my agent see the code graph after installing?

Installing the CLI alone does not connect your agent. Run codegraph install in a new terminal, then run codegraph init inside each project. The README says the installer does not index code by itself.

How does CodeGraph compare to other code indexing tools?

The source does not name any comparable projects, so this guide cannot make a comparison. The README says CodeGraph reduces token use and tool calls, but it gives no benchmark numbers that you can check here.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

CodeGraph suits developers and teams who use supported AI coding agents on medium or large existing codebases and want the index kept on their own machines. It is a poor fit for languages outside the README's supported list, for anyone who needs the hosted service (still a waitlist beta), or for small scripts where a full code graph adds little.

Install options & downloads