CodeGraph Usage Guide

02. Install the CLI and Connect an Agent

The complete setup has three parts: install the CLI, connect an agent, and initialize a project. Installing the CLI alone does not configure MCP, and running codegraph install alone does not build a graph for a project.

# Install the CodeGraph CLI globally with npm
npm i -g @colbymchenry/codegraph

# One-shot alternative: download and run the interactive installer
npx @colbymchenry/codegraph

If Node.js is unavailable, use the standalone installer for Windows, macOS, or Linux from the official Installation page. The standalone installer adds codegraph to PATH but does not refresh the current terminal. Open a new terminal before running the next commands.

# Connect CodeGraph to detected agents
codegraph install

# Confirm that the CLI resolves in the new terminal
codegraph version

The installer can detect Codex CLI, Claude Code, Cursor, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro. Restart the agent after configuration so the MCP server loads in a new session.

03. Initialize a Project and Run the First Query

Run codegraph init inside the target repository. This command creates the project index and performs the first full graph build in one step, so a separate codegraph index command is unnecessary.

# Enter the project that should be indexed
cd your-project

# Create .codegraph/ and build the first full graph
codegraph init

# Verify file, node, edge, SQLite, and journal statistics
codegraph status

codegraph status should report file, node, and edge counts along with the SQLite backend and journal mode. If it reports that the project is not initialized, the current directory is usually wrong or codegraph init has not been run for that project.

For the first structural query, start with the natural-language codegraph explore entry point. It combines relevant source, relationship maps, and impact context in one result.

# Ask a natural-language architecture question
codegraph explore "how does login work"

# Find a class by name
codegraph query UserService --kind class --limit 10

# Inspect both directions of a call relationship
codegraph callers handleRequest
codegraph callees handleRequest

04. Use CodeGraph in Codex and Other Agents

When an agent starts a project session, it launches codegraph serve --mcp automatically. You generally do not start the MCP server by hand. The default codegraph_explore tool becomes available to the agent when the project contains a .codegraph/ index.

You can ask an agent questions such as:

• “Which functions does a login request pass through from the route to the database?”
• “Before changing AuthMiddleware, list callers, downstream calls, and tests that may be affected.”
• “Explain the relationship between UserService and the cache layer, with source locations.”

Including file names, symbol names, and the target flow usually produces more stable results. If a workspace contains several indexed projects, the agent can query another index through projectPath. A path without an index falls back to the agent’s built-in search tools.

05. Check Impact Before Changing Code

codegraph impact traces dependencies outward from a target symbol. codegraph affected starts from changed files and follows import dependencies to find tests that may be affected. Together they provide a workflow for checking impact before a change and selecting tests afterward.

# Inspect the blast radius of a symbol
codegraph impact AuthMiddleware --depth 3

# Find tests affected by one changed source file
codegraph affected src/auth.ts

# Feed the current Git diff into affected-test discovery
git diff --name-only | codegraph affected --stdin

# Produce machine-readable impact data for a script
codegraph impact AuthMiddleware --depth 3 --json

affected traverses up to five dependency levels by default. It also supports a custom test-file glob and path-only output. It can narrow the test set, but it does not replace a complete test strategy.

A static dependency graph cannot cover every runtime relationship. Reflection, runtime dependency injection, dynamic string routes, and external service contracts still require integration tests, logs, or human review.

06. Keep the Index Fresh

The MCP server starts a file watcher by default. After a source file is created, changed, or deleted, CodeGraph coalesces nearby writes and updates the graph incrementally. A normal agent session does not require repeated manual codegraph sync commands.

# Check index health and statistics
codegraph status

# Manually apply changed files when the watcher is unavailable
codegraph sync

# Rebuild the complete graph when configuration or mappings changed
codegraph index --force

# Remove a confirmed stale indexing lock
codegraph unlock

If an agent has just edited a file, query results identify pending files during the brief synchronization window. When a staleness notice appears, the agent should read that file directly or wait for incremental synchronization before querying again.

07. Control Index Scope and Local Data

The index scope is determined by supported file extensions, default exclusions, and .gitignore. Dependency and build directories such as node_modules, vendor, dist, build, and .next are excluded by default. Files larger than 1 MB are also skipped.

Use codegraph.json in the project root for committed directories that should not be indexed. The same file can map non-standard extensions to supported languages.

{
  "exclude": ["static/", "**/vendor/**"],
  "include": ["Tools/", "Local/typescript/"],
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

Run codegraph index --force after changing codegraph.json so the new scope and extension mappings take full effect. exclude takes precedence over include, and built-in exclusions cannot be re-enabled through include.

The official documentation states that source code, paths, symbol names, and query contents are not included in anonymous telemetry. If organizational policy requires usage statistics to be disabled completely, run:

# Disable anonymous usage telemetry
codegraph telemetry off

08. Troubleshoot and Remove CodeGraph

When troubleshooting CodeGraph, check codegraph status before diagnosing connection, lock, or scope problems. Do not keep serve --mcp running manually when MCP fails to connect; supported agents launch the service themselves.

# Check whether an upgrade is available
codegraph upgrade --check

# Upgrade the current installation
codegraph upgrade

# Remove only this project's .codegraph/ index
codegraph uninit

# Remove agent configurations but keep the CLI
codegraph uninstall --keep-cli

# Remove configured integrations and the CLI
codegraph uninstall