|
|
@@ -0,0 +1,242 @@
|
|
|
+---
|
|
|
+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`).
|
