colbymchenry/codegraph

This document details CodeGraph, a tool designed to significantly enhance the performance and capabilities of AI code assistants like Claude Code. Here's a breakdown of its key features, functionality, and usage:

Core Purpose:

CodeGraph creates a local, searchable knowledge graph of your codebase. This allows Claude Code (via the MCP server) to understand your project's structure, dependencies, and semantics much faster and more accurately than relying on simple text searches (grep/glob/read). This leads to better code completion, bug fixes, refactoring suggestions, and overall AI-assisted development.

Key Features:

Code Understanding: Parses code using Tree-sitter to create an Abstract Syntax Tree (AST), extracting symbols (functions, classes, methods, etc.) and relationships (calls, imports, inheritance). Local SQLite Database: Stores the extracted information in a fast, local SQLite database with full-text search (FTS5). Incremental Updates: Automatically syncs with your project as you make changes, keeping the knowledge graph up-to-date. Uses native OS file events for efficient monitoring. MCP Server: Provides a server that Claude Code can query to access the knowledge graph. Exposes a set of tools for searching, context building, and code analysis. Configuration: Allows customization of indexing behavior (languages, exclusions, file size limits, etc.) via a `config.json` file. CLI Tool: Offers a command-line interface for initialization, indexing, querying, and management. Affected Files Detection: Can identify test files impacted by code changes, useful for CI/CD pipelines. Library Usage: Provides a JavaScript API for directly interacting with the CodeGraph database.

How it Works (Simplified):

1. Extraction: CodeGraph parses your source code. 2.

Storage: The parsed information (symbols & relationships) is stored in a local SQLite database. 3. Resolution: References are resolved (e.g., function calls are linked to their definitions). 4.

Auto-Sync: The database automatically updates when you save code changes. 5. Claude Integration: Claude Code queries the MCP server, which in turn queries the local database to provide fast, accurate information.

Tools Exposed to Claude Code (via MCP Server):

`codegraph_search`: Finds symbols by name. `codegraph_context`: Builds relevant code context for a task. `codegraph_callers`: Finds functions that call a given function. `codegraph_callees`: Finds functions called by a given function. `codegraph_impact`: Analyzes the impact of changing a symbol. `codegraph_node`: Gets details about a specific symbol. `codegraph_files`: Gets the project's file structure. `codegraph_status`: Checks the index health and statistics.

CLI Commands (Commonly Used):

`codegraph init [path]`: Initializes CodeGraph in a project. `codegraph index [path]`: Indexes a project. `codegraph sync [path]`: Updates the index with recent changes. `codegraph status [path]`: Shows index statistics. `codegraph serve --mcp`: Starts the MCP server. `codegraph affected [files...]`: Finds affected test files.

Installation & Setup:

1. Install: `npm install -g @colbymchenry/codegraph` 2.

Initialize: `codegraph init` (in your project directory) 3. Index: `codegraph index` 4.

Start MCP Server: `codegraph serve --mcp` 5. Configure Claude Code: Point Claude Code to the running MCP server.

Troubleshooting:

Slow Indexing: Exclude `node_modules` and other large directories in `config.json`. Database Locked: Ensure `better-sqlite3` is installed correctly. If not, CodeGraph falls back to a slower WASM-based SQLite engine. * MCP Server Not Connecting: Verify the project is initialized, indexed, and the path is correct.

Benefits of Using CodeGraph:

Faster Performance: Significantly speeds up AI-assisted coding tasks. Improved Accuracy: Provides more accurate code completion and suggestions. Deeper Understanding: Enables Claude Code to understand your project's structure and semantics. Enhanced Productivity: Helps you write and maintain code more efficiently.

In essence, CodeGraph transforms Claude Code from a text-based assistant into a code-aware AI, enabling a more intelligent and productive development experience.