mirror of
https://github.com/colbymchenry/codegraph.git
synced 2026-11-02 08:23:14 +08:00
Colby Mchenry
68eaf0dbd8
## Summary
Completes the explore-overhaul arc: `codegraph_explore` becomes the single primary tool an agent reaches for, and its coverage + output shape are tuned so flow/architecture questions resolve with near-zero Read/Grep.
### What changed
- **explore is the sole primary tool** — removed `codegraph_context` (the fuzzy-input Read-trigger) and `codegraph_trace` (under-picked by agents); explore already surfaces the call flow among the symbols you name. A plain natural-language question now works as the query.
- **Store/handler coverage** — functions defined inside object literals (Zustand `create((set, get) => ({ … }))`, Redux/Pinia/MobX, exported handler/route maps) are indexed as real symbols, including calls through `useStore.getState().fn()` and destructured `const { fn } = useStore.getState()`. A general AST rule, not a per-lib hack.
- **Overload disambiguation** — explore leads with the *right* definition when a method name is overloaded across types (a PascalCase type token in the query biases to that type's own def); `codegraph_node` returns *every* overload's body in one call, with an optional `file`/`line` selector to pin one.
- **Method-atomic render** — explore never returns half a method; at the size budget it drops whole methods/files (and lists what it dropped) instead of truncating a body mid-method.
- **Native-read-shaped output** — per-call output is capped to ~24K with a 25K hard ceiling and concentrated into ~150–250-line flow windows, mirroring how the agent natively reads; repo size scales the *call* budget, not the per-call size (a larger response just gets externalized to a file the host Reads back).
- **Blast radius** folded into explore (dependents + covering tests, locations only).
### Benchmark (refreshed on this build)
Re-validated the 7-repo A/B on 2026-06-02 (Opus 4.8, effort=high, median of 4). WITH arm re-measured on this build, WITHOUT reused:
**~16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls** — 0 file reads on 6 of 7 repos (Gin ~1).
The arc trades larger, cache-heavy explore responses for guaranteed near-zero reads, so cost/token margins soften vs the prior build (Excalidraw and Tokio land at cost break-even) while time and tool-calls stay clear wins everywhere — consistent with the project's stated optimization target (latency + tool-calls, not token cost).
### Validation
- Full suite green: **1112 passed, 2 skipped**.
- 28/28 plain WITH runs across the 7 README repos completed clean; reads median 0 on 6/7.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
71 lines
5.5 KiB
TypeScript
71 lines
5.5 KiB
TypeScript
/**
|
|
* Server-level instructions emitted in the MCP `initialize` response.
|
|
*
|
|
* MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
|
|
* SDK, …) surface this text in the agent's system prompt automatically,
|
|
* giving the agent a high-level playbook for the codegraph toolset
|
|
* before it sees individual tool descriptions.
|
|
*
|
|
* Goals when editing this:
|
|
* - Tool selection by intent (which tool for which question)
|
|
* - Common chains (refactor planning = X then Y)
|
|
* - Anti-patterns (don't grep when codegraph_search is faster)
|
|
*
|
|
* Keep it tight. The agent reads this every session — long instructions
|
|
* burn tokens. Reference only tools that exist on `main`; gate any
|
|
* conditional tools behind feature checks if/when they ship.
|
|
*/
|
|
export const SERVER_INSTRUCTIONS = `# Codegraph — code intelligence over an indexed knowledge graph
|
|
|
|
Codegraph is a SQLite knowledge graph of every symbol, edge, and file
|
|
in the workspace. Reads are sub-millisecond; the index lags writes by
|
|
about a second through the file watcher. Consult it BEFORE writing or
|
|
editing code, not during.
|
|
|
|
## Answer directly — don't delegate exploration
|
|
|
|
For "how does X work", architecture, trace, or where-is-X questions,
|
|
answer DIRECTLY — usually with ONE \`codegraph_explore\` call.
|
|
\`codegraph_explore\` takes either a natural-language question or a bag of
|
|
symbol/file names and returns the verbatim source of the relevant symbols
|
|
grouped by file, so it is Read-equivalent and most often the ONLY
|
|
codegraph call you need. Codegraph IS the pre-built search index — so
|
|
delegating the lookup to a separate file-reading sub-task/agent, or
|
|
running your own grep + read loop, repeats work codegraph already did and
|
|
costs more for the same answer. Reach for raw Read/Grep only to confirm a
|
|
specific detail codegraph didn't cover. A direct codegraph answer is
|
|
typically one to a few calls; a grep/read exploration is dozens.
|
|
|
|
## Tool selection by intent
|
|
|
|
- **Almost any question — "how does X work", architecture, a bug, "what/where is X", or surveying an area** → \`codegraph_explore\` (PRIMARY — call FIRST; ONE capped call returns the verbatim source of the relevant symbols grouped by file; most often the ONLY call you need)
|
|
- **"How does X reach/become Y? / the flow / the path from X to Y"** → \`codegraph_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, including dynamic-dispatch hops (callbacks, React re-render, JSX children) grep can't follow
|
|
- **"What is the symbol named X?" (just its location)** → \`codegraph_search\`
|
|
- **"What calls this?" / "What does this call?" / "What would changing this break?"** → \`codegraph_callers\` / \`codegraph_callees\` / \`codegraph_impact\`
|
|
- **One specific symbol's full source (esp. a body \`codegraph_explore\` trimmed), or an OVERLOADED name** → \`codegraph_node\` (with \`includeCode\`): for an ambiguous name it returns EVERY matching definition's body in one call, so you never Read a file to find the right overload
|
|
- **"What's in directory X?"** → \`codegraph_files\`
|
|
- **"Is the index ready / what's its size?"** → \`codegraph_status\`
|
|
|
|
## Common chains
|
|
|
|
- **Flow / "how does X reach Y"**: ONE \`codegraph_explore\` with the symbol names spanning the flow — it surfaces the call path among them (riding dynamic-dispatch hops) AND returns their source. No need to reconstruct the path with \`codegraph_search\` + \`codegraph_callers\`.
|
|
- **Onboarding / understanding any area**: ONE \`codegraph_explore\` is usually the whole answer. Only follow up — \`codegraph_node\` for a specific symbol — if something is still unclear.
|
|
- **Refactor planning**: \`codegraph_search\` → \`codegraph_callers\` → \`codegraph_impact\`. The blast-radius answer comes from impact, not from walking callers manually.
|
|
- **Debugging a regression**: \`codegraph_callers\` of the suspected symbol; widen with \`codegraph_impact\` if an unexpected call appears.
|
|
|
|
## Anti-patterns
|
|
|
|
- **Trust codegraph's results — don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.
|
|
- **Don't grep first** when looking up a symbol by name — \`codegraph_search\` is faster and returns kind + location + signature.
|
|
- **Don't chain \`codegraph_search\` + \`codegraph_node\`** to understand an area — ONE \`codegraph_explore\` returns the relevant symbols' source together in a single round-trip.
|
|
- **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use \`codegraph_node\` for a single symbol.
|
|
- **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. \`codegraph_status\` also lists pending files under "Pending sync".
|
|
|
|
## Limitations
|
|
|
|
- If a tool reports the project isn't initialized, \`.codegraph/\` doesn't exist yet — offer to run \`codegraph init -i\` to build the index.
|
|
- Index lags file writes by ~1 second.
|
|
- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
|
|
- No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.
|
|
`;
|