codegraph
CLI, MCP and TS library that turns source code into a map of files, symbols, references, and dependencies using tree-sitter.
Install / Use
claude mcp add lzehrung -- npx -y github:lzehrung/codegraphIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of codegraph
codegraph scores 84/100 on our quality scale, 632nd of 937 AI & Machine Learning skills we index.
Its MCP Server is 18 KB long, well organised into 33 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so codegraph is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (2 minor notes below). An AI review of the same text found nothing harmful.
- noteInstalls by piping a downloaded script into a shellline 36
irm https://github.com/lzehrung/codegraph/releases/latest/download/install.ps1 | iex - noteInstalls by piping a downloaded script into a shellline 40
curl -fsSL https://github.com/lzehrung/codegraph/releases/latest/download/install.sh | sh
AI review by kimi-k2.7-code on 2026-11-18. Automated pattern scan on 2026-11-18. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
codegraph compared with similar skills
All 4 of these similar skills score higher than codegraph; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| codegraph (this skill)by lzehrung | 84 | 10 | today | MCP Server |
| claude-memby thedotmack | 100 | 118.2k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 113.0k | 10d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 93.2k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 86.4k | today | CLAUDE.md |
Frequently asked questions
- How do I install codegraph?
- Run
claude mcp add lzehrung -- npx -y github:lzehrung/codegraph. The install tabs above show the steps for each supported agent. - Which AI agents does codegraph work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is codegraph safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (2 minor notes below). An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is codegraph still maintained?
- The repository was last updated today, so codegraph is actively maintained.
Skill content
View source on GitHubcodegraph
<p align="center"> <img src="./assets/codegraph-logo.png" alt="codegraph" width="300"> </p> <p align="center"> <a href="https://www.npmjs.com/package/@lzehrung/codegraph"><img src="https://img.shields.io/npm/v/%40lzehrung%2Fcodegraph?logo=npm&label=npm" alt="npm version"></a> <a href="https://github.com/lzehrung/codegraph/releases/latest"><img src="https://img.shields.io/github/v/release/lzehrung/codegraph?display_name=tag&sort=semver" alt="Release"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a> <a href="./package.json"><img src="https://img.shields.io/badge/node-%3E%3D22.16-brightgreen.svg" alt="Node.js"></a> <a href="./docs/mcp.md"><img src="https://img.shields.io/badge/MCP-server-purple.svg" alt="MCP"></a> <a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-Keep%20a%20Changelog-orange.svg" alt="Changelog"></a> </p>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 map of files, symbols, references, and dependencies. Ask where an implementation lives, how components connect, what a change can break, or which tests are relevant, then get bounded source evidence and copyable next steps.
codegraph is not an AST, a compiler, or a linter. People can use codegraph review and codegraph deps to inspect changes and dependencies without an agent.
Without structural context, an agent burns early turns listing directories, guessing search terms, opening candidate files, and reconstructing relationships. codegraph does that discovery once so the context window can stay focused on the problem.
With Node.js 22.16 or newer, install from npm:
npm install -g @lzehrung/codegraph
codegraph doctor
codegraph install
codegraph explore "build review report" --root .
No Node.js or npm? The standalone installers download a self-contained bundle with Node.js, the CLI, and the matching native runtime:
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
Use codegraph alongside text search and compilers: text search finds exact strings, compilers prove language behavior, and codegraph fills in the cross-file repository map between them. See Installation for npm, standalone, and source-checkout paths.
Table of contents
- Changelog
- What you can do
- Try it
- A useful first five minutes
- Visualize a graph
- 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
- Development
What you can do
| Job | Question | Start here | What comes back |
| -------- | ----------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
| Review | What could this change break? | codegraph review | Changed symbols, risks, and candidate tests |
| Review | Which tests should I run? | codegraph affected --base HEAD --head WORKTREE --quiet | Test paths from changed files and reverse dependencies |
| Review | Where should I start reading for a topic? | codegraph explore "<terms>" --root . | Top search hits with their source, dependents, and candidate tests |
| Refactor | Where is this symbol used? | codegraph refs src/file.ts:10:5 | Semantic references and coverage |
| Refactor | What depends on this file? | codegraph rdeps src/file.ts --json | Reverse dependencies |
| Refactor | What evidence supports a change? | codegraph refactor-plan <symbol-target> | Read-only evidence; no code changes |
| Refactor | Where would a rename apply? | codegraph rename-preview <symbol-target> <new-name> | Read-only edits and conflicts; no code changes |
| Quality | Which files have the most connections? | codegraph hotspots ./src --limit 20 | Fan-in and fan-out ranking |
| Quality | Where is code duplicated? | codegraph duplicates ./src --min-confidence medium | Ranked duplicate groups |
| Docs | Which public symbols exist? | codegraph apisurface | Exported API symbols |
| Docs | Which exports have no indexed docstring? | codegraph apisurface --undocumented | Locations; partial coverage names unchecked files |
| Docs | Are Markdown links broken? | codegraph links --root . | Broken local links with ranges; external URLs skipped |
CLI output is readable by default. Use --json for structured fields and omission counts.
Try it
See Installation for npm, standalone, and source-checkout steps.
A useful first five minutes
Do not begin by generating every possible report. Start with the question you actually have.
Understand an unfamiliar repo
# Map the repository before selecting a target
codegraph orient --root . --budget small
# Search a concrete term (the query is lexical: use the words that appear in code)
codegraph search "build review report" --json
# explore: search, then bundle the top hits with source, dependents, and candidate tests
codegraph explore "build review report" --root .
# Follow a returned target
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
# Broader blast-radius map when the summary needs expansion
codegraph impact --base HEAD --head WORKTREE
# Deterministic affected-test paths for focused validation
codegraph affected --base HEAD --head WORKTREE --quiet
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
# Validate local Markdown links offline (exit 1 on broken links)
codegraph links --root .
Export the model
codegraph graph --root . ./src --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
Visualize a graph
The packaged viewer is a human-facing graph UI; agents should use graph JSON, SQLite, MCP, or --json instead. Its command is codegraph viewer [--root <root>] [--graph <root-confined-json>] [--host <host>] [--port <0-65535>] [--open] [--print-url]; the root defaults to the current directory.

codegraph viewer --root . --open
codegraph viewer --root . --graph codegraph-out/graph.json --open
codegraph viewer --root . --port 4173 --print-url
The default host is 127.0.0.1 and the default port is 4173. Without --graph, each UI load or reload builds a current graph projection through the automatically validated .codegraph/cache/index-v1 index; init, index, and an exported JSON file are not prerequisites. An explicit --graph serves that root-confined snapshot through the same /graph.json route, while --print-url only prints the deterministic URL and exits.
The UI loads Sigma, Graphology, and ForceAtlas2 from bundled src/viewer/vendor/ assets, so the viewer stays offline and self-contained once codegraph is installed.
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, and the limits that applied; --json adds the omission counts.
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.
Why codegraph
Spend context on the problem, not repository discovery
explore runs one search and bundles bounded context around the top hits: source, dependency paths, dependents, candidate tests, and next commands. It is a reading starting point, only as good as the search terms. MCP omits source by default.
Ground the next action
Results include 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.
Trust the answer, or know why not
Definitions, references, and call edges come from scopes, imports, packages, and receivers proven from source, not from name matching alone. When codegraph cannot prove a target, it returns not_found or reports referenceCoverage as partial with a reason instead of guessing. An agent can act on a complete result and fall back to text search or a compiler for the rest; complete covers every candidate known to the index, not unknown dynamic loading. See the refs coverage contract and the language parity matrix for per-language support and tested limits.
Reuse one map from discovery through review
Search, navigation, dependency analysis, impact, and review reuse the same graph and semantic index. A target found during discovery ca
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
118.2kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
113.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
93.2kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
hyperframes
86.4kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
