SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscodegraph

codegraph

Coding & development

View repository

Updated 10-15 22:11

About this skill

CodeGraph — Semantic Code Intelligence

CodeGraph is based on tree-sitter a local code knowledge graph tool that provides AI coding agents (Claude Code, Cursor, Codex, Gemini, etc.) with instant query capabilities for symbol relationships, call graphs, and code structure.

Core Benefits: average ~16% cost savings, ~58% fewer tool calls, ~47% reduction in token consumption, ~22% faster responses.

100% Local — no data leaves your machine, no API keys, no external services, just a SQLite database.

Capability Boundaries

✅ Strong Suits

  1. Code structure queries — "how does X work", "how does X reach Y"
  2. Symbol search and call chain tracing — find callers and callees of functions/classes
  3. Change impact analysis — analyze the blast radius before modifying a symbol
  4. Framework route detection — route bindings for 14 frameworks including Django/Express/NestJS/Spring/Gin
  5. Cross-language bridging — iOS (Swift↔ObjC), React Native (JS↔native), Expo Modules
  6. Auto-sync — file watcher + debounced auto-sync, index updates in real time with code
  7. Full-text search — instant symbol name search based on FTS5
  8. Affected test file tracing — codegraph affected trace test files affected by changes

⚠️ Requirements

  1. Project needs to run codegraph init -i to initialize the knowledge graph index
  2. MCP server needs to be configured to the target Agent via codegraph install Configure to the target Agent
  3. After configuration, the Agent needs to be restarted to load the MCP server
  4. The first index may take a few minutes (depending on codebase size)

❌ Out of Scope (with alternatives)

  1. Real-time debugging / runtime dynamic analysis → use a debugger (e.g., GDB, Chrome DevTools)
  2. Non-filesystem projects (e.g., remote repositories not checked out) → clone locally first
  3. Code editing/generation → use the Agent's own editing capabilities
  4. CI/CD pipeline management → use dedicated CI tools

When to Use This Skill

Use this skill when the agent needs to:

  • Understand codebase architecture: "how does X work", "how does a request reach the database"
  • Trace symbol dependencies: "who calls X", "who does X call"
  • Analyze change impact: "what will modifying X affect"
  • Find call chains: "the complete path from A to B"
  • Review code structure: get project file structure, symbol index
  • Determine affected test files:codegraph affected

Data Privacy

CodeGraph does not collect, store, or transmit any user data. All indexes are stored locally in the project's .codegraph/ directory, and the SQLite database never leaves your machine. No API keys, no external services.

How It Works

Agent → CodeGraph MCP Server (explore/search/callers/callees/impact/node)
         → SQLite 知识图谱 (符号 · 边 · 文件 · FTS5)
  1. Extraction — tree-sitter parses source code into an AST, extracting nodes and edges
  2. Storage — stored in a local SQLite database (.codegraph/codegraph.db) with FTS5 support
  3. Resolution — resolves reference relationships: call→definition, import→source file, framework routes
  4. Auto-Sync — native OS file event watching + debounced sync (default 2s), index updates in real time

Quick Start

# Step 1: 安装 CLI（无需 Node.js）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Step 2: 配置 Agent
codegraph install
# Step 3: 初始化项目
cd your-project
codegraph init -i

Workflow

Step 1. Initialize project — confirm that .codegraph/ exists; if not, run codegraph init -i

Step 2. Choose the appropriate tool — Select an MCP tool based on the query intent (see the tool selection matrix)

Step 3. Execute the query — Call the MCP tool to obtain results.Key constraints：

  • Never fabricate on unfamiliar APIs or uncertain symbol relationships; if CodeGraph returns empty results or cannot confirm, directly tell the user "symbol/relationship not found" and do not impose fabricated information
  • When information is insufficient: first output an assumed version based on the existing information, then list the specific N items that are missing, guiding the user to supplement. Do not give the vague prompt "please provide more information"

Step 4. Process the results — Treat the returned symbol source as already read; no need to verify again with grep/read

Step 5. Check staleness — After editing a file, check the response for the ⚠️ staleness banner, and if present, directly Read the corresponding file

MCP tool selection matrix

Query intent Recommended tool Description
"How does X work" / flow tracing codegraph_explore Preferred. A single call returns the source code, relationship graph, and impact scope
Find symbol location codegraph_search Search by name
Who calls X codegraph_callers Find callers
What does X call codegraph_callees Find callees
Impact of modifying X codegraph_impact Impact scope analysis
Get symbol details codegraph_node Complete source code and metadata
Project file structure codegraph_files List of indexed files
Index health status codegraph_status Statistics and health

For detailed parameters of each tool, see references/mcp-tools.md

CLI command quick reference

codegraph install/uninstall         # 安装/移除 Agent 配置
codegraph init/uninit [path]        # 初始化/移除项目索引
codegraph index/sync [path]         # 索引/增量同步
codegraph status/query/files        # 状态查询
codegraph callers/callees/impact    # 调用链/影响分析
codegraph affected [files...]       # 受影响测试文件
codegraph serve --mcp               # 启动 MCP 服务器
codegraph upgrade [version]         # 升级

For the complete reference, see references/cli-reference.md

Installation quick reference

Automatic installation (recommended):

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph install

For manual configuration of Claude Code, see references/installation.md

Gotchas

  1. First connect the MCP server — codegraph install Only configures the Agent and will not automatically start MCP; the Agent must be restarted to load it
  2. codegraph init -i is required — Each project must initialize the index before first use, otherwise all MCP tools will fail
  3. Data within the debounce window (2s) may be stale — Querying immediately after editing may return old data; check ⚠️ banner
  4. WSL/Windows shared checkout — Do not share the same .codegraph/, use CODEGRAPH_DIR to distinguish
  5. The MCP server delivers the usage guide itself — No need to manually edit CLAUDE.md; the guide is automatically delivered via MCP initialize
  6. Excluded directories — node_modules、dist、build and others are excluded by default; manage via .gitignore Management
  7. Do not ask vague questions when information is insufficient — First output an assumed version, then list the specific missing items (see the Workflow Step 3 template)

Quick Fixes

Problem Solution
"not initialized" Run codegraph init -i
Index is slow Confirm that node_modules and others have been excluded
database is locked Upgrade to the latest version; check whether the Journal is wal
Missing symbol Wait for automatic sync or codegraph sync; check whether the language is supported

See references/troubleshooting.md

FAQ

Q: What is the difference between CodeGraph and grep/find? A: CodeGraph builds a complete symbol relationship graph, understanding call chains, inheritance relationships, and framework routing; grep can only do text matching and cannot understand code semantics.

Q: How much space does the index take up? A: It depends on the size of the codebase. A typical project (~1000 files) takes about a few MB; a large project (~10k files) takes about a few tens of MB.

Q: Does it support monorepos? A: Yes. Run it separately in each subproject directory of the monorepo codegraph init -i and it's done.

Q: How do I update the index? A: The MCP server syncs automatically while running. Manually, you can run codegraph sync for incremental updates or codegraph index --force to rebuild.

Q: Can it be used offline? A: Completely offline. All data is stored in a local SQLite database, with no network requests whatsoever.

Q: How do I uninstall it? A: Run codegraph uninstall to remove all Agent configurations;codegraph uninit to remove the project index.

Q: My project is in Java/Python/Rust. Does CodeGraph support it? A: It supports 20+ languages, including Java, Python, Rust, Go, TypeScript, and more. See the complete list at references/supported-languages.md

Q: What is the use of framework route recognition? A: CodeGraph can automatically recognize route bindings for 14 web frameworks, including Django, Express, Spring, and Gin, directly associating URL paths with handler functions for easy tracking of request flow.

Q: What scenarios does cross-language bridging cover? A: It supports Swift↔ObjC automatic bridging, React Native legacy bridge/TurboModules/Fabric, Expo Modules, and native→JS event channels.

Q: What should I do if indexing fails or gets stuck? A: Run codegraph status to check the status; check whether there are large files (files >1MB are skipped); confirm that the directory is not in the exclusion list; you can try codegraph index --force to rebuild.

Official Sources

References

Audience

User Type Usage
New Users Get started in three steps through Quick Start, use codegraph_explore to answer code questions
Advanced Users Combine callers/callees/impact for in-depth architecture analysis
CI/Maintainers Use codegraph affected to track test files affected by changes