# Codegraph > A tool for agents and humans to understand a repo, assess diff impact/risk, navigate code, and answer questions fast. - **Type:** MCP server - **Install:** `agentstack add mcp-lzehrung-codegraph` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [lzehrung](https://agentstack.voostack.com/s/lzehrung) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [lzehrung](https://github.com/lzehrung) - **Source:** https://github.com/lzehrung/codegraph ## Install ```sh agentstack add mcp-lzehrung-codegraph ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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`: ```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: ```bash 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. ```bash # 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. ```bash # 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: ```text 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: ```json { "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: ```text 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`: ```json { "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: ```text 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: ```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: ```bash 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: ```bash 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: ```bash # 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](https://github.com/lzehrung) - **Source:** [lzehrung/codegraph](https://github.com/lzehrung/codegraph) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-lzehrung-codegraph - Seller: https://agentstack.voostack.com/s/lzehrung - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.