codegraph-diagram

name	codegraph-diagram
description	[PRE-ALPHA] Generate a Mermaid flowchart of a code subgraph centered on a function, class, or module. Runs `vco codegraph-diagram` under the hood, writes the .mmd to .claude/diagrams/codegraph/ so it's indexed for hybrid_search, and gives a 3-5 line summary plus a link to open it in the launcher's DiagramsTab. Output may be incomplete, inaccurate, or visually broken — always tell the user to verify against the source code before sharing. Use when the user asks "show me a call graph for X", "what does Y depend on", "draw the inheritance chain rooted at Z", or any other request that maps to a small-to-medium subgraph extraction from the code graph.
short_desc	[PRE-ALPHA] auto-generate a Mermaid call/import/extends graph from a seed symbol
keywords	["code graph","Mermaid","call graph","dependency diagram","class hierarchy","architecture diagram","show me a call graph","what does X depend on"]
argument-hint	<symbol> [--hops N] [--scope calls|imports|extends|composes|interactions|all]
model	inherit
effort	medium

/codegraph-diagram

⚠️ PRE-ALPHA. The codegraph→Mermaid pipeline is experimental. Output may be incomplete (graph traversal skips edges the schema doesn't yet capture), inaccurate (heuristic seed resolution can pick the wrong symbol when names collide), or visually broken (Mermaid auto-layout degrades past ~50 nodes even when the data is clean). Always tell the user to verify the diagram against the source code before sharing it or making decisions from it. File-, schema-, and pipeline-level bugs are expected; report surprising behaviour rather than working around it silently.

Generate a Mermaid flowchart TD of a subgraph rooted at one code symbol, write it to .claude/diagrams/codegraph/<sanitised>.mmd, index it so hybrid_search finds it later, and give a quick summary the user can read before opening the rendered diagram in the launcher.

Inputs

Arg	Required	Meaning
<symbol>	yes	A code entity. Resolved in order: CodeFunction.full_name → CodeClass.full_name → CodeModule.path. Pass exactly what query_code_structure would accept.
--hops N	no	BFS depth (default 2, max 3). Beyond 3 the auto-layout devolves into a "ball of yarn"; the CLI rejects higher values.
--scope	no	Which edges to follow (default calls): calls, imports, extends, composes, interactions, or all. See Scope guide below.
--max-nodes N	no	Soft cap (default 50 — the empirical Mermaid auto-layout knee). The CLI truncates and warns when traversal would exceed the cap.
--no-modules	no	Skip per-module subgraph grouping. Useful for tiny diagrams.
--title TEXT	no	Override the auto-derived title (default: the resolved seed's full_name).
--output PATH	no	Override the default output path (./.claude/diagrams/codegraph/<sanitised>.mmd). Anything outside .claude/diagrams/ is written but NOT indexed.
--print	no	Write to stdout instead of a file. Skips indexing.
--project NAME	no	Override the code-graph project name (otherwise resolved via the launcher).

If invoked with no arguments, ASK the user for a seed symbol before doing anything. Don't guess — picking the wrong seed produces an off-topic diagram that wastes the user's time.

What you do

1. Run the CLI via Bash:

   vco codegraph-diagram "<symbol>" --hops <N> --scope <scope> --json
   

   Always use --json so you can parse the result deterministically. The exit code carries the success/failure signal:
   • 0 — diagram written and (when under .claude/diagrams/) indexed.
   • 1 — render error (Weaviate query failed mid-flight, file write failed, or indexer raised — diagram may or may not exist).
   • 2 — env problem (Weaviate down, seed not in the code graph, project unresolvable).
2. Read the resulting .mmd file (path is in the JSON payload's path field).
3. Produce a short summary for the user:
   • First line: a PRE-ALPHA caveat. "⚠️ codegraph→Mermaid is pre-alpha; verify against source before trusting." Don't skip this — even on a clean render the pipeline can quietly miss edges.
   • One line on the seed: kind + full name.
   • One line on the scope + counts: "12 nodes, 18 edges across 3 modules".
   • One line on truncation if truncated=true: "truncated at ".
   • One pointer: "open in the launcher's DiagramsTab for an embedded render".
   • If exit was 2 with seed_not_found: suggest running search_code_graph("<concept>") first to discover the right full_name, then re-run with the corrected seed.

Keep the whole reply under 9 lines (8 + the caveat) unless the user explicitly asks for a deeper walk-through. The diagram itself is the answer — the summary is a navigation aid.

Scope guide

Scope	Use when	What you get
calls (default)	"what does function X call?"	Outbound call graph from a function. Edges = calls.
imports	"what does module M depend on?"	Outbound import graph from a module. Edges = imports.
extends	"what's the inheritance chain of class C?"	Base classes recursively. Edges = extends.
composes	"what classes does C hold as fields?"	Composition relationships. Edges = composes.
interactions	"what external services does X call?"	Cross-service HTTP/gRPC/MQ calls. Edges = interacts. Each remote endpoint shows up as a leaf node labelled <protocol> <endpoint>.
all	"show me everything around X"	Fan-out across every scope above. Hits the 50-node cap fast on busy entities — pair with --max-nodes 30 to keep it readable.

The 50-node cap

Mermaid's flowchart TD auto-layout starts crossing edges chaotically past ~50 nodes; past 100 it's unusable. The CLI defaults to --max-nodes 50 and TRUNCATES rather than producing a broken diagram. When you see truncated=true in the JSON, tell the user to:

• Narrow scope (--scope calls instead of --scope all).
• Reduce hops (--hops 1 instead of --hops 3).
• Or split the request into multiple seed-rooted diagrams.

Don't bump --max-nodes past the default unless the user explicitly asks; the cap exists for a reason.

Examples

/codegraph-diagram vco_lib.diagram_indexer.index_diagram
/codegraph-diagram vco_lib.codegraph_to_mermaid.fetch_subgraph --hops 1
/codegraph-diagram api.UserManager --scope extends
/codegraph-diagram launcher/src-tauri/src/main.rs --scope imports --hops 2
/codegraph-diagram api.routes.serve_request --scope interactions
/codegraph-diagram vco_lib.cli --scope all --hops 1 --max-nodes 30

What you don't do

• Don't try to "see" the diagram. The Mermaid file is text and the user opens the visual in their browser or the launcher.
• Don't bump --hops above 3 hoping for more context — the CLI rejects it and rightly so.
• Don't write to a path outside .claude/diagrams/ unless the user explicitly asks for --output. Anywhere else and hybrid_search won't find the diagram later.
• Don't re-derive the call graph by reading source files when you could query the code graph — that's what this tool exists to short-circuit.