codegraph

Give your AI the map before it starts exploring.

The Problem · What It Does · Quick Start · Commands · Languages · AI Integration · How It Works · Practices · Roadmap

---

The Problem

AI agents face an impossible trade-off. They either spend thousands of tokens reading files to understand a codebase's structure — blowing up their context window until quality degrades — or they assume how things work, and the assumptions are often wrong. Either way, things break. The larger the codebase, the worse it gets.

An agent modifies a function without knowing 9 files import it. It misreads what a helper does and builds logic on top of that misunderstanding. It leaves dead code behind after a refactor. The PR gets opened, and your reviewer — human or automated — flags the same structural issues again and again: "this breaks 14 callers," "that function already exists," "this export is now dead." If the reviewer catches it, that's multiple rounds of back-and-forth. If they don't, it can ship to production. Multiply that by every PR, every developer, every repo.

The information to prevent these issues exists — it's in the code itself. But without a structured map, agents lack the context to get it right consistently, reviewers waste cycles on preventable issues, and architecture degrades one unreviewed change at a time.

What Codegraph Does

Codegraph builds a function-level dependency graph of your entire codebase — every function, every caller, every dependency — and keeps it current with sub-second incremental rebuilds.

It parses your code with tree-sitter (native Rust or WASM), stores the graph in SQLite, and exposes it where it matters most:

• MCP server — AI agents query the graph directly through 34 tools — one call instead of dozens of grep/find/cat invocations
• CLI — developers and agents explore, query, and audit code from the terminal
• CI gates — check and manifesto commands enforce quality thresholds with exit codes
• Programmatic API — embed codegraph in your own tools via npm install

Instead of an agent editing code without structural context and letting reviewers catch the fallout, it knows "this function has 14 callers across 9 files" before it touches anything. Dead exports, circular dependencies, and boundary violations surface during development — not during review. The result: PRs that need fewer review rounds.

Free. Open source. Fully local. Zero network calls, zero telemetry. Your code stays on your machine. When you want deeper intelligence, bring your own LLM provider — your code only goes where you choose to send it.

Three commands to a queryable graph:

npm install -g @optave/codegraph
cd your-project
codegraph build

No config files, no Docker, no JVM, no API keys, no accounts. Point your agent at the MCP server and it has structural awareness of your codebase.

Why it matters

	Without codegraph	With codegraph
Code review	Reviewers flag broken callers, dead code, and boundary violations round after round	Structural issues are caught during development — PRs pass review with fewer rounds
AI agents	Modify parseConfig() without knowing 9 files import it — reviewer catches it	fn-impact parseConfig shows every caller before the edit — agent fixes it proactively
AI agents	Leave dead exports and duplicate helpers behind after refactors	Dead code, cycles, and duplicates surface in real time via hooks and MCP queries
AI agents	Produce code that works but doesn't fit the codebase structure	context <name> -T returns source, deps, callers, and tests — the agent writes code that fits
CI pipelines	Catch test failures but miss structural degradation	check --staged fails the build when blast radius or complexity thresholds are exceeded
Developers	Inherit a codebase and grep for hours to understand what calls what	context handleAuth -T gives the same structured view agents use
Architects	Draw boundary rules that erode within weeks	manifesto and boundaries enforce architecture rules on every commit

Feature comparison

_{Comparison last verified: August 2026 (full re-verification of every linked repo's live README + GitHub API on 2026-08-09). Full analysis: COMPETITIVE_ANALYSIS.md}

Capability	codegraph (this repo)	code-review-graph	narsil-mcp	codegraph (other)¹	claude-context	GitNexus
GitHub stars
Languages	34	30+	32	20+ (34 named)²	17³	14
CLI tool	Yes (44 commands)	Yes	Partial (config/serve only)⁴	Yes	— (MCP + library only)	Yes
API functionality (embeddable library)	Yes	—	—	Yes	Yes	Partial (HTTP API only)⁵
Dataflow + CFG + AST querying	Yes	Call graph only	Yes	—	—	PDG opt-in, TS/JS only
Interprocedural dataflow (cross-function)	Yes⁶	—	Partial (taint-only)⁷	—	—	Partial (taint-only, opt-in)⁸
Hybrid search (BM25 + semantic)	Yes	Yes	Yes (local ONNX, no key needed)	Keyword only	Yes	Yes
Git-aware (diff impact, co-change, branch diff)	All 3	Partial (co-change unreliable)⁹	Partial (no co-change/branch-diff)	—	—	Partial (no co-change)
Dead code / role classification	Yes	Yes	Yes	—	—	—
Code health (complexity metrics)	Yes (cognitive, cyclomatic, Halstead, MI)	—	Partial (cyclomatic + cognitive)¹⁰	—	—	—
Incremental rebuilds	O(changed)	O(changed)	**O(changed)**¹¹	**O(changed)**¹²	**O(changed)**¹³	Partial (chunk cache-key)¹⁴
Architecture rules + CI gate	Yes	Partial (risk-gate, no boundary rules)	Partial (layer model, no CI gate)	—	—	—
Security scanning (SAST / vuln detection)	Intentionally out of scope¹⁵	—	Yes	—	—	Partial (opt-in taint, --pdg only)
Zero config, npm install	Yes	— (pip)	Yes	Yes	No¹⁶	Yes
Runtime dependencies (direct packages)¹⁷	4	7	0¹⁸	10	23¹⁹	36
Graph export (GraphML / Neo4j / DOT)	Yes	Yes²⁰	Partial²¹	—	—	—
Open source + commercial use	Yes (Apache-2.0)	Yes (MIT)	Yes (Apache-2.0/MIT)	Yes (MIT)	Yes (MIT)	Non-commercial²²

^{¹ Unrelated tool sharing the name; focuses on AI token reduction via pre-indexed context, not structural analysis or CI gates. ² README says "20+ languages"; architecture docs list 34 across native + fallback grammar tiers. ³ Indexes 17 file extensions by default; AST-aware chunking covers ~10 — the rest fall back to plain text splitting. ⁴ narsil-mcp's CLI only manages config, lists tools, and serves the visualization frontend — no query commands; all graph queries require an MCP client. ⁵ GitNexus's local HTTP API (gitnexus serve, port 4747) only serves its own web UI — no importable library package. ⁶ Variable-level vertex model (arg_in/return_out/def_use) stitched across call edges — general-purpose, not just security, across all 34 languages. ⁷ trace_taint/get_typed_taint_flow cross function calls for security; general dataflow tools (get_data_flow, get_reaching_definitions) are per-function only. ⁸ Optional --pdg index (TS/JS only) adds taint source→sink tracking — security-scoped, not general cross-function flow. ⁹ Per its own README benchmark (2026-08-02), co-change eval returns 0 predicted files on every graded commit — "not yet a usable measurement." ¹⁰ get_complexity covers cyclomatic + cognitive complexity only — no Halstead metrics or maintainability index. ¹¹ Added Merkle-tree incremental indexing + watch mode (previously full re-index). ¹² OS-native file watcher reprocesses only changed files (debounced auto-sync); --force forces a full rebuild. ¹³ Merkle DAG + per-file MD5 hashing skips unchanged files, but each changed file still round-trips to the embedding provider + vector DB. ¹⁴ Cache-keyed, byte-budgeted chunk dispatch with incremental per-branch updates on checkout — finer than a full reprocess, but not per-file hashing. ¹⁵ Structural understanding, not vulnerability detection — use dedicated SAST tools (Semgrep, CodeQL, Snyk). ¹⁶ Requires an external Milvus vector DB + an embedding provider. A local keyless path exists (self-hosted Milvus + Ollama) but needs two running services; the managed path (Zilliz Cloud + OpenAI/VoyageAI/Gemini) trades that for cost. ¹⁷ Direct runtime deps declared in each project's own manifest (package.json/pyproject.toml), excluding dev/optional/transitive deps. ¹⁸ Single compiled binary — no separate packages to install. ¹⁹ mcp + core packages combined — plus the external vector DB + embedding provider noted above. ²⁰ Added GraphML, Neo4j Cypher, Obsidian vault, and SVG export. ²¹ Visualization frontend graph views, plus JSON-LD/N-Quads export for its Code Context Graph — but not GraphML or Neo4j specifically (a repo-wide code search found zero matches for either string); an internal DOT exporter exists (to_dot()) but isn't exposed via CLI or MCP. ²² PolyForm Noncommercial 1.0.0 license; separate commercial/enterprise licensing available.}

What makes codegraph different

	Differentiator	In practice
🤖	AI-first architecture	34-tool MCP server — agents query the graph directly instead of scraping the filesystem. One call replaces 20+ grep/find/cat invocations
🏷️	Role classification	Every symbol auto-tagged as entry/core/utility/adapter/dead/leaf — agents understand a symbol's architectural role without reading surrounding code
🔬	Function-level, not just files	Traces handleAuth() → validateToken() → decryptJWT() and shows 14 callers across 9 files break if decryptJWT changes
⚡	Always-fresh graph	Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds — agents work with current data
💥	Git diff impact	codegraph diff-impact shows changed functions, their callers, and full blast radius — enriched with historically coupled files from git co-change analysis. Ships with a GitHub Actions workflow
🌐	Multi-language, one graph	34 languages in a single graph — JS/TS, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Kotlin, Swift, Scala, Bash, HCL, Elixir, Lua, Dart, Zig, Haskell, OCaml, F#, Gleam, Clojure, Julia, R, Erlang, Solidity, Objective-C, CUDA, Groovy, Verilog — agents don't need per-language tools
🧠	Hybrid search	BM25 keyword + semantic embeddings fused via RRF — hybrid (default), semantic, or keyword mode; multi-query via "auth; token; JWT"
🔬	Dataflow + CFG	Track how data flows through and between functions — function-level edges (flows_to, returns, mutates), interprocedural variable-level edges (arg_in, return_out, def_use), and intraprocedural control flow graphs — all 34 languages
🔓	Fully local, zero cost	No API keys, no accounts, no network calls. Optionally bring your own LLM provider — your code only goes where you choose

---

🚀 Quick Start

npm install -g @optave/codegraph
cd your-project
codegraph build        # → .codegraph/graph.db created

That's it. The graph is ready. Now connect your AI agent.

For AI agents (primary use case)

Connect directly via MCP — your agent gets 34 tools to query the graph:

codegraph mcp          # 34-tool MCP server — AI queries the graph directly

Or add codegraph to your agent's instructions (e.g. CLAUDE.md):

Before modifying code, always:
1. `codegraph where <name>` — find where the symbol lives
2. `codegraph context <name> -T` — get full context (source, deps, callers)
3. `codegraph fn-impact <name> -T` — check blast radius before editing

After modifying code:
4. `codegraph diff-impact --staged -T` — verify impact before committing

Full agent setup: AI Agent Guide · CLAUDE.md template

For developers

The same graph is available via CLI:

codegraph map          # see most-connected files
codegraph query myFunc # find any function, see callers & callees
codegraph deps src/index.ts  # file-level import/export map

Or install from source:

git clone https://github.com/optave/ops-codegraph-tool.git
cd codegraph && npm install && npm link

Dev builds: Pre-release tarballs are attached to GitHub Releases. Install with npm install -g <path-to-tarball>. Note that npm install -g <tarball-url> does not work because npm cannot resolve optional platform-specific dependencies from a URL — download the .tgz first, then install from the local file.

---

✨ Features

	Feature	Description
🤖	MCP server	34-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo
🎯	Deep context	context gives agents source, deps, callers, signature, and tests for a function in one call; audit --quick gives structural summaries
🏷️	Node role classification	Every symbol auto-tagged as entry/core/utility/adapter/dead/leaf based on connectivity — agents instantly know architectural role
📦	Batch querying	Accept a list of targets and return all results in one JSON payload — enables multi-agent parallel dispatch
💥	Impact analysis	Trace every file affected by a change (transitive)
🧬	Function-level tracing	Call chains, caller trees, function-level impact, and A→B pathfinding with qualified call resolution
📍	Fast lookup	where shows exactly where a symbol is defined and used — minimal, fast
🔍	Symbol search	Find any function, class, or method by name — exact match priority, relevance scoring, --file and --kind filters
📁	File dependencies	See what a file imports and what imports it
📊	Diff impact	Parse git diff, find overlapping functions, trace their callers
🔗	Co-change analysis	Analyze git history for files that always change together — surfaces hidden coupling the static graph can't see; enriches diff-impact with historically coupled files
🗺️	Module map	Bird's-eye view of your most-connected files
🏗️	Structure & hotspots	Directory cohesion scores, fan-in/fan-out hotspot detection, module boundaries
🔄	Cycle detection	Find circular dependencies at file or function level
📤	Export	DOT, Mermaid, JSON, GraphML, GraphSON, and Neo4j CSV graph export
🧠	Semantic search	Embeddings-powered natural language search with multi-query RRF ranking
👀	Watch mode	Incrementally update the graph as files change
⚡	Always fresh	Three-tier incremental detection — sub-second rebuilds even on large codebases
🔬	Data flow analysis	Intraprocedural parameter tracking, return consumers, argument flows, and mutation detection — all 34 languages
🧮	Complexity metrics	Cognitive, cyclomatic, nesting depth, Halstead, and Maintainability Index per function
🏘️	Community detection	Leiden clustering to discover natural module boundaries and architectural drift
📜	Manifesto rule engine	Configurable pass/fail rules with warn/fail thresholds for CI gates via check (exit code 1 on fail)
👥	CODEOWNERS integration	Map graph nodes to CODEOWNERS entries — see who owns each function, ownership boundaries in diff-impact
💾	Graph snapshots	snapshot save/restore for instant DB backup and rollback — checkpoint before refactoring, restore without rebuilding
🔎	Hybrid BM25 + semantic search	FTS5 keyword search + embedding-based semantic search fused via Reciprocal Rank Fusion — hybrid, semantic, or keyword modes
📄	Pagination & NDJSON streaming	Universal --limit/--offset pagination on all MCP tools and CLI commands; --ndjson for newline-delimited JSON streaming
🔀	Branch structural diff	Compare code structure between two git refs — added/removed/changed symbols with transitive caller impact
🛡️	Architecture boundaries	User-defined dependency rules between modules with onion architecture preset — violations flagged in manifesto and CI
✅	CI validation predicates	check command with configurable gates: complexity, blast radius, cycles, boundary violations — exit code 0/1 for CI
📋	Composite audit	Single audit command combining explain + impact + health metrics per function — one call instead of 3-4
🚦	Triage queue	triage merges connectivity, hotspots, roles, and complexity into a ranked audit priority queue
🔬	Dataflow analysis	Track how data moves through and between functions — function-level (flows_to, returns, mutates) and interprocedural variable-level edges (arg_in, return_out, def_use) — all 34 languages, included by default, skip with --no-dataflow
🧩	Control flow graph	Intraprocedural CFG construction for all 34 languages — cfg command with text/DOT/Mermaid output, included by default, skip with --no-cfg
🔎	AST node querying	Stored queryable AST nodes (calls, new, string, regex, throw, await) — ast command with SQL GLOB pattern matching
🧬	Expanded node/edge types	parameter, property, constant node kinds with parent_id for sub-declaration queries; contains, parameter_of, receiver edge kinds
📊	Exports analysis	exports <file> shows all exported symbols with per-symbol consumers, re-export detection, and counts
📈	Interactive viewer	codegraph plot generates an interactive HTML graph viewer with hierarchical/force/radial layouts, complexity overlays, and drill-down
🏷️	Stable JSON schema	normalizeSymbol utility ensures consistent 7-field output (name, kind, file, line, endLine, role, fileHash) across all commands

See docs/examples for real-world CLI and MCP usage examples.

📦 Commands

Build & Watch

codegraph build [dir]          # Parse and build the dependency graph
codegraph build --no-incremental  # Force full rebuild
codegraph build --dataflow     # Extract data flow edges (flows_to, returns, mutates)
codegraph build --engine wasm  # Force WASM engine (skip native)
codegraph watch [dir]          # Watch for changes, update graph incrementally

Query & Explore

codegraph query <name>         # Find a symbol — shows callers and callees
codegraph deps <file>          # File imports/exports
codegraph map                  # Top 20 most-connected files
codegraph map -n 50 --no-tests # Top 50, excluding test files
codegraph where <name>         # Where is a symbol defined and used?
codegraph where --file src/db.js  # List symbols, imports, exports for a file
codegraph stats                # Graph health: nodes, edges, languages, quality score
codegraph roles                # Node role classification (entry, core, utility, adapter, dead, leaf)
codegraph roles --role dead -T # Find dead code (unreferenced, non-exported symbols)
codegraph roles --dynamic      # Show dynamic call sink edges (eval, computed-key, unresolved)
codegraph roles --role core --file src/  # Core symbols in src/
codegraph exports src/queries.js  # Per-symbol consumer analysis (who calls each export)
codegraph children <name>         # List parameters, properties, constants of a symbol

Deep Context (designed for AI agents)

codegraph context <name>       # Full context: source, deps, callers, signature, tests
codegraph context <name> --depth 2 --no-tests  # Include callee source 2 levels deep
codegraph brief <file>            # Token-efficient file summary: symbols, roles, risk tiers
codegraph audit <file> --quick    # Structural summary: public API, internals, data flow
codegraph audit <function> --quick  # Function summary: signature, calls, callers, tests

Impact Analysis

codegraph impact <file>        # Transitive reverse dependency trace
codegraph query <name>         # Function-level: callers, callees, call chain
codegraph query <name> --no-tests --depth 5
codegraph fn-impact <name>     # What functions break if this one changes
codegraph path <from> <to>            # Shortest path between two symbols (A calls...calls B)
codegraph path <from> <to> --reverse  # Follow edges backward
codegraph path <from> <to> --depth 5 --kinds calls,imports
codegraph diff-impact          # Impact of unstaged git changes
codegraph diff-impact --staged # Impact of staged changes
codegraph diff-impact HEAD~3   # Impact vs a specific ref
codegraph diff-impact main --format mermaid -T  # Mermaid flowchart of blast radius
codegraph branch-compare main feature-branch    # Structural diff between two refs
codegraph branch-compare main HEAD --no-tests   # Symbols added/removed/changed vs main
codegraph branch-compare v2.4.0 v2.5.0 --json   # JSON output for programmatic use
codegraph branch-compare main HEAD --format mermaid  # Mermaid diagram of structural changes

Co-Change Analysis

Analyze git history to find files that always change together — surface