---
name: "codegraph"
description: CodeGraph — 预构建的代码知识图谱 MCP 工具集。为 AI 编程智能体提供语义级代码理解：一次调用获取符号源码、调用链路、影响范围和全文本搜索。支持 35+ 语言、17+ Web 框架路由识别、iOS/RN 跨语言桥接。自动同步文件变更。用于架构理解、代码搜索、变更影响分析、跨文件流程追踪等场景。
---

# CodeGraph

CodeGraph is a pre-indexed code knowledge graph + MCP server. It parses your codebase with tree-sitter (backed by a native Rust kernel), stores every symbol, edge, and file in SQLite (FTS5), and exposes it to AI agents through MCP tools. Auto-syncs on file changes.

**Repo**: <https://github.com/colbymchenry/codegraph>
**Version**: 1.5.0+

---

## Quick Start

### 1. Install CodeGraph CLI

```bash
# Via npm (any platform)
npm i -g @colbymchenry/codegraph

# Or via installer (no Node.js required):
#   macOS/Linux: curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
#   Windows: irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
```

### 2. Wire up your agent

```bash
codegraph install
```

Auto-detects and configures: Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro.

### 3. Initialize a project

```bash
cd your-project
codegraph init
```

Creates `.codegraph/` directory and builds the full knowledge graph.

---

## MCP Tools

CodeGraph exposes the following MCP tools when running as `codegraph serve --mcp`:

### `codegraph_explore` (PRIMARY — call first)

Answer almost any question in one call: "how does X work", a flow ("how does X reach Y"), or surveying an area.

```
Input: {
  query: string          // Symbol names, file names, or natural language
  projectPath?: string   // Path to indexed project (default: cwd)
  maxFiles?: number      // Max files to include
}
Output: Symbols' verbatim source grouped by file + call paths + blast radius
```

### `codegraph_node`

Two modes:
1. **Read a file** — pass `file` (path or basename) without `symbol` → returns line-numbered source (Read-equivalent)
2. **One symbol** — returns location, signature, source, caller/callee trail

```
Input: {
  symbol?: string        // Symbol name (qualified or short)
  file?: string          // File path or basename
  line?: number          // Line number (disambiguation)
  includeCode?: boolean  // Include source code (default: true)
  projectPath?: string
}
```

### `codegraph_search`

Quick symbol search by name. Returns locations only (no code).

```
Input: {
  query: string          // Symbol name to search
  kind?: string          // Filter by node kind (class, function, etc.)
  limit?: number         // Max results
  projectPath?: string
}
```

### `codegraph_callers` / `codegraph_callees`

Find what calls a function / what a function calls.

```
Input: {
  symbol: string         // Symbol name
  limit?: number
  projectPath?: string
}
```

### `codegraph_impact`

List symbols affected by changing a symbol.

```
Input: {
  symbol: string         // Symbol to analyze
  depth?: number         // Traversal depth (default: 2)
  projectPath?: string
}
```

### `codegraph_files`

Show file structure of the indexed project.

```
Input: {
  format?: "tree" | "list"
  filter?: string        // Glob pattern
  maxDepth?: number
  projectPath?: string
}
```

### `codegraph_status`

Check if a project is indexed and see its statistics.

```
Input: {
  projectPath?: string   // If omitted, checks the current project
}
```

---

## CLI Commands

```bash
codegraph                         # Interactive installer
codegraph install                 # Wire up agents
codegraph uninstall               # Remove CodeGraph from agents + CLI
codegraph init [path]             # Initialize + build graph
codegraph uninit [path]           # Remove CodeGraph from project
codegraph index [path]            # Full re-index
codegraph sync [path]             # Incremental sync
codegraph status [path]           # Show index statistics
codegraph unlock [path]           # Remove stale lock file
codegraph query <search>          # Search symbols
codegraph explore <query>         # CLI equivalent of codegraph_explore
codegraph node <symbol|file>      # CLI equivalent of codegraph_node
codegraph callers <symbol>        # Find callers
codegraph callees <symbol>        # Find callees
codegraph impact <symbol>         # Impact analysis
codegraph affected [files...]     # Find affected test files
codegraph daemon                  # Manage background daemons
codegraph upgrade [version]       # Update to latest
codegraph version                 # Print version
codegraph help [command]          # Show help
```

### `codegraph affected`

Trace import dependencies to find which test files are affected by changes:

```bash
codegraph affected src/utils.ts src/api.ts
git diff --name-only | codegraph affected --stdin
codegraph affected src/auth.ts --filter "e2e/*"
```

---

## Configuration

Zero-config by default. Optional `codegraph.json` at project root:

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

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `CODEGRAPH_WATCH_DEBOUNCE_MS` | File watcher debounce (clamped 100ms–60s, default 2000ms) |
| `CODEGRAPH_MCP_TOOLS` | Re-enable hidden tools: `explore,node,search,callers` |
| `CODEGRAPH_EXPLORE_LINENUMS` | Set to `0` to disable line numbers |
| `CODEGRAPH_NO_DAEMON` | Disable background daemon (sandboxed environments) |
| `CODEGRAPH_TELEMETRY` | Set to `0` to disable telemetry |
| `DO_NOT_TRACK` | Also disables telemetry |
| `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` | Daemon idle timeout |

---

## Key Features

- **35+ Languages**: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Swift, Kotlin, Scala, Dart, Lua, and more
- **17+ Framework Routes**: Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, ASP.NET, Vapor, React Router, SvelteKit, Vue/Nuxt, Astro
- **Cross-language Bridging**: Swift ↔ ObjC, React Native (legacy bridge, TurboModules, Fabric, Paper), Expo Modules
- **Dynamic Dispatch**: Callbacks, React re-render, interface→impl, JSX children — edges grep can't follow
- **Auto-sync**: Native file watcher (FSEvents/inotify/RDCW) with debounced re-index
- **100% Local**: SQLite database, no data leaves your machine
- **Benchmark**: 89% fewer tool calls, 60% cheaper, 69% fewer tokens vs. unassisted agent (validated on 7 repos)

---

## Agent Usage Guidance

When CodeGraph's MCP server is active:

1. **Call `codegraph_explore` FIRST** for any structural/flow question — it returns verbatim source grouped by file, call paths, and blast radius. Usually the only call needed.

2. **Treat returned source as already Read** — do NOT re-open those files with the Read tool.

3. **For a flow question** ("how does X reach Y"), name the symbols spanning the flow in the query (e.g. `mutateElement renderScene`). CodeGraph surfaces the path between them, including dynamic-dispatch hops.

4. **For reading a file or symbol**, use `codegraph_explore` with its name/path — you get line-numbered source (safe to Edit from) plus impact info.

5. **Don't grep then Read** — one `codegraph_explore` replaces the entire search+read loop.

6. **After edits, check the staleness banner** — files listed as pending need a direct Read; everything else is fresh.

7. **Monorepo support**: pass `projectPath` to query a specific sub-project that has a `.codegraph/` index.

---

## Supported Languages

TypeScript (`.ts`, `.tsx`), JavaScript (`.js`, `.jsx`, `.mjs`), ArkTS (`.ets`), Python (`.py`), Go (`.go`), Rust (`.rs`), Java (`.java`), C# (`.cs`), PHP (`.php`), Ruby (`.rb`), C (`.c`, `.h`), C++ (`.cpp`, `.hpp`, `.cc`), Objective-C (`.m`, `.mm`, `.h`), Metal (`.metal`), CUDA (`.cu`, `.cuh`), Swift (`.swift`), Kotlin (`.kt`, `.kts`), Scala (`.scala`, `.sc`), Dart (`.dart`), Svelte (`.svelte`), Vue (`.vue`), Astro (`.astro`), Liquid (`.liquid`), Pascal/Delphi (`.pas`, `.dpr`, `.dpk`, `.lpr`), Lua (`.lua`), R (`.R`, `.r`), Luau (`.luau`), CFML (`.cfc`, `.cfm`, `.cfs`), COBOL (`.cbl`, `.cob`, `.cpy`), VB.NET (`.vb`), Erlang (`.erl`, `.hrl`, `.escript`), Solidity (`.sol`), Terraform/OpenTofu (`.tf`, `.tfvars`, `.tofu`), Nix (`.nix`).