CodeGraph: Open‑Source AI Tool for One‑Click Project Insight—Essential for Large Codebases

Introduction

When an AI agent needs to understand code, the traditional workflow requires retrieving, traversing, and reading files one by one, manually reconstructing call chains and dependencies. This generates many tool calls before the core work can start.

CodeGraph pre‑builds a knowledge graph that records every symbol, call relationship, and dependency in a codebase. A single query can return the relevant source, the complete call chain (including dynamic dispatch that ordinary search tools miss), and the impact range of code changes.

Core Features

Precise directed context – one tool call returns entry functions, related symbols, and code snippets without per‑file traversal.

Full‑text search – implemented with SQLite FTS5 for instant name‑based search across the entire codebase.

Impact analysis – tracks callers and callees of any symbol to analyze the ripple effect of modifications.

Real‑time synchronization – a file monitor uses native OS events (FSEvents, inotify, ReadDirectoryChangesW) with a 2‑second debounce to keep the graph up‑to‑date automatically.

Multi‑language support – recognizes more than 20 languages, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Objective‑C, Swift, Kotlin, Scala, Dart, Lua, Luau, R, Svelte, Vue, Astro, Liquid, Pascal/Delphi.

Framework route recognition – detects routes for 17 web frameworks, establishing URL‑to‑handler mappings.

Hybrid development support – completes cross‑language call chains such as Swift ↔ Objective‑C bridges, React Native bridges, Turbo modules, native‑to‑JS events, and Expo modules.

Fully local operation – all data stays on the local machine in a SQLite database; no API keys or external services are required.

Routing Recognition

Django : path(), re_path(), url(), include() in urls.py (CBV .as_view(), dotted paths).

Flask : @app.route('/path', methods=[...]) and blueprint routes.

FastAPI : request method decorators such as @app.get(...), @router.post(...).

Express : app.get(...), router.post(...), including middleware chains.

NestJS : @Controller with @Get/@Post, GraphQL @Resolver/@Query/@Mutation, message patterns, etc.

Laravel : Route::get(), Route::resource(), controller@method, tuple syntax.

Drupal : *.routing.yml files and various hook implementations.

Rails : get '/path', to: 'controller#action' syntax.

Spring : @GetMapping, @PostMapping, @RequestMapping annotations.

Play : conf/routes with GET/POST linking to Scala or Java controllers.

Gin / chi / gorilla/mux : r.GET(...), router.HandleFunc(...).

Axum / actix / Rocket : .route("/path", get(handler)).

ASP.NET : [HttpGet("/path")] attribute on methods.

Vapor : app.get("path", use: handler).

React Router / SvelteKit : route component nodes.

Vue Router / Nuxt : file‑based routes under pages/, server/api/, and route middleware.

Astro : file‑based routes in src/pages/ with dynamic syntax.

Practical Example

Installation

npm install -g @colbymchenry/codegraph

Index Creation

Navigate to the project directory and run the initialization command. CodeGraph scans all files, uses Tree‑Sitter to parse the code structure, and creates a local SQLite graph database.

codegraph init -i

AI Agent Integration

After the index is built, run the MCP bridge installer to connect CodeGraph with AI code assistants (e.g., Claude Code, Cursor). The agent can query the graph directly, avoiding costly file‑traversal.

codegraph install

Working Principle

Extraction phase : Tree‑Sitter parses source files into abstract syntax trees; language‑specific queries extract nodes (functions, classes, methods) and edges (calls, imports, inheritance).

Storage phase : All extracted data is stored in a local SQLite database ( .codegraph/codegraph.db) with built‑in FTS5 full‑text search.

Association phase : After extraction, references are resolved—function calls link to definitions, import statements to source files, class inheritance, and framework‑specific patterns.

Automatic sync : MCP runs a file‑system watcher that reacts to native events, applies a 2‑second debounce, and incrementally updates the graph without extra configuration.

CLI Reference

codegraph                 # Run interactive installer</code>
<code>codegraph install        # Execute installer explicitly</code>
<code>codegraph uninstall      # Remove CodeGraph from the agent</code>
<code>codegraph init [path]    # Initialize project and build graph</code>
<code>codegraph uninit [path]  # Remove graph (use --force to skip prompts)</code>
<code>codegraph index [path]   # Full re‑index (use --force, --quiet)</code>
<code>codegraph sync [path]    # Incremental update</code>
<code>codegraph status [path]  # Show statistics</code>
<code>codegraph unlock [path]  # Delete stale lock files</code>
<code>codegraph query <search>  # Search symbols (supports --kind, --limit, --json)</code>
<code>codegraph explore <query> # Return associated source and call chain (same format as MCP tool)</code>
<code>codegraph node <symbol|file> # View source of a symbol or file with line numbers</code>
<code>codegraph files [path]   # Show file tree (supports --format, --filter, --max-depth, --json)</code>
<code>codegraph callers <symbol> # Find callers of a function/method</code>
<code>codegraph callees <symbol> # Find callees of a function/method</code>
<code>codegraph impact <symbol>  # Analyze all code affected by modifying the symbol</code>
<code>codegraph affected [files...] # Identify tests impacted by code changes</code>
<code>codegraph daemon          # Manage background daemon process</code>
<code>codegraph telemetry on|off # Toggle anonymous usage data collection</code>
<code>codegraph upgrade [version] # Upgrade to latest version (use --check, --force)</code>
<code>codegraph version          # Show installed version</code>
<code>codegraph help [command]   # Show help for a specific command

MCP Tool

When run as an MCP server, CodeGraph exposes a single tool codegraph_explore. One call can answer most code questions—e.g., implementation logic of a symbol, business flow from X to Y, or module research. The tool returns grouped source files, full call chains, and impact analysis, including dynamic dispatch that grep cannot track. Queries specify a file or symbol name to obtain line‑numbered source and JSON‑formatted results consistent with the Read tool.