Codegraph

Give your coding agent a map of the repository, not a pile of search results.

Codegraph is a local CLI and TypeScript library that turns a source tree into a resolved model of files, symbols, references, and dependencies. Agents and humans can ask where an implementation lives, how components connect, what a change can break, and which tests are likely relevant - then get bounded source evidence and copyable next steps.

Without structural context, an agent spends early turns listing directories, guessing search terms, opening candidate files, and reconstructing relationships in its prompt. Codegraph performs that deterministic discovery once so more of the context window can go toward understanding and changing the code.

Windows PowerShell:

irm https://github.com/lzehrung/codegraph/releases/latest/download/install.ps1 | iex

macOS or glibc-based Linux:

curl -fsSL https://github.com/lzehrung/codegraph/releases/latest/download/install.sh | sh

Then configure an agent and ask the first question:

codegraph install
codegraph explore "how does auth reach the database?" --root .

Use Codegraph alongside text search and compilers: text search finds exact strings, compilers prove language behavior, and Codegraph supplies the cross-file repository map between them. See Installation for standalone, package, and source-checkout paths.

Table of contents

• What you can do
• Try it
• A useful first five minutes
• What the output looks like
• Why Codegraph
• Why not just grep or an LSP?
• Agent setup
• Language support
• Using as a library
• How it works
• Limits and tradeoffs
• Documentation
  • CLI
  • Publishing
• Contributing

What you can do

Question	Start here	What comes back
"Where should I start in this repo?"	codegraph orient --root . --budget small	Central modules, a bounded tree, and copyable follow-ups
"How does this feature work?"	codegraph explore "<question>" --root .	Ranked anchors, source packets, dependency paths, blast radius, and likely tests
"What could this change break?"	codegraph review --base HEAD --head WORKTREE --summary	Changed symbols, risk signals, candidate tests, duplicate leads, and review tasks
"What depends on this file?"	codegraph rdeps src/file.ts --json	Reverse dependencies from the resolved project graph
"Where is this symbol defined or used?"	codegraph goto <file> <line> <column> and codegraph refs ...	Semantic definitions and references across supported languages
"Which declaration matches this name?"	codegraph symbols "CodeReviewSession" --root .	Ranked symbols with portable handles, exact ranges, provenance, and omissions
"What evidence do I need before a refactor?"	codegraph refactor-plan <symbol-target>	References, call and type relationships, candidate tests, omissions, and copyable follow-ups
"Is the architecture drifting?"	codegraph drift ./src --base origin/main --head HEAD	New cycles, hotspot changes, unresolved imports, API changes, and graph deltas
"Where is code duplicated?"	codegraph duplicates ./src --min-confidence medium	Ranked exact and near-duplicate groups with locations and confidence
"Can another tool consume the graph?"	codegraph graph --root . ./src --compact-json --output codegraph.json	JSON, Mermaid, DOT, or SQLite output

Human-readable output is the CLI default; --pretty remains an explicit equivalent and --summary selects compact report output where supported. Use --json for stable fields, ranges, handles, reasons, confidence, and omission counts in automation.

Try it

Requirement: Package and source installs require Node.js 22.16 or newer. Standalone archives bundle Node.js.

Standalone archive

The preview standalone channel bundles Node.js, the CLI, production dependencies, the matching native runtime, and the Codegraph skill. Its bootstrap verifies the selected archive against the release SHA256SUMS before extraction: Standalone assets are attached by a separate post-release workflow, so use a release that lists the archive and installer assets.

irm https://github.com/lzehrung/codegraph/releases/latest/download/install.ps1 | iex

curl -fsSL https://github.com/lzehrung/codegraph/releases/latest/download/install.sh | sh

Both commands preview the target and user-owned install paths, then default to no. Noninteractive automation must download the script and pass -Yes on PowerShell or --yes on POSIX.

See Installation for supported targets, inspect-before-run commands, version pinning, install roots, and rollback.

From a source checkout

This is the least ambiguous way to evaluate the current repository:

git clone https://github.com/lzehrung/codegraph.git
cd codegraph
npm install
npm run build
node ./dist/cli.js doctor
node ./dist/cli.js orient --root . --budget small

Continue with node ./dist/cli.js <command> from the checkout. To use the bare codegraph examples below unchanged, run npm install -g . after the build, then codegraph doctor and codegraph install --all --dry-run.

From GitHub Packages

After authenticating to GitHub Packages with a classic token that has read:packages (setup):

npm login --scope=@lzehrung --auth-type=legacy --registry=https://npm.pkg.github.com
npm config set "@lzehrung:registry" "https://npm.pkg.github.com"
npm install -g @lzehrung/codegraph
codegraph doctor
codegraph install --all --dry-run
codegraph install --all --yes

Published package installs resolve the optional native runtime automatically when a compatible artifact exists. See Installation for registry setup, npm tarballs, standalone releases, local global installs, and native runtime modes.

On Windows, installed releases load the native addon from a verified per-user cache so long-running MCP servers do not keep npm's package copy mapped. The first upgrade from an older direct-loading release still requires one stop-update-restart cycle; see Updating on Windows.

A useful first five minutes

Do not begin by generating every possible report. Start with the question you actually have.

Understand an unfamiliar repo

# Ask one concrete architecture question
codegraph explore "how does the CLI reach review analysis?" --root .

# If you do not know the question yet, get a bounded map
codegraph orient --root . --budget small

# Follow an anchor returned by either command
codegraph explain src/review.ts
codegraph deps src/review.ts --json
codegraph refs src/review.ts:215:23

Review local changes

# Compact reviewer handoff for staged and unstaged tracked changes
codegraph review --base HEAD --head WORKTREE --summary

# Broader blast-radius map when the summary needs expansion
codegraph impact --base HEAD --head WORKTREE

Use --head STAGED to compare HEAD with the index, or use refs such as --base origin/main --head HEAD for a branch review.

Inspect repository health

codegraph inspect ./src --limit 20
codegraph cycles --sort priority
codegraph unresolved
codegraph apisurface
codegraph duplicates ./src --min-confidence medium --limit 20
codegraph drift ./src --base origin/main --head HEAD --graph-edges summary --public-api removals

Export the model

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
codegraph graph --root . ./src --sqlite codegraph.sqlite

What the output looks like

Because ranking and counts change with the working tree, this abbreviated explore excerpt shows the stable response structure rather than snapshot-specific totals:

Anchors
- buildReviewReport [symbol] src/review.ts
- src/cli/help.ts:1 [chunk] src/cli/help.ts
- ReviewPreset [symbol] src/review.ts

Relevant source
- buildReviewReport is defined in src/review.ts.
- References, dependencies, and dependents are summarized here.

Blast radius
- src/review.ts: src/index.ts, src/cli/review.ts, src/mcp/server.ts, ...

Candidate tests
- tests/agent-explain.test.ts
- tests/agent-explore.test.ts
- tests/agent-packet.test.ts

Follow-ups
- codegraph file src/review.ts
- codegraph refs src/review.ts:215:23

Limits
- anchors, packets, paths, blast radius, reverse dependencies, and candidate tests

Recommended next: codegraph file src/review.ts

Real output includes counts, copyable follow-ups, explicit limits, and omission counts. It does not pretend omitted context was analyzed.

A worktree review is optimized for a different job:

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

Structured output carries the underlying changed files, symbols, graph edges, reasons, diagnostics, snippets, and candidate-test confidence instead of requiring a caller to parse this display text.

Why Codegraph

Spend context on the problem, not repository discovery

One bounded explore response can combine ranked anchors, relevant source, dependency paths, blast radius, candidate tests, and next commands. The agent gets an evidence-backed starting point without first dumping the tree or repeatedly guessing which files to open.

Ground the next action

Results carry source paths, symbol ranges, stable handles, rank reasons, graph relationships, confidence, and omission counts. An agent can inspect why something ranked, jump to the definition or references, and continue from an exact target instead of treating a fuzzy match as an answer.

Reuse one map from discovery through review

Search, navigation, dependency analysis, impact, and review share the same graph and semantic index. The target found during discovery can flow directly into explain, refs, deps, impact analysis, and candidate-test selection.

Work across the repository an agent actually has

Source code, SQL, workspace packages, documentation links, stylesheets, templates, and single-file components can participate in one repository model. Capability claims remain language-specific, so graph support is not presented as full compiler or language-server parity.

Keep the evidence local and reusable

Codegraph runs locally through a CLI, library, or MCP server. People can read pretty output; agents and programs can keep structured JSON, stable handles, warm sessions, SQLite data, or graph exports without parsing display text.

Why not just grep or an LSP?

Codegraph complements both.

• Use text search for exact strings, logs, config keys, and prose.
• Use a compiler or language server when you need compiler-grade type analysis, overload resolution, dynamic dispatch, or editor refactors.
• Use Codegraph when the question crosses files, languages, dependency edges, a git diff, or an agent context boundary.

The useful distinction is evidence shape, not a claim that one tool replaces every other tool.

Agent setup

Run codegraph install on an interactive terminal to detect supported clients, preview exact Codegraph-owned changes, and confirm once. Use --all when you intentionally want the complete current catalog without detection:

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

Supported target ids are codex, claude, cursor, gemini, opencode, omp, kilo, and agents (universal agent skills). OMP uses .omp/agent/managed-skills/codegraph; Kilo uses .kilocode/skills/codegraph plus its comment-preserving JSONC MCP config. Interactive writes default to no; noninteractive writes require --yes, and uninstall removes only Codegraph-owned content. --all cannot be combined with target selection, --detect, or --print-config.

For a skill without MCP configuration:

codegraph skill install --agent codex
codegraph skill install --agent claude
codegraph skill install --agent cursor

See Agent workflows for exploration strategy, warm sessions, streaming, review loops, and tool wrappers. See MCP for server and client configuration.

Language support

Shared source-language indexing and navigation: JavaScript, TypeScript, Python, PHP, Go, Java, C#, Ruby, Rust, Kotlin, Swift, Zig, C, and C++.

SQL: statement chunking, object symbols, common DDL/DML and CTE facts, SQL-to-SQL edges, and object-level navigation. Codegraph does not claim column-definition resolution.

Graph-first formats: HTML, Astro, Handlebars, Markdown, MDX, reStructuredText, AsciiDoc, CSS, SCSS, and Less have narrower graph or chunking support.

Single-file components: Vue and Svelte script blocks participate in dependency graphs and chunking; semantic navigation is narrower.

See Language parity for the capability matrix and Scenario catalog for the fixtures behind those claims.

Using as a library

Use the TypeScript API when another program needs structured results or a warm, reusable session:

import { buildProjectIndex, analyzeImpactFromDiff } from "@lzehrung/codegraph";

const root = process.cwd();
const index = await buildProjectIndex(root, { native: "auto" });

const impact = await analyzeImpactFromDiff(root, index, {
  provider: "git",
  base: "HEAD",
  head: "WORKTREE",
  detectBreakingChanges: true,
});

console.log(impact.changedSymbols, impact.impacted);

Keep structured fields until the final UI or prompt boundary. Repeated callers should prefer one warm createCodeReviewSession() or agent/MCP session; see the Library API reference for exports, session lifecycle, streaming, graph APIs, and review reports.

The public surface also includes buildReviewReport, analyzeImpactStreaming, and tool_impactJSON for specialized review and integration workflows. Batch output can retain ranked top impacts and full report metadata; streaming callers can choose a lighter terminal summary after consuming incremental chunks.

The root export includes compatibility APIs; documented subpath facades provide narrower imports. See the public API boundary before choosing an import path.

How it works

Codegraph follows a single analysis pipeline:

1. Discover supported files under the selected project and include roots.
2. Parse source languages with Tree-sitter and extract imports, exports, definitions, bindings, and scopes.
3. Resolve module specifiers to project files or explicit external nodes.
4. Build forward and reverse dependency indexes plus a semantic symbol index.
5. Reuse those indexes for navigation, exploration, impact, review, and exports.

Disk caching avoids repository-wide source reads on exact warm text-search hits. How it works covers caching, recovery, and performance choices.

Limits and tradeoffs

The honest boundaries matter:

• Codegraph is not a compiler or type checker. Reflection, generated code, macros, overload behavior, and dynamic dispatch can be missed.
• Precise navigation depends on successful parsing and language queries. Without a compatible native runtime, Codegraph falls back to reduced graph-only and regex recovery rather than claiming equivalent semantics.
• Call-compatibility findings are conservative review leads, not compiler diagnostics.
• Duplicate matches and candidate tests are ranked leads that still require human or agent judgment.
• --fast-graph is an explicit speed/accuracy tradeoff for plain JavaScript and TypeScript import extraction.
• The checked explore benchmark demonstrates bounded evidence retrieval, not universal speed, cost, or quality advantages.
• The separate semantic corpus reports reviewed definition, reference, dependency, and candidate-test results by runtime mode with an explicit support denominator. Its initial baseline is informational.

Run codegraph doctor to confirm the active runtime. Use --report on graph, index, or review commands when backend and cache behavior need to be auditable.

Development

npm install
npm run build
npm run check

Use the narrowest relevant test while iterating. npm run check is the pre-commit baseline for formatting, lint, build, and tests; native workspace changes also require npm run build:native and npm run test:native.

Codegraph is MIT licensed.