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, omi