Code Graph

Code graph

Language: English · 简体中文

LWC integrates a pinned CodeGraph runtime for structural questions about checked-out code. It maps files, symbols, definitions, calls, and dependencies so an Agent can locate the smallest relevant source surface before reading exact files.

The code graph is independent from the document knowledge graph. One models source code structure; the other models Wiki Pages, Sources, citations, and semantic relations. Enable and verify them separately.

When to use it

Use CodeGraph for:

• symbol definitions and signatures;
• callers and callees;
• source and test dependencies;
• file topology;
• structural exploration around a feature;
• change impact before editing a shared symbol.

Use rg for literal text, comments, log strings, configuration keys, and one-file edits already proven by exact search. CodeGraph complements source reading; it does not replace it.

Runtime and project index

LWC separates installation from indexing:

pinned runtime -> installed once globally per version and platform
project index  -> stored separately in each project's .lwc/codegraph

The first project that runs cg init may download the verified pinned runtime. Later projects reuse that global runtime, but each project builds and maintains its own index. An update downloads a new pinned version; normal project initialization does not repeatedly download the same runtime.

LWC does not invoke an arbitrary codegraph from PATH. It disables telemetry and owns the project-local index path.

Check readiness first

lwc --scope project cg status

status is read-only and separates runtime availability from project index initialization. An existing, user-authorized index can be queried without new consent.

If the runtime or project index is missing, explain the download, local index, and storage effects before asking once for consent. Detection alone is not permission to download or index code.

Initialize

After consent:

lwc --scope project cg init
lwc --scope project cg status

Use --verbose only when detailed indexing progress is useful. Initialization is complete only when status reports an installed healthy runtime and initialized=true for the current project.

Never pass another project path through the wrapper, point it at an unrelated working tree, or edit .lwc/codegraph directly.

Query workflow

Start with a symbol search:

lwc cg query "checkpoint restore" --limit 10
lwc cg node checkpoint_restore
lwc cg callers checkpoint_restore --limit 20
lwc cg callees checkpoint_restore --limit 20

• query searches indexed symbols and can filter by symbol kind.
• node returns one symbol's source plus caller and callee context; with --file, it reads a bounded line-numbered file window.
• callers answers “who calls this?”
• callees answers “what does this call?”

Disambiguate common symbol names with exact files or follow the indexed locations into the checkout. Do not make a final implementation claim from a symbol name alone.

Explore and inspect topology

lwc cg explore "checkpoint recovery"
lwc cg files --filter src/store --format tree --max-depth 3
lwc cg impact checkpoint_restore --depth 2
lwc cg affected src/store/checkpoints.rs

• explore combines relevant symbols, source, and call paths for one area.
• files shows indexed file structure with optional directory and glob filters.
• impact traverses code affected by a symbol change.
• affected identifies tests affected by changed source files.

Keep limits and depth bounded. Use the graph to locate candidate files, then read the exact checked-out implementation and its tests.

Keep dirty code current

The index may lag behind uncommitted edits. When a task depends on current dirty code, synchronize before the first structural query, after relevant code changes, and before a final structural claim:

lwc --scope project cg sync
lwc --scope project cg status

CodeGraph reconciles files with document-granular transactions. A successful sync updates the project index; it does not commit Git changes or write LWC Wiki knowledge.

MCP integration

lwc serve --mcp exposes CodeGraph through the single read-only lwc_explore tool. Use mode=code for code-only exploration or mode=all when both Wiki memory and code structure matter.

MCP never initializes the runtime or project index. When CodeGraph is unavailable, it returns readiness guidance and requires an explicit CLI cg init outside the read-only tool.

Safety boundaries

• Index only the current authorized project root.
• Treat checked-out source as current implementation evidence when Wiki memory differs.
• Do not ingest the CodeGraph database as a Wiki Source.
• Do not edit, copy between projects, or remove the index database manually.
• Do not mistake index success for build, test, or runtime verification.
• Run native tests and inspect exact code before claiming a change is safe.

Completion evidence

CodeGraph use is complete when:

• cg status reports the expected pinned runtime and initialized project index;
• the index was synced after relevant dirty changes;
• structural queries identified the relevant symbols and files;
• exact checked-out source and tests confirmed the final claim;
• the project-local index remained inside .lwc/codegraph with telemetry disabled.

Next: Word graph