codegraph-usage

name	codegraph-usage
description	How to use CodeGraph well — which tool answers which question, when to reach for it and when not, and the gotchas that trip agents up. Read before using CodeGraph tools in a project that has a .codegraph/ index, and whenever a CodeGraph call returns confusing or incomplete results.

Using CodeGraph

CodeGraph is a local knowledge graph of a project's symbols, call edges, and files. One call returns verbatim line-numbered source plus the call paths between symbols and a blast-radius summary — replacing a grep + read loop with a single round-trip. Read this before reaching for CodeGraph so you pick the right call and avoid the mistakes below.

When to reach for it

• "How does X work?" / "Where is X?" / "What happens when X runs?"
• Before editing a symbol: source + callers + blast radius in one call.
• Tracing a flow: name both endpoints in one query (e.g. mutateElement renderScene) — it rides dynamic-dispatch hops (callbacks, re-renders) that grep can't follow.
• Judging impact before a change, or when reviewing risk — not only your own refactors.

When NOT to

• Semantic/conceptual search. It knows structure (calls, imports, definitions), not meaning. "Code similar to X" or "where do we handle billing edge cases?" — reason over results yourself or use plain search.
• Unindexed content. Configs, docs, lockfiles, generated code — use Read/Grep.
• Trivial single-file edits. If you know the exact file and line, editing directly is faster than a graph round-trip.
• Correctness. No type-checking or test-running here — the compiler, tests, and linter still own "is this right?".

Which call answers which question

Which tools you can reach depends on how CodeGraph was set up: the default MCP surface is codegraph_explore alone, other tools are enabled per config, and all of them exist as CLI subcommands (codegraph <command>). Use whichever is available — explore alone answers most questions.

You want	Use	Instead of
Almost anything: how X works, where X is, survey an area	explore	grep + read loop
One symbol's full source + direct callers	node	reading the whole file
"What calls X?" (direct, one hop)	callers	impact
"What does X call?"	callees	reading X and grepping each name
"What depends on X transitively?" (blast radius)	impact	chaining callers by hand
Symbol lookup by name/kind	query	grep
File/module layout of an area	files	ls -R + reading files

node returns a symbol's full source or a file's contents from the index — it is not a substitute for read on files CodeGraph doesn't cover.

CLI-only (not an MCP tool): codegraph affected <files...> — which test files a change touches, without running the suite.

impact vs callers is the common mixup: callers is one hop; impact walks the graph transitively. "What could break?" → impact.

Gotchas

Don't re-verify what CodeGraph returned — but do fill gaps

Its results come from a full AST parse, so re-grepping the same symbols is slower and blinder (grep misses dynamic dispatch) — don't double-check what it gave you. It is not infallible, though: a blast radius may be truncated (+N more), and a symbol you expected may be missing. When you need more than it returned, fall back to grep/read for that gap — without discarding the parts it did provide. (The one case where its output itself is suspect: the staleness banner, below.)

Don't over-call on small tasks

One explore usually answers the whole question — treat what it returns as already read. If the first call answered it, stop. Calling before every minor edit just burns tokens.

The staleness banner is per-file

"⚠️ Some files referenced below were edited since the last index sync…" — only the listed files are stale; Read those directly and keep trusting the graph for the rest. The rarer "auto-sync is DISABLED" banner means the whole index is frozen — Read directly until it's resolved.

Same-named symbols

A bare name that exists in several places returns every match. Disambiguate with a file path or a neighboring symbol rather than taking the first result.

Not indexed? Stop calling it

If a tool reports no .codegraph/ for a project, stop calling CodeGraph there for the rest of the session and use built-in tools. Indexing is the user's decision — mention codegraph init if it comes up, but don't run it yourself.