codegraph

name	codegraph
description	CodeGraph scout before broad grep/read. Use for repo explanation, navigation, diagnosis, runtime/reconnect flow, contract/RPC/schema tracing, refactor/cycle seams, dead-code cleanup, test targeting, and code review.
compatibility	Requires the `codegraph` CLI (`npm install -g @optave/codegraph`) and, for MCP use, the Pi MCP adapter with a `codegraph` server entry.

CodeGraph

CodeGraph is a scout: it indexes a structural map, narrows the search, and explains relationships. It produces suspects, not proof. It does not validate behavior. codegraph build . means “the graph rebuilt,” not “the code passed.” codegraph check and diff-impact are structural checks, not substitutes for tests, typecheck, lint, or runtime verification.

Scout before reading broadly: find exact files/symbols, trace relationships, then read the narrowed source. For absence claims, scout first, then corroborate with exact search, source reads, and the project’s package/export boundaries.

Report in three ledgers: CodeGraph evidence, source-read interpretation, and proof commands/manual checks. Do not merge them.

Before editing, run a seam checkpoint: name the existing behavioral seam you intend to preserve or extend, the invariant that must stay true, and the smallest scoped change that exercises that seam. CodeGraph can identify structure and blast radius; it cannot decide the behavioral contract for you.

Blind spots

CodeGraph sees static structure, not every live dependency. Watch for:

• interface/property contracts where implementations and callers share shape rather than a symbol edge;
• schemas and generated/inferred protocol types whose value/type flow is indirect;
• computed keys, indexed dispatch, string-named RPC methods, reflection, config, or external clients;
• package subpath imports, barrel/re-export wrappers, path aliases, and cross-workspace consumers that may not resolve to a symbol edge;
• test-only consumers and wrapper files that only re-export a symbol without using it;
• local closure symbols, Effect.fn locals, object-literal handlers, and service methods implemented as properties; where may miss them even when brief names the containing file;
• runtime-only behavior: validation/decoding, auth, reconnect timing, cache warmup, environment/process effects, backwards compatibility;
• public protocol shape, event/message ordering, lifecycle/timer behavior, persistence ordering, dialect/config scoping, and test identity. These are often owned by conventions or tests rather than static symbol edges.

When one is in play, say so. Use CodeGraph to narrow the target, then use exact targeted search and source reads for the blind spot. Keep generated/schema-heavy results as a hint, not the report backbone: generated protocol files often prove a method/schema exists but not which app path handles it.

CLI guardrails

The CLI is the source of truth. Before using a flag not shown here, run codegraph help <command>.

Known command shapes:

• Directory scoping for structure is positional: codegraph structure apps/server/src --depth 2 -T; do not use --directory.
• cycles has no --limit; cap display externally (| head) or use --json and post-process.
• cycles --json may order cycles differently from text output. Select a cycle by its file set or focus match, not by “Cycle N” alone.
• cycles --functions is separate from file-level cycles; run it when the report might imply a symbol/function cycle, and say explicitly when only a file-level cycle was found.
• deps --json returns { file, results: [{ file, imports, importedBy }] }; read results[0], not top-level imports.
• deps --json proves file import edges and typeOnly; it usually does not name the imported symbols or runtime calls. Use source reads or targeted exact search for import specifiers, call sites, and responsibility claims.
• path resolves symbols, not file paths. For file-to-file cycle edges, use cycles plus deps --json; do not waste time trying codegraph path fileA fileB.
• fn-impact --file/-f can be fragile across CLI versions. If it errors, rerun unscoped, then disambiguate by the reported definition path.
• roles is not path-positional; scope with supported flags such as --file or post-filter JSON by .file.
• exports --unused --json returns results plus reexportedSymbols; inspect both, or you will miss re-exported public-surface suspects.
• “No uses found” can mean “no visible static edge,” not “unused”; check the blind spots before treating it as absence evidence.
• build, stats, map, structure, triage, deps, cycles, and complexity are structural scouting only, not validation.

Scout loop

1. Index and inspect graph health.

   codegraph build .
   codegraph stats -T
   

   build is incremental by default. It records structure for later queries; it is not a lint/test/typecheck gate. Completion criterion: the graph exists, stats shows language/quality/cycle/hotspot data, and you know whether tests are excluded (-T) or included. Do not report this step as validation.

2. Orient before choosing files.

   codegraph map -T
   codegraph structure --depth 2 -T
   codegraph triage -T --limit 20
   

   To narrow a large repo, pass the directory positionally:

   codegraph structure apps/server/src --depth 2 -T --limit 80
   codegraph structure packages --depth 2 -T --limit 80
   

   Completion criterion: you can name the likely modules, hotspots, and candidate files instead of guessing from filenames.

3. Pin exact targets.

   codegraph where <symbol> -T
   codegraph where --file <path> -T
   codegraph brief <file> -T
   

   If names are ambiguous, rerun with --file, --kind, or a file-level query. If where misses a local closure or property method after CodeGraph has named the file, use brief <file> plus a targeted exact search inside the narrowed area; record that the symbol edge was not visible. Completion criterion: every candidate has an exact path/line or a named CodeGraph blind spot with the narrowed file path.

4. Trace the relevant structure.

   codegraph context <symbol> -T --file <path>
   codegraph deps <file> -T --brief
   codegraph deps <file> -T --json
   codegraph exports <file> -T
   codegraph path <symbol-from> <symbol-to> -T
   codegraph dataflow <symbol> -T --file <path>
   

   For concise dependency summaries, prefer deps --json and extract results[0].imports / results[0].importedBy instead of dumping every symbol consumer. For cycles, this is the primary way to prove which imports create each file edge.

   For contract work, trace the spine as separate evidence: schema/type definition, method string or RPC tag, protocol/group assembly, server handler, client runtime wrapper, and app-surface adapters. If CodeGraph loses an edge at any spine segment, use a targeted exact search for that segment only, then read the narrowed files. Record the spine in the three ledgers.

Branches

• Repo explanation: run the scout loop, then read package manifests and narrowed entrypoints. Use codegraph deps <entrypoint> -T --json, codegraph cycles -T | head, and codegraph complexity -T --above-threshold --limit 20. Explain the repo as layers: workspaces, runtime entrypoints, shared contracts/runtime, main flows, hotspots, and caveats. Completion criterion: every major workspace and cross-workspace dependency path is accounted for with CodeGraph output or source reads.

• Targeted navigation: use where, brief, deps, and narrowed source reads to answer “where is this?” or “who owns this?” Completion criterion: every named target has an exact path/line and the owning module is identified.

• Diagnosis: start from the reported symbol/file/entrypoint, trace with context, deps, path, and source reads; use flow, sequence, or cfg only when control flow matters. If the report is scenario-led rather than symbol-led, first scout the likely layer directories with structure, then pin candidates with brief/deps before any exact search. Completion criterion: the suspected path from symptom to responsible code is explicit, unresolved forks and CodeGraph blind spots are named, and the three ledgers are complete.

• Blast radius and migration: for shared functions, types, interfaces, schemas, or RPC methods, combine where, exports, fn-impact, impact, interfaces, and implementations. Completion criterion: callers, dependents, implementers, and transitive risks are accounted for before editing.

• Contract/RPC migration: first scout the contract package with structure, exports, deps, and where; pick one concrete method/schema, not a whole surface. Then trace the spine: backing schema/type → method constant/string → RPC/schema registration → protocol/client factory → client-runtime state/RPC wrapper → server handler/service → app imports/call sites. Run impact once with -T for application blast radius and once including tests for test candidates. Use targeted exact search only where CodeGraph cannot see dynamic keys, interface properties, generated protocol types, or string dispatch; exclude generated files until you need to confirm schema/method existence. Completion criterion: the report names the chosen contract, server handler/service, client-runtime dependency, affected app surfaces, highest-risk files/functions, validation commands, and dynamic risks CodeGraph may miss.

Read COMMANDS.md when you need the command atlas, rare branches, output modes, or known CLI quirks.

Reporting language

• Say: “rebuilt the CodeGraph index,” “stats show…,” “diff-impact shows…,” or “structural check found…”.
• Do not say: “CodeGraph passed,” “build passed,” or “validated” unless the project’s real validation commands also passed.

Rules of thumb

• Prefer -T / --no-tests while scouting application code; rerun without -T or with the supported include-tests flag when test coverage or test-only callers matter.
• Use codegraph help <command> before relying on any flag not named in this skill.
• Use CodeGraph before broad grep/read, not instead of reading. The map narrows the work; source files and tests prove it.
• Let CodeGraph make the edit smaller, not more elaborate. After scouting, preserve the existing public shape and closest behavioral seam unless source reads prove a broader change is necessary.
• In reports, use the three ledgers. Do not let targeted search become a substitute for the initial structural scout.
• If output is stale, low-quality, or missing relationships, rebuild before trusting it. Use --no-incremental only when the incremental graph looks corrupt.
• If MCP is configured, you may use it; otherwise run the CLI through bash.