Codegraph

codegraph

Codegraph is a small multi-language code analysis library and CLI for understanding repos quickly. It builds dependency graphs, symbol indexes, go-to-definition results, find-references results, semantic chunks, architecture drift reports, and PR review and impact artifacts across source languages plus graph-first document, stylesheet, and template formats.

It is built for agent and human workflows that need repo structure fast without standing up a full editor or LSP stack.

Table of contents

• [Why Codegraph](#why-codegraph)
• [Features](#features)
• [Quick start](#quick-start)
• [CLI examples](#cli-examples)
• [Key output examples](#key-output-examples)
• [Agent setup](#agent-setup)
• [Using as a library](#using-as-a-library)
• [Common workflows](#common-workflows)
• [Supported languages](#supported-languages)
• [Documentation](#documentation)
• [Installation options](#installation-options)
• [FAQ](#faq)
• [Contributing and releases](#contributing-and-releases)

Why Codegraph

Use Codegraph when you need fast structural answers about a repo without relying on a full editor session or language-server setup.

• Triage an unfamiliar codebase with one pass that highlights hotspots, unresolved imports, cycles, and next commands to run.
• Review diffs with changed symbols, graph deltas, likely regression tests, and risk signals that agents or humans can consume directly.
• Export graph data as JSON, Mermaid, DOT, or SQLite, then inspect it from scripts, Markdown renderers, Graphviz, or SQL tools.
• Keep one workflow across source languages, monorepos, and graph-first document and template formats instead of stitching together separate tools.

For unfamiliar repos with a concrete question, start with explore "how does auth reach db?" --root . --pretty; use orient --root . --budget small --pretty when you need a map before asking a question. For daily change work, start with review --base HEAD --head WORKTREE --summary; use impact --base HEAD --head WORKTREE --pretty as the broader blast-radius map when needed. Search is code-first by default in hybrid mode, and explore, search, explain, and review packets include analysis labels so reduced-mode or mixed-semantics runs stay visible. Detailed command contracts and JSON shapes live in [docs/cli.md](./docs/cli.md).

Features

• Multi-language dependency graphs, including imports, re-exports, require(), dynamic imports, workspace resolution, document links, stylesheet imports, and SFC script dependencies.
• Per-file symbol indexes with locals, exports, docstrings, line spans, and lightweight complexity metadata.
• Cross-file go-to-definition and find-references support across the shared source-language pipeline.
• Deterministic agent exploration, orientation, packet retrieval, search, bounded explanations, portable artifact bundles, and MCP tools across files, symbols, chunks, SQL objects, graph neighborhoods, and review ranges with stable follow-up targets.
• Semantic chunking for code and text files, including Vue and Svelte single-file component block splitting.
• Duplicate and near-duplicate detection over indexed symbols, semantic chunks, text chunks, token fingerprints, and AST shape hashes when parser context is available.
• AST grep, public API summaries, unresolved import reports, hotspot analysis, cycle detection, and shortest dependency paths.
• PR impact analysis and review bundles that map diffs to changed symbols, impacted code, likely tests, graph deltas, and conservative provider-backed call-arity hints after signature changes.
• SQL language support for .sql files, including statement chunks, object symbols, SQL-to-SQL graph edges, SQL navigation, and statement facts.
• SQLite export plus read-only SQL access for downstream tools and agent workflows.
• Native Tree-sitter parsing by default when a matching prebuilt is available, with reduced graph-only and regex recovery when native is unavailable.

Sample graph output can be generated with npm run graph:mermaid, npm run graph:dot, or npm run graph:json.

This repo keeps test fixtures out of default Codegraph scans with codegraph.config.json:

{
  "discovery": {
    "ignoreGlobs": ["tests/samples/**", "tests/languages/samples/**"]
  }
}

Use this pattern in other repos when large fixture, generated, or vendored trees should not participate in search, unresolved-import checks, graphing, indexing, inspect, impact, or review runs. Config globs are project-root-relative. CLI --include-glob and --ignore-glob stay relative to each active scan root.

Quick start

Requirements: Node.js 24.10+.

For contributors and first-time evaluation, start from a local source checkout:

git clone https://github.com/lzehrung/codegraph.git
cd codegraph
npm install
npm run build

npm run build always rebuilds dist/. If Cargo is available, it also requires the local native workspace build to succeed; if Cargo is unavailable, it still completes with the JavaScript build output and a warning.

Then start with the default workflow. For code reviews, the lowest-friction loop is review --summary first, impact --pretty only when you need blast radius, then search or explain on a file or symbol named in the summary; use review JSON when a follow-up needs stable handles.

# compact reviewer handoff for current edits
node ./dist/cli.js review --base HEAD --head WORKTREE --summary

# broader blast-radius map when the review packet needs expansion
node ./dist/cli.js impact --base HEAD --head WORKTREE --pretty

# one-call answer for a concrete repo question
node ./dist/cli.js explore "how does auth reach db?" --root . --pretty

# bounded repo orientation with next-step suggestions
node ./dist/cli.js orient --root . --budget small --pretty

# find and explain a concrete anchor
node ./dist/cli.js search "build review report" --json
node ./dist/cli.js explain src/cli.ts

# optional runtime and artifact health check
node ./dist/cli.js doctor

# optional broader architecture summary
node ./dist/cli.js inspect ./src --limit 20

# build a graph for product code
node ./dist/cli.js graph --root . ./src --compact-json --output codegraph.json

# inspect public API surface
node ./dist/cli.js apisurface

# find duplicate and near-duplicate code
node ./dist/cli.js duplicates ./src --min-confidence medium --limit 20

# compare architecture drift between refs
node ./dist/cli.js drift ./src --base origin/main --head HEAD --compact-json
node ./dist/cli.js drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals

If you install the published CLI instead of using a source checkout, replace node ./dist/cli.js with codegraph.

Small orientation packets skip deeper health analysis and record that omission; use --budget medium or --budget large when health counts matter.

CLI examples

Choose output by consumer:

• Use --pretty or --summary when a person or model needs a compact triage view.
• Use --json or library APIs when a script, tool wrapper, or follow-up command needs stable fields.

Use these as starting points, then see [docs/cli.md](./docs/cli.md) for all flags, defaults, and output contracts.

# fastest code-review handoff for current edits
codegraph review --base HEAD --head WORKTREE --summary
codegraph impact --base HEAD --head WORKTREE --pretty

# repo question, orientation, and bounded follow-up
codegraph explore "how does auth reach db?" --root . --pretty
codegraph orient --root . --budget small --pretty
codegraph search "build review report" --json
codegraph explain src/review.ts

# semantic navigation
codegraph goto   
codegraph refs --file src/index.ts --line 12 --col 17 --pretty

# architecture and review
codegraph drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals
codegraph drift ./src --base origin/main --head HEAD --compact-json
codegraph impact --base origin/main --head HEAD --pretty
codegraph review --base origin/main --head HEAD --summary

# duplicate and graph exploration
codegraph duplicates ./src --json --min-confidence medium --limit 20
codegraph graph --root . ./src --compact-json --output codegraph.json

See [docs/cli.md](./docs/cli.md) for full flags, JSON shapes, drift policy gates, duplicate scopes, and review output details.

Key output examples

These excerpts show the shape of the outputs agents and humans usually consume. Use --pretty or --summary for triage, and switch to JSON when a follow-up command needs stable handles, paths, ranges, reasons, or counts.

Orientation

orient --root . --budget small --pretty gives first-turn focus targets plus copyable follow-ups:

Summary
- 567 file(s) in scope.
- 5 graph-central module(s) ranked for first follow-up.
- Health analysis skipped for small budget.

Start here
- src/index.ts: graph-central module: fan-in 96, fan-out 40, score 232
  - codegraph packet get src/index.ts --pretty
  - codegraph explain src/index.ts

Recommended next
- codegraph hotspots . --limit 20
- codegraph impact --base HEAD --head WORKTREE --pretty
- codegraph review --base HEAD --head WORKTREE --summary
- codegraph search  --json

Search

search "graph json" --json returns ranked, explainable anchors. Follow-up commands reuse the returned handle, file, or symbol path:

{
  "schemaVersion": 1,
  "query": "build review report",
  "mode": "hybrid",
  "analysis": {
    "label": "native semantic"
  },
  "resultCount": 1,
  "totalCandidates": 42,
  "results": [
    {
      "handle": "symbol:src%2Freview.ts:buildReviewReport:214:1",
      "kind": "symbol",
      "label": "buildReviewReport",
      "file": "src/review.ts",
      "score": 248,
      "provenance": {
        "surface": "code",
        "capability": "semantic",
        "analysisMode": "semantic",
        "backend": "native",
        "confidence": "high"
      },
      "rankReasons": ["exact phrase match in symbol name", "symbol token match: build, review, report"],
      "followUps": [
        "codegraph explain \"symbol:src%2Freview.ts:buildReviewReport:214:1\"",
        "codegraph refs --file src/review.ts --line 214 --col 1 --pretty"
      ]
    }
  ]
}

Impact

impact --base HEAD --head WORKTREE --pretty answers what changed and what else can break. Pretty output keeps severity and reason labels visible:

Impact Analysis Report
======================
Changed files: 1
Changed symbols: 1
Impacted items: 2

utils.ts: defaultExport (reason: direct reference, severity: 100.0%)
main.ts: defaultExport (reason: transitive dependency, severity: 72.0%)

Use --compact-json when tooling needs normalized arrays, graph edges, diagnostics, and schemaVersion:

{
  "schemaVersion": 1,
  "format": "compact",
  "files": ["utils.ts", "main.ts", "dynamic-import.ts", "helpers.ts", "tsconfig.json"],
  "changedFiles": [{ "file": 0, "kind": "modified", "hunks": [{ "start": 28, "end": 38 }] }],
  "changedSymbols": [{ "file": 0, "name": "defaultExport", "kind": "function", "exported": true }],
  "impacted": [
    { "file": 0, "symbols": ["defaultExport"], "reasons": ["directRef"], "severity": 1 },
    { "file": 1, "symbols": ["defaultExport"], "reasons": ["importAlias", "transitive"], "severity": 0.72 }
  ]
}

Review

review --base HEAD --head WORKTREE --summary is the compact reviewer handoff. It combines changed files, changed symbols, candidate tests, risk signals, review tasks, duplicate leads, and call-compatibility hints when a supported signature change has resolvable callsites:

Review Summary
==============
Status: ok
Files changed: 5
Symbols changed: 22
Candidate tests: 1 (high: 1, medium: 0, low: 0)
Risk: high (80)
Signals: exported-symbols-changed, many-symbols-changed

Changed files:
- src/invoices-a.ts: updated (label, output, rounded, subtotal, summarizeInvoices)
- src/invoices-b.ts: updated (label, output, rounded, subtotal, summarizeInvoices)
- src/orders-a.ts: updated (label, output, rounded, subtotal, summarizeOrders)
- src/orders-b.ts: updated (label, output, rounded, subtotal, summarizeOrders)
- src/pricing.ts: updated (calculateTotal, discounted)

Candidate tests:
High-confidence tests:
- tests/pricing.test.ts: importsChanged

Review tasks:
- review-summary: medium - Review changed symbols (baseline-review)
- api-compat: high - Verify API compatibility (exported-symbols-changed)
- high-change-volume: high - Assess change scope (large-change-set)
- duplicate-sibling-check:d9a0ad66c9cb5610: high - Check related duplicate implementation (duplicate-sibling)
- duplicate-sibling-check:a9188e0046912ef6: high - Check related duplicate implementation (duplicate-sibling)

Call compatibility:
- calculateTotal: src/checkout.ts:3 passes 2 arguments; new signature requires 3.
- calculateTotal: tests/pricing.test.ts:2 passes 2 arguments; new signature requires 3.

Duplicate leads:
- src/invoices-a.ts:1-10 matches src/invoices-b.ts:1-10 (exact, score 100).
- src/orders-a.ts:1-10 matches src/orders-b.ts:1-10 (exact, score 100).
- src/invoices-a.ts:1-10 matches src/orders-a.ts:1-10 (renamed, score 100).
- omitted: 1 by budget, 24 hidden evidence items

Dependency graph

For a small dependency slice, Mermaid output can be pasted directly into Markdown renderers that support Mermaid:

flowchart LR
f0["utils.ts"]
f1["main.ts"]
s0["utils.ts:defaultExport"]
f1 --> f0
f0 --> s0

For full-repo exploration, generate a portable graph artifact for scripts or downstream tools:

codegraph graph --root . ./src --compact-json --output codegraph.json
codegraph graph --root . ./src --mermaid --output graph.mmd
codegraph graph --root . ./src --dot --output graph.dot

Agent setup

Using a local agent client? The top-level installer configures Codegraph-owned MCP entries, bundled skill payloads, and marker files for supported clients, while preserving existing user config:

codegraph install --target codex,claude --dry-run
codegraph install --target codex,claude --yes
codegraph install --print-config codex
codegraph uninstall --target codex --yes

Supported installer targets are codex, claude, cursor, gemini, opencode, and agents. Writes require --yes; --dry-run previews files, and uninstall removes only Codegraph-owned marker blocks, marker files, exact bundled skill payloads, or exact installer-owned MCP entries.

Using a skill-aware agent only? Install the bundled skill directly so repo navigation, semantic references, dependency tracing, and PR impact questions route to Codegraph automatically:

# Codex CLI: ${CODEX_HOME:-~/.codex}/skills/codegraph
codegraph skill install --agent codex

# Claude Code: ~/.claude/skills/codegraph
codegraph skill install --agent claude

# Universal agent skills: ~/.agents/skills/codegraph
codegraph skill install --agent agents

# Cursor CLI: ~/.cursor/skills/codegraph
codegraph skill install --agent cursor

# Gemini CLI: ~/.gemini/skills/codegraph
codegraph skill install --agent gemini

# OpenCode: ~/.config/opencode/skills/codegraph
codegraph skill install --agent opencode

For a custom skill location, use codegraph skill install --target /skills/codegraph; the target must end with skills/codegraph, and the installer creates the directory as needed. Cursor CLI supports native skills directories too, so .cursor/skills/codegraph works alongside the universal ~/.agents/skills/codegraph location. To inspect the packaged skill paths and target health, run codegraph skill doctor.

Using as a library

Use the TypeScript API when another program needs deterministic explore responses, file packs, review packets, or model prompts. CLI --pretty and --summary output is also useful for model-readable triage, but library callers should keep structured fields until the final UI or prompt boundary. For repeated calls, prefer one warm `createCodeReviewSession(

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lzehrung
• Source: lzehrung/codegraph
• License: MIT

Install and usage instructions live in the source repository linked above.