CodeGraph

Supercharge Claude Code, Cursor, Codex, and OpenCode with Semantic Code Intelligence

94% fewer tool calls · 77% faster exploration · 100% local

Get Started

npx @whenyoung/codegraph

Interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode

Initialize Projects

cd your-project
codegraph init -i

中文介绍

CodeGraph 是一个本地代码知识图谱工具，通过 MCP 协议为 Claude Code 等 AI 编程助手提供结构化代码智能——让 Agent 直接查图谱而无需反复 grep 文件。

核心效果

| 指标 | 数据 | |---|---| | 减少工具调用 | 平均 92% | | 加快代码探索 | 平均 71% | | 数据位置 | 100% 本地，不上传 |

🚀 推荐：使用 Claude Code 技能（零门槛）

安装完成后，不需要记忆任何命令，在 Claude Code 里直接说：

"帮我初始化 codegraph" "帮我建立跨仓库索引" "查一下 DiscountService 的调用方"

Claude 会自动执行正确的命令、引导你完成配置、构建索引、并在全程显示进度。

技能涵盖完整流程：

• ✅ 自动检测安装状态
• ✅ 引导选择仓库目录和 db 管理模式
• ✅ 并行初始化多个仓库
• ✅ 构建跨仓库图谱（带进度条 + ETA + 断点续跑）
• ✅ 日常维护（sync、新增仓库）

安装技能（唯一需要手动做的事）

下载仓库中的 skill.md 并放到：

~/.claude/skills/codegraph/skill.md

然后在 Claude Code 里直接说：

用户：帮我初始化 codegraph

技能会自动检测环境，如果还没安装 CodeGraph，会提示你执行：

npx @whenyoung/codegraph@workspace

安装完成后，Claude 继续引导完成索引构建，全程无需记忆任何命令。

🆕 多仓库跨库分析（Java + Maven）

当你的代码分布在多个仓库时，CodeGraph 将它们合并成一个统一图谱，支持跨仓库调用链追踪和全局影响分析。

| 查询 | 单仓库 | 多仓库模式 | |---|---|---| | 谁调用了 DiscountService？ | 只看当前仓库 | 所有仓库的调用方 | | 改了 OrderModel 会影响什么？ | 当前仓库影响 | 全局影响半径 |

实测 11 个 Java 仓库，ws build 仅需 12 秒；500 个仓库估算 5–8 分钟。

集成到 Agent / Skill

已有成熟的集成模式（三阶段使用、证据门、主/子 Agent 分工），详见 集成到 Agent / Skill 工作流 章节。

Why CodeGraph?

When Claude Code explores a codebase, it spawns Explore agents that scan files with grep, glob, and Read — consuming tokens on every tool call.

CodeGraph gives those agents a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.

Benchmark Results

Tested across 6 real-world codebases comparing Claude Code's Explore agent with and without CodeGraph:

Average: 92% fewer tool calls · 71% faster

| Codebase | With CG | Without CG | Improvement | |----------|---------|------------|-------------| | VS Code · TypeScript | 3 calls, 17s | 52 calls, 1m 37s | 94% fewer · 82% faster | | Excalidraw · TypeScript | 3 calls, 29s | 47 calls, 1m 45s | 94% fewer · 72% faster | | Claude Code · Python + Rust | 3 calls, 39s | 40 calls, 1m 8s | 93% fewer · 43% faster | | Claude Code · Java | 1 call, 19s | 26 calls, 1m 22s | 96% fewer · 77% faster | | Alamofire · Swift | 3 calls, 22s | 32 calls, 1m 39s | 91% fewer · 78% faster | | Swift Compiler · Swift/C++ | 6 calls, 35s | 37 calls, 2m 8s | 84% fewer · 73% faster |

All tests used Claude Opus 4.6 (1M context) with Claude Code v2.1.91. Each test spawned a single Explore agent with the same question.

Queries used: | Codebase | Query | |----------|-------| | VS Code | "How does the extension host communicate with the main process?" | | Excalidraw | "How does collaborative editing and real-time sync work?" | | Claude Code (Python+Rust) | "How does tool execution work end to end?" | | Claude Code (Java) | "How does tool execution work end to end?" | | Alamofire | "Trace how a request flows from Session.request() through to the URLSession layer" | | Swift Compiler | "How does the Swift compiler handle error diagnostics?" |

With CodeGraph — the agent uses codegraph_explore and stops: | Codebase | Files Indexed | Nodes | Tool Uses | Tokens | Time | File Reads | |----------|--------------|-------|-----------|--------|------|------------| | VS Code (TypeScript) | 4,002 | 59,377 | 3 | 56.6k | 17s | 0 | | Excalidraw (TypeScript) | 626 | 9,859 | 3 | 57.1k | 29s | 0 | | Claude Code (Python+Rust) | 115 | 3,080 | 3 | 67.1k | 39s | 0 | | Claude Code (Java) | — | — | 1 | 40.8k | 19s | 0 | | Alamofire (Swift) | 102 | 2,624 | 3 | 57.3k | 22s | 0 | | Swift Compiler (Swift/C++) | 25,874 | 272,898 | 6 | 77.4k | 35s | 0 |

Without CodeGraph — the agent uses grep, find, ls, and Read extensively: | Codebase | Tool Uses | Tokens | Time | File Reads | |----------|-----------|--------|------|------------| | VS Code (TypeScript) | 52 | 89.4k | 1m 37s | ~15 | | Excalidraw (TypeScript) | 47 | 77.9k | 1m 45s | ~20 | | Claude Code (Python+Rust) | 40 | 69.3k | 1m 8s | ~15 | | Claude Code (Java) | 26 | 73.3k | 1m 22s | ~15 | | Alamofire (Swift) | 32 | 52.4k | 1m 39s | ~10 | | Swift Compiler (Swift/C++) | 37 | 99.1k | 2m 8s | ~20 |

Key observations:

• With CodeGraph, the agent never fell back to reading files — it trusted the codegraph_explore results completely
• Without CodeGraph, agents spent most of their time on discovery (find, ls, grep) before they could even start reading relevant code
• The Java codebase needed only 1 codegraph_explore call to answer the entire question
• Cross-language queries (Python+Rust) worked seamlessly — CodeGraph's graph traversal found connections across language boundaries
• The Swift benchmark (Alamofire) traced a 9-step call chain from Session.request() to URLSession.dataTask() — CodeGraph's graph traversal at depth 3 captured the full chain in one explore call
• The Swift Compiler benchmark is the largest codebase tested (25,874 files, 272,898 nodes) — CodeGraph indexed it in under 4 minutes and the agent answered a complex cross-cutting question with 6 explore calls and zero file reads in 35 seconds

Key Features

| | | |---|---| | Smart Context Building | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents | | Full-Text Search | Find code by name instantly across your entire codebase, powered by FTS5 | | Impact Analysis | Trace callers, callees, and the full impact radius of any symbol before making changes | | Always Fresh | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config | | 19+ Languages | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi | | Framework-aware Routes | Recognizes web-framework routing files and links URL patterns to their handlers across 13 frameworks | | 100% Local | No data leaves your machine. No API keys. No external services. SQLite database only | | 🆕 Multi-Repo Workspace | Merge multiple repositories into a unified graph — trace cross-repo call chains and impact analysis across your entire codebase |

🆕 Multi-Repo Workspace

New in this fork. When your codebase spans multiple repositories, CodeGraph can merge them into a single unified knowledge graph — letting you trace call chains and impact across repo boundaries in one query.

What it does

Single-repo mode gives you a graph per project. Workspace mode merges all your repos into one SQLite database and resolves cross-repo edges — so when repo A calls a class defined in repo B, the agent can follow that edge without switching context.

| Query | Single-repo | Workspace | |---|---|---| | Who calls DiscountService? | Only callers in the same repo | All callers across all repos | | What breaks if I change OrderModel? | Impact within one repo | Full cross-repo blast radius | | Where is PromotionCalculator defined? | Must know which repo | One search across all repos |

Cross-repo edges (Java + Maven)

Cross-repo call resolution currently works for Java + Maven projects. CodeGraph parses each repo's pom.xml to build a dependency graph, then resolves import statements and method calls across repo boundaries.

For other languages, workspace mode still merges all symbols into a unified search index — cross-repo call edges are not yet resolved, but symbol lookup and codegraph_explore work across repos.

Setup

# Step 1 — create a managed workspace, then register its repositories
cd ~/your-repos
codegraph ws init                 # managed per-repo DBs are the default
find ~/your-repos -maxdepth 2 -name "pom.xml" \
  -not -path "*/target/*" | sed 's|/pom.xml||' \
  | xargs codegraph ws add

# Step 2 — index all registered repos in parallel (cores/2 concurrency)
JOBS=$(( $(sysctl -n hw.logicalcpu 2>/dev/null || nproc) / 2 ))
find ~/your-repos -maxdepth 2 -name "pom.xml" \
  -not -path "*/target/*" | sed 's|/pom.xml||' \
  | xargs -P "$JOBS" -I {} codegraph init -i {}

# Step 3 — build the workspace (with progress bar + ETA)
codegraph ws build

Performance: 11 Java repos builds in ~12 seconds. 500 repos estimated 5–8 minutes.

Interrupted? Resume from the last checkpoint — no need to restart:

codegraph ws build --resume

Daily workflow

# After changing code in a repo
codegraph ws sync --repo repo-a      # sync one repo
codegraph ws sync                     # sync all repos with changes

# Check workspace health
codegraph ws status

# Add a new repo to an existing workspace
codegraph ws add new-repo/       # register first for managed DB placement
codegraph init -i new-repo/
codegraph ws sync --repo new-repo

Using workspace in your agent

Pass workspacePath (the parent directory containing .codegraph-workspace.json) to any tool:

codegraph_callers   symbol="DiscountService"   workspacePath="~/your-repos"
codegraph_impact    symbol="OrderModel"        workspacePath="~/your-repos"
codegraph_search    query="PromotionCalculator" workspacePath="~/your-repos"

Tip: codegraph_context and codegraph_explore do not support workspacePath — use projectPath for deep dives into a single repo, and workspacePath for cross-repo traversal.

集成到 Agent / Skill 工作流

以下模式来自实战经验（gan-dev-v2 自动化开发 Agent），适用于任何需要读代码→设计方案→编写代码的 Agent 或 Skill。

核心原则

CodeGraph 的价值是防漏，不是替代读代码。

Agent 读代码是为了理解业务逻辑；CodeGraph 是为了让 Agent 在读完之后，不会遗漏那些"隐藏在其他仓库里的调用者"或"改了这里会炸哪里"。

三阶段使用模式

在研发流程中，codegraph 工具在不同阶段有不同的使用目的：

| 阶段 | 时机 | 工具 | 深度 | 目的 | |---|---|---|---|---| | 理解阶段 | 调研读代码时遇到感兴趣的符号 | callers + impact | depth=1 | 建立背景：这个符号范围大不大、涉及哪些仓库 | | 验证阶段 | 方案草稿出来后 | callers + impact | depth=2 | 确认方案核心符号的影响面没有遗漏 | | 精确阶段 | 执行计划拆完后，针对每个具体改动方法 | callers + impact | depth=2 | 针对具体改动方法查漏补缺 |

口诀： 读懂是目的 → 只查 1 层；方案已定 → 查 2 层验证。

工具分工：主 Agent vs 子 Agent

| | 主 Agent（orchestrator） | 子 Agent（研究/开发） | |---|---|---| | 工具 | codegraph_callers / codegraph_impact | codegraph_context / codegraph_explore | | 参数 | workspacePath（跨仓库） | projectPath（单仓库深挖） | | 原因 | 跨仓库边返回的是其他仓库的文件，只有主 Agent 有全局上下文才能判断是否需要跟进 | 子 Agent 只负责自己所在仓库的深度理解 |

主 Agent
├── codegraph_callers(核心符号, workspacePath)     ← 发现跨仓库调用者
├── codegraph_impact(核心符号, workspacePath, 2)   ← 跨仓库影响面
└── spawn 子 Agent（按仓库分组）
    └── codegraph_context(projectPath)             ← 单仓库深挖
    └── codegraph_explore(projectPath)             ← 陌生模块全面扫描

在 Skill 中嵌入 CodeGraph 证据门（强制执行）

在自动化 Skill 或 Agent 提示词中，推荐用证据门模式确保 codegraph 查询不被跳过：

## CodeGraph 证据门（硬拦截，不可跳过）

读取 `.agent-work/<slug>/codegraph-evidence.md`：
- 文件存在 → 继续
- 文件不存在 → BLOCKED

  必须对方案核心符号执行：
  codegraph_callers(symbol, workspacePath, maxDepth=2)
  codegraph_impact(symbol, workspacePath, maxDepth=2)
  
  将原始输出写入 codegraph-evidence.md 后重新提交。

为什么用文件做检查点而不是口头约定： 子 Agent 没有主对话的 context，无法继承约束。写入文件 = 留下可核查的物理证据，Orchestrator 读文件就能判断步骤是否真正执行。

在 Skill 提示词中声明 CodeGraph 使用规则

将以下片段加入你的调研/开发 Skill：

## Codegraph 使用规则

调研全程可使用 codegraph MCP 工具（workspacePath: ~/your-repos）。

**跨仓库查询**（主 Agent 执行）：
- codegraph_callers / codegraph_impact → workspacePath，depth=2
- 涉及跨仓库依赖时，始终用 workspacePath 而不是 projectPath

**单仓库深挖**（子 Agent 执行）：
- codegraph_context / codegraph_explore → projectPath

**验证节点**（方案确认后必查）：
1. codegraph_callers <核心改动类> — 有没有遗漏的调用者
2. codegraph_impact <核心改动类> maxDepth=2 — 影响面是否完整

Framework-aware Routes

CodeGraph detects web-framework routing files and emits route nodes linked by references edges to their handler classes or functions. Querying callers of a view/controller now surfaces the URL pattern that binds it.

| Framework | Shapes recognized | |---|---| | Django | path(), re_path(), url(), include() in urls.py (CBV .as_view(), dotted paths) | | Flask | @app.route('/path', methods=[...]), blueprint routes | | FastAPI | @app.get(...), @router.post(...), all standard methods | | Express | app.get(...), router.post(...) with middleware chains | | Laravel | Route::get(), Route::resource(), Controller@action, tuple syntax | | Rails | get '/x', to: 'users#index', hash-rocket => syntax | | Spring | @GetMapping, @PostMapping, @RequestMapping on methods | | Gin / chi / gorilla / mux | r.GET(...), router.HandleFunc(...) | | Axum / actix / Rocket | .route("/x", get(handler)) | | ASP.NET | [HttpGet("/x")] attributes on action methods | | Vapor | app.get("x", use: handler) | | React Router / SvelteKit | Route component nodes |

Quick Start

1. Run the Installer

npx @whenyoung/codegraph

The installer will:

• Ask which agent(s) to configure — auto-detects installed ones from: Claude Code, Cursor, Codex CLI, opencode
• Prompt to install codegraph on your PATH (so agents can launch the MCP server)
• Ask whether configs apply to all your projects or just this one
• Write each chosen agent's MCP server config + an instructions file (e.g. CLAUDE.md, .cursor/rules/codegraph.mdc, ~/.codex/AGENTS.md)
• Set up auto-allow permissions when Claude Code is one of the targets
• Initialize your current project (local installs only)

Non-interactive (scripting / CI):

codegraph install --yes                              # auto-detect agents, install global
codegraph install --target=cursor,claude --yes       # explicit target list
codegraph install --target=auto --location=local     # detected agents, project-local
codegraph install --print-config codex               # print snippet, no file writes

| Flag | Values | Default | |---|---|---| | --target | auto, all, none, or csv (claude,cursor,...) | prompt | | --location | global, local | prompt | | --yes | (boolean) | prompt every step | | --no-permissions | (boolean) skip Claude auto-allow list | permissions on | | --print-config <id> | dump snippet for one agent and exit | — |

2. Restart Your Agent

Restart your agent (Claude Code / Cursor / Codex CLI / opencode) for the MCP server to load.

3. Initialize Projects

cd your-project
codegraph init -i

Builds the per-project knowledge graph index. Also wires up any project-local agent surfaces (e.g. Cursor's .cursor/rules/codegraph.mdc) so a single global codegraph install works in every project you open — no need to re-run the installer per project.

That's it — your agent will use CodeGraph tools automatically when a .codegraph/ directory exists.

Install globally:

npm install -g @colbymchenry/codegraph

Add to ~/.claude.json:

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

For a global MCP setup that should default to one multi-repo workspace, set CODEGRAPH_DEFAULT_WORKSPACE_PATH in that client's stdio-server environment. For Codex TOML configuration:

[mcp_servers.codegraph]
command = "/absolute/path/to/codegraph"
args = ["serve", "--mcp"]
env = { CODEGRAPH_DEFAULT_WORKSPACE_PATH = "/absolute/path/to/workspace" }

Add to ~/.claude/settings.json (optional, for auto-allow):

{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_context",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

The installer automatically adds these instructions to ~/.claude/CLAUDE.md:

## CodeGraph

CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.

### If `.codegraph/` exists in the project

**NEVER call `codegraph_explore` or `codegraph_context` directly in the main session.** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?").

**When spawning Explore agents**, include this instruction in the prompt:

> This project has CodeGraph initialized (.codegraph/ exists). Use `codegraph_explore` as your PRIMARY tool — it returns full source code sections from all relevant files in one call.
>
> **Rules:**
> 1. Follow the explore call budget in the `codegraph_explore` tool description — it scales automatically based on project size.
> 2. Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative.
> 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results.

**The main session may only use these lightweight tools directly** (for targeted lookups before making edits, not for exploration):

| Tool | Use For |
|------|---------|
| `codegraph_search` | Find symbols by name |
| `codegraph_callers` / `codegraph_callees` | Trace call flow |
| `codegraph_impact` | Check what's affected before editing |
| `codegraph_node` | Get a single symbol's details |

### If `.codegraph/` does NOT exist

At the start of a session, ask the user if they'd like to initialize CodeGraph:

"I notice this project doesn't have CodeGraph initialized. Would you like me to run `codegraph init -i` to build a code knowledge graph?"

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code                               │
│                                                                  │
│  "Implement user authentication"                                 │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐      ┌─────────────────┐                   │
│  │  Explore Agent  │ ──── │  Explore Agent  │                   │
│  └────────┬────────┘      └────────┬────────┘                   │
│           │                        │                             │
└───────────┼────────────────────────┼─────────────────────────────┘
            │                        │
            ▼                        ▼
┌───────────────────────────────────────────────────────────────────┐
│                     CodeGraph MCP Server                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
│  │   Search    │  │   Callers   │  │   Context   │               │
│  │  "auth"     │  │  "login()"  │  │  for task   │               │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │
│         │                │                │                       │
│         └────────────────┼────────────────┘                       │
│                          ▼                                        │
│              ┌───────────────────────┐                            │
│              │   SQLite Graph DB     │                            │
│              │   • 387 symbols       │                            │
│              │   • 1,204 edges       │                            │
│              │   • Instant lookups   │                            │
│              └───────────────────────┘                            │
└───────────────────────────────────────────────────────────────────┘

1. Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).

2. Storage — Everything goes into a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search.

3. Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.

4. Auto-Sync — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed.

CLI Reference

codegraph                         # Run interactive installer
codegraph install                 # Run installer (explicit)
codegraph init [path]             # Initialize in a project (--index to also index)
codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
codegraph sync [path]             # Incremental update
codegraph status [path]           # Show statistics
codegraph query <search>          # Search symbols (--kind, --limit, --json)
codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
codegraph context <task>          # Build context for AI (--format, --max-nodes)
codegraph affected [files...]     # Find test files affected by changes (see below)
codegraph serve --mcp             # Start MCP server

codegraph affected

Traces import dependencies transitively to find which test files are affected by changed source files.

codegraph affected src/utils.ts src/api.ts         # Pass files as arguments
git diff --name-only | codegraph affected --stdin   # Pipe from git diff
codegraph affected src/auth.ts --filter "e2e/*"     # Custom test file pattern

| Option | Description | Default | |--------|-------------|---------| | --stdin | Read file list from stdin | false | | -d, --depth <n> | Max dependency traversal depth | 5 | | -f, --filter <glob> | Custom glob to identify test files | auto-detect | | -j, --json | Output as JSON | false | | -q, --quiet | Output file paths only | false |

CI/hook example:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

MCP Tools

When running as an MCP server, CodeGraph exposes these tools to Claude Code:

| Tool | Purpose | |------|---------| | codegraph_search | Find symbols by name across the codebase | | codegraph_context | Build relevant code context for a task | | codegraph_callers | Find what calls a function | | codegraph_callees | Find what a function calls | | codegraph_impact | Analyze what code is affected by changing a symbol | | codegraph_node | Get details about a specific symbol (optionally with source code) | | codegraph_files | Get indexed file structure (faster than filesystem scanning) | | codegraph_status | Check index health and statistics |

Library Usage

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');
// Or: const cg = await CodeGraph.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

Configuration

The .codegraph/config.json file controls indexing:

{
  "version": 1,
  "languages": ["typescript", "javascript"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
  "frameworks": [],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true
}

| Option | Description | Default | |--------|-------------|---------| | languages | Languages to index (auto-detected if empty) | [] | | exclude | Glob patterns to ignore | ["node_modules/**", ...] | | frameworks | Framework hints for better resolution | [] | | maxFileSize | Skip files larger than this (bytes) | 1048576 (1MB) | | extractDocstrings | Extract docstrings from code | true | | trackCallSites | Track call site locations | true |

Supported Languages

| Language | Extension | Status | |----------|-----------|--------| | TypeScript | .ts, .tsx | Full support | | JavaScript | .js, .jsx, .mjs | Full support | | Python | .py | Full support | | Go | .go | Full support | | Rust | .rs | Full support | | Java | .java | Full support | | C# | .cs | Full support | | PHP | .php | Full support | | Ruby | .rb | Full support | | C | .c, .h | Full support | | C++ | .cpp, .hpp, .cc | Full support | | Swift | .swift | Full support | | Kotlin | .kt, .kts | Full support | | Scala | .scala, .sc | Full support (classes, traits, methods, type aliases, Scala 3 enums) | | Dart | .dart | Full support | | Svelte | .svelte | Full support (script extraction, Svelte 5 runes, SvelteKit routes) | | Vue | .vue | Full support (script + script-setup extraction, Nuxt page/API/middleware routes) | | Liquid | .liquid | Full support | | Pascal / Delphi | .pas, .dpr, .dpk, .lpr | Full support (classes, records, interfaces, enums, DFM/FMX form files) |

Troubleshooting

"CodeGraph not initialized" — Run codegraph init in your project directory first.

Indexing is slow — Check that node_modules and other large directories are excluded. Use --quiet to reduce output overhead.

Indexing is slow / MCP database is locked / WASM fallback active — codegraph ships with a WASM SQLite fallback for environments where better-sqlite3 (a native module, declared as optionalDependencies) can't install. The fallback is 5-10x slower than the native backend and uses a journal mode that lets writers block readers, so MCP queries can also hit database is locked while indexing runs. Run codegraph status and look at the Backend: line:

• Backend: native — you're on the fast path, nothing to do.

• Backend: wasm — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix:

  # macOS
  xcode-select --install                                  # installs the C compiler
  
  # Linux (Debian / Ubuntu)
  sudo apt install build-essential python3 make
  
  # Linux (RHEL / Fedora)
  sudo yum groupinstall "Development Tools"
  
  # Then rebuild on any platform:
  npm rebuild better-sqlite3
  
  # Or force-include as a hard dep:
  npm install better-sqlite3 --save

  After the fix, codegraph status should show Backend: native.

MCP server not connecting — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that codegraph serve --mcp works from the command line.

Missing symbols — The MCP server auto-syncs on save (wait a couple seconds). Run codegraph sync manually if needed. Check that the file's language is supported and isn't excluded by config patterns.

License

MIT

Made for the Claude Code community

Report Bug · Request Feature