|
| 1 | +--- |
| 2 | +description: CodeGraph MCP usage guide — when to use which tool |
| 3 | +alwaysApply: true |
| 4 | +--- |
| 5 | +<!-- CODEGRAPH_START --> |
| 6 | +## CodeGraph |
| 7 | + |
| 8 | +This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot. |
| 9 | + |
| 10 | +### When to prefer codegraph over native search |
| 11 | + |
| 12 | +Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open. |
| 13 | + |
| 14 | +| Question | Tool | |
| 15 | +|---|---| |
| 16 | +| "Where is X defined?" / "Find symbol named X" | `codegraph_search` | |
| 17 | +| "What calls function Y?" | `codegraph_callers` | |
| 18 | +| "What does Y call?" | `codegraph_callees` | |
| 19 | +| "What would break if I changed Z?" | `codegraph_impact` | |
| 20 | +| "Show me Y's signature / source / docstring" | `codegraph_node` | |
| 21 | +| "Give me focused context for a task/area" | `codegraph_context` | |
| 22 | +| "See several related symbols' source at once" | `codegraph_explore` | |
| 23 | +| "What files exist under path/" | `codegraph_files` | |
| 24 | +| "Is the index healthy?" | `codegraph_status` | |
| 25 | + |
| 26 | +### Rules of thumb |
| 27 | + |
| 28 | +- **Answer directly — don't delegate exploration.** For "how does X work" / architecture / trace questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer. |
| 29 | +- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context. |
| 30 | +- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call. |
| 31 | +- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call. |
| 32 | +- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more. |
| 33 | +- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn. |
| 34 | + |
| 35 | +### If `.codegraph/` doesn't exist |
| 36 | + |
| 37 | +The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"* |
| 38 | +<!-- CODEGRAPH_END --> |
0 commit comments