From 0df50fec596a43e33128f7403525b88c76142674 Mon Sep 17 00:00:00 2001 From: Badar <78179321+Badi21@users.noreply.github.com> Date: Thu, 2 Jul 2026 01:46:27 +0200 Subject: [PATCH 1/2] docs: add community usage skill for CodeGraph (codegraph-usage) Field guide collecting community-reported usage patterns: tool selection (impact vs callers), what CodeGraph is not for, staleness banner semantics, monorepo projectPath, CLI-in-container workflow, and over-calling guidance. Addresses #1097 --- skills/codegraph-usage/SKILL.md | 120 ++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 skills/codegraph-usage/SKILL.md diff --git a/skills/codegraph-usage/SKILL.md b/skills/codegraph-usage/SKILL.md new file mode 100644 index 000000000..4d749a42d --- /dev/null +++ b/skills/codegraph-usage/SKILL.md @@ -0,0 +1,120 @@ +--- +name: codegraph-usage +description: Community field guide for working with CodeGraph effectively — when to reach for it, which tool answers which question, known gotchas and workarounds, and what CodeGraph is NOT for. Use when working in a repo that has a .codegraph/ index, or when CodeGraph tool calls return confusing or incomplete results. +--- + +# CodeGraph usage — community field guide + +CodeGraph is a local SQLite knowledge graph of every symbol, call edge, and +file in an indexed project. One query 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. + +This skill collects usage patterns, gotchas, and workarounds reported by real +users. It complements (does not replace) the MCP server instructions. + +## When to reach for CodeGraph + +- "How does X work?" / "Where is X defined?" / "What happens when X runs?" +- Before editing a symbol: get its source, callers, and blast radius in one call. +- Tracing a flow between two points: name both endpoints in one query + (e.g. `mutateElement renderScene`) — it finds the path, including + dynamic-dispatch hops (callbacks, React re-renders) grep can't follow. +- Impact assessment before a refactor, when answering "is this safe to change?", + or when evaluating a PR's risk — not only when you are the one refactoring. + +## When NOT to reach for CodeGraph + +- **Semantic/conceptual search.** The graph knows calls, imports, and + definitions — structure, not meaning. "Find code conceptually similar to X" + or "where do we handle billing edge cases?" are not its job; use your own + reasoning over `explore` results, or plain search. +- **Unindexed content.** Configs, docs, lockfiles, data files, generated code + — use Read/Grep for those. +- **Trivial single-file tasks.** If you already know the exact file and line + ("fix the typo in README", "bump the version string"), calling CodeGraph + first adds a round-trip for nothing. A quick edit does not need a graph. +- **Correctness validation.** The graph has no type checking or test running. + The compiler, test suite, and linter still own "is this right?" — CodeGraph + supplements them with structural context. + +## Which tool answers which question + +The default MCP surface is `codegraph_explore` alone; the narrower tools below +are available via the CLI (`codegraph `) and re-enablable over MCP +with `CODEGRAPH_MCP_TOOLS`. + +| You want to know | Use | Not | +|---|---|---| +| Almost anything: how X works, where X is, survey an area | `explore` | grep + read loop | +| One symbol's source + direct callers | `node` | reading the whole file | +| "What calls X?" (direct, one hop) | `callers` | `impact` | +| "What does X call?" | `callees` | reading X's body and grepping each name | +| "What depends on X **transitively**?" — blast radius | `impact` | chaining `callers` by hand | +| "Which tests are affected by these changed files?" | `affected` | running the full suite to find out | +| File/module layout of an area | `files` | `ls -R` + reading each file | +| Symbol lookup by name/kind | `query` | grep | + +**`impact` vs `callers` is the one people mix up:** `callers` is one hop; +`impact` walks the graph transitively and covers dependents that manual +tracing misses. If the question is "what could break?", it's `impact`. + +## Gotchas & workarounds (community-reported) + +### Don't over-call explore on small tasks +One `explore` call usually answers the whole question — treat the source it +returns as already read. If the task is small and the first call answered it, +stop. Repeated exploratory calls on a task that needed none make sessions +slower and burn tokens (reported against agent harnesses that call +before every minor edit). Rule of thumb: call when you have a genuine +structural question, not as a reflex before every change. + +### Trust results — don't re-verify with grep +Results come from a full AST parse. Re-checking them with grep is slower, +less accurate (grep can't see dynamic dispatch), and wastes context. The one +exception is the staleness banner, below. + +### The staleness banner is per-file, not global +When a response starts with "⚠️ Some files referenced below were edited since +the last index sync…", only the **listed** files are stale — Read those +directly; keep trusting the graph for every file not listed. The rarer +"auto-sync is DISABLED" banner means the whole index is frozen — Read +directly until it's resolved. + +### Overloaded / same-named symbols +A bare name that exists in several places returns every matching definition. +Disambiguate by adding the file path or a neighboring symbol to the query +rather than picking the first result. + +### Monorepos: pass projectPath +If the MCP server started somewhere with no `.codegraph/` of its own, tools +still work per project — pass `projectPath` pointing into any directory that +has an index. No restart needed after a new `codegraph init`. + +### Containers & subagents: use the CLI, skip MCP +The full CLI works standalone with no MCP server: `codegraph explore`, +`node`, `query`, `callers`, `callees`, `impact`, `affected` — same output as +the MCP tools. If your agent runs commands in a container, install codegraph +in the container and call the CLI against the container's filesystem; no +host/container MCP wiring needed. Keep the index fresh with `codegraph sync` +(or a git hook) since the watcher may not run there. Add `--json` to `query`, +`callers`, `callees`, and `impact` for machine-readable output. + +### Index freshness outside agent sessions +The file watcher keeps the graph current (~1s lag) during normal sessions. +When scripting against the index (CI, hooks, containers), run +`codegraph sync` first — an incremental update, cheap. `codegraph index` is +a full rebuild and only needed when things look wrong. + +### Not indexed? Stop asking +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 call — suggest `codegraph init` if relevant, don't run it yourself. + +## Contributing to this skill + +This file is built from user experience. Hit an edge case, a misuse pattern, +or a workaround worth sharing? PRs welcome — add a short entry under +"Gotchas & workarounds" with the symptom, the cause if known, and the +workaround. Date-stamp entries tied to a specific version (behavior may be +fixed later). From 0d52f9d6dfe5a4c5ba51571948b46602bd8f8e01 Mon Sep 17 00:00:00 2001 From: Badar <78179321+Badi21@users.noreply.github.com> Date: Thu, 2 Jul 2026 13:33:45 +0200 Subject: [PATCH 2/2] Rework codegraph-usage skill from review feedback - Reframe as an agent-facing playbook read before using CodeGraph; drop the community/contributing framing and meta. - Remove the projectPath monorepo workaround (now enforced by the tool schema) and the container/subagent and offline-sync sections (user setup, not agent guidance). - Note tool availability depends on MCP config; mark 'affected' as CLI-only. - Clarify 'node' is not a substitute for 'read' on unindexed files. - Soften 'trust results': don't re-verify what CodeGraph returned, but fall back to grep/read for a truncated blast radius or a symbol it didn't cover. --- skills/codegraph-usage/SKILL.md | 178 ++++++++++++++------------------ 1 file changed, 75 insertions(+), 103 deletions(-) diff --git a/skills/codegraph-usage/SKILL.md b/skills/codegraph-usage/SKILL.md index 4d749a42d..ffc9d8bc6 100644 --- a/skills/codegraph-usage/SKILL.md +++ b/skills/codegraph-usage/SKILL.md @@ -1,120 +1,92 @@ --- name: codegraph-usage -description: Community field guide for working with CodeGraph effectively — when to reach for it, which tool answers which question, known gotchas and workarounds, and what CodeGraph is NOT for. Use when working in a repo that has a .codegraph/ index, or when CodeGraph tool calls return confusing or incomplete results. +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. --- -# CodeGraph usage — community field guide +# Using CodeGraph -CodeGraph is a local SQLite knowledge graph of every symbol, call edge, and -file in an indexed project. One query 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. +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. -This skill collects usage patterns, gotchas, and workarounds reported by real -users. It complements (does not replace) the MCP server instructions. +## When to reach for it -## When to reach for CodeGraph +- "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. -- "How does X work?" / "Where is X defined?" / "What happens when X runs?" -- Before editing a symbol: get its source, callers, and blast radius in one call. -- Tracing a flow between two points: name both endpoints in one query - (e.g. `mutateElement renderScene`) — it finds the path, including - dynamic-dispatch hops (callbacks, React re-renders) grep can't follow. -- Impact assessment before a refactor, when answering "is this safe to change?", - or when evaluating a PR's risk — not only when you are the one refactoring. +## When NOT to -## When NOT to reach for CodeGraph +- **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?". -- **Semantic/conceptual search.** The graph knows calls, imports, and - definitions — structure, not meaning. "Find code conceptually similar to X" - or "where do we handle billing edge cases?" are not its job; use your own - reasoning over `explore` results, or plain search. -- **Unindexed content.** Configs, docs, lockfiles, data files, generated code - — use Read/Grep for those. -- **Trivial single-file tasks.** If you already know the exact file and line - ("fix the typo in README", "bump the version string"), calling CodeGraph - first adds a round-trip for nothing. A quick edit does not need a graph. -- **Correctness validation.** The graph has no type checking or test running. - The compiler, test suite, and linter still own "is this right?" — CodeGraph - supplements them with structural context. +## Which call answers which question -## Which tool 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 `). Use whichever is +available — `explore` alone answers most questions. -The default MCP surface is `codegraph_explore` alone; the narrower tools below -are available via the CLI (`codegraph `) and re-enablable over MCP -with `CODEGRAPH_MCP_TOOLS`. - -| You want to know | Use | Not | +| You want | Use | Instead of | |---|---|---| | Almost anything: how X works, where X is, survey an area | `explore` | grep + read loop | -| One symbol's source + direct callers | `node` | reading the whole file | +| 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's body and grepping each name | -| "What depends on X **transitively**?" — blast radius | `impact` | chaining `callers` by hand | -| "Which tests are affected by these changed files?" | `affected` | running the full suite to find out | -| File/module layout of an area | `files` | `ls -R` + reading each file | +| "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 ` — 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 -**`impact` vs `callers` is the one people mix up:** `callers` is one hop; -`impact` walks the graph transitively and covers dependents that manual -tracing misses. If the question is "what could break?", it's `impact`. - -## Gotchas & workarounds (community-reported) - -### Don't over-call explore on small tasks -One `explore` call usually answers the whole question — treat the source it -returns as already read. If the task is small and the first call answered it, -stop. Repeated exploratory calls on a task that needed none make sessions -slower and burn tokens (reported against agent harnesses that call -before every minor edit). Rule of thumb: call when you have a genuine -structural question, not as a reflex before every change. - -### Trust results — don't re-verify with grep -Results come from a full AST parse. Re-checking them with grep is slower, -less accurate (grep can't see dynamic dispatch), and wastes context. The one -exception is the staleness banner, below. - -### The staleness banner is per-file, not global -When a response starts with "⚠️ Some files referenced below were edited since -the last index sync…", only the **listed** files are stale — Read those -directly; keep trusting the graph for every file not listed. The rarer -"auto-sync is DISABLED" banner means the whole index is frozen — Read -directly until it's resolved. - -### Overloaded / same-named symbols -A bare name that exists in several places returns every matching definition. -Disambiguate by adding the file path or a neighboring symbol to the query -rather than picking the first result. - -### Monorepos: pass projectPath -If the MCP server started somewhere with no `.codegraph/` of its own, tools -still work per project — pass `projectPath` pointing into any directory that -has an index. No restart needed after a new `codegraph init`. - -### Containers & subagents: use the CLI, skip MCP -The full CLI works standalone with no MCP server: `codegraph explore`, -`node`, `query`, `callers`, `callees`, `impact`, `affected` — same output as -the MCP tools. If your agent runs commands in a container, install codegraph -in the container and call the CLI against the container's filesystem; no -host/container MCP wiring needed. Keep the index fresh with `codegraph sync` -(or a git hook) since the watcher may not run there. Add `--json` to `query`, -`callers`, `callees`, and `impact` for machine-readable output. - -### Index freshness outside agent sessions -The file watcher keeps the graph current (~1s lag) during normal sessions. -When scripting against the index (CI, hooks, containers), run -`codegraph sync` first — an incremental update, cheap. `codegraph index` is -a full rebuild and only needed when things look wrong. - -### Not indexed? Stop asking -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 call — suggest `codegraph init` if relevant, don't run it yourself. - -## Contributing to this skill - -This file is built from user experience. Hit an edge case, a misuse pattern, -or a workaround worth sharing? PRs welcome — add a short entry under -"Gotchas & workarounds" with the symptom, the cause if known, and the -workaround. Date-stamp entries tied to a specific version (behavior may be -fixed later). +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.