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.