Ops Codegraph Tool

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

Feature comparison

Comparison last verified: June 2026. Claims verified against each repo's README/docs. Full analysis: COMPETITIVE_ANALYSIS.md

Capability	codegraph (this repo)	code-review-graph	narsil-mcp	codegraph (other)¹	axon	GitNexus
GitHub stars
Languages	34	~30	32	~20	3	13
MCP server	Yes	Yes	Yes	Yes	Yes	Yes
Dataflow + CFG + AST querying	Yes	AST only	Yes²	—	—	—
Hybrid search (BM25 + semantic)	Yes	Yes	—	Keyword only	Yes	Yes
Git-aware (diff impact, co-change, branch diff)	All 3	All 3	—	—	All 3	—
Dead code / role classification	Yes	Yes	Yes	—	Yes	—
Incremental rebuilds	O(changed)	O(changed)	O(n)	O(n)³	Yes⁴	O(n)⁵
Architecture rules + CI gate	Yes	—	—	—	—	—
Security scanning (SAST / vuln detection)	Intentionally out of scope⁶	—	Yes	—	—	—
Zero config, npm install	Yes	— (pip)	Yes	Yes	Yes	Yes
Graph export (GraphML / Neo4j / DOT)	Yes	—	—	—	—	—
Open source + commercial use	Yes (Apache-2.0)	Yes (MIT)	Yes (MIT/Apache-2.0)	Yes (MIT)	Source-available⁷	Non-commercial⁸

¹ colbymchenry/codegraph is an unrelated tool that shares the name. It focuses on reducing AI agent token consumption by pre-indexing code structure for fast context retrieval — not on structural analysis, CI gates, or complexity metrics. ² narsil-mcp added CFG and dataflow in recent versions. ³ colbymchenry/codegraph uses OS file watchers (chokidar) for auto-sync — rebuild triggers on file change but re-parses from scratch per file, not O(changed) hashing. ⁴ axon caches file-level parse results; the rebuild strategy is consistent with file-level incremental behaviour but has not been independently benchmarked for O(changed) complexity. ⁵ GitNexus skips re-index if the git commit hasn't changed, but re-processes the entire repo when it does — no per-file incremental parsing. ⁶ Codegraph focuses on structural understanding, not vulnerability detection — use dedicated SAST tools (Semgrep, CodeQL, Snyk) for that. ⁷ axon claims MIT in pyproject.toml but has no LICENSE file in the repo. ⁸ GitNexus uses the PolyForm Noncommercial 1.0.0 license.

What makes codegraph different

🚀 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

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 — surfaces hidden coupling the static graph can't see. Requires a git repository.

codegraph co-change --analyze          # Scan git history and populate co-change data
codegraph co-change src/queries.js     # Show co-change partners for a file
codegraph co-change                    # Show top co-changing file pairs globally
codegraph co-change --since 6m         # Limit to last 6 months of history
codegraph co-change --min-jaccard 0.5  # Only show strong coupling (Jaccard >= 0.5)
codegraph co-change --min-support 5    # Minimum co-commit count
codegraph co-change --full             # Include all details

Co-change data also enriches diff-impact — historically coupled files appear in a historicallyCoupled section alongside the static dependency analysis.

Structure & Hotspots

codegraph structure            # Directory overview with cohesion scores
codegraph triage --level file  # Files with extreme fan-in, fan-out, or density
codegraph triage --level directory --sort coupling --no-tests

Code Health & Architecture

codegraph complexity              # Per-function cognitive, cyclomatic, nesting, MI
codegraph complexity --health -T  # Full Halstead health view (volume, effort, bugs, MI)
codegraph complexity --sort mi -T # Sort by worst maintainability index
codegraph complexity --above-threshold -T  # Only functions exceeding warn thresholds
codegraph communities             # Leiden community detection — natural module boundaries
codegraph communities --drift -T  # Drift analysis only — split/merge candidates
codegraph communities --functions # Function-level community detection
codegraph check                   # Pass/fail rule engine (exit code 1 on fail)
codegraph check -T                # Exclude test files from rule evaluation

Dataflow, CFG & AST

codegraph dataflow <name>             # Data flow edges for a function (flows_to, returns, mutates)
codegraph dataflow <name> --impact    # Transitive data-dependent blast radius
codegraph cfg <name>                  # Control flow graph (text format)
codegraph cfg <name> --format dot     # CFG as Graphviz DOT
codegraph cfg <name> --format mermaid # CFG as Mermaid diagram
codegraph ast                         # List all stored AST nodes
codegraph ast "handleAuth"            # Search AST nodes by pattern (GLOB)
codegraph ast -k call                 # Filter by kind: call, new, string, regex, throw, await
codegraph ast -k throw --file src/    # Combine kind and file filters

Note: Dataflow and CFG are included by default for all 34 languages. Use --no-dataflow / --no-cfg for faster builds.

Audit, Triage & Batch

Composite commands for risk-driven workflows and multi-agent dispatch.

codegraph audit <file-or-function>    # Combined structural summary + impact + health in one report
codegraph audit <target> --quick      # Structural summary only (skip impact and health)
codegraph audit src/queries.js -T     # Audit all functions in a file
codegraph explain <target>            # Alias for audit — same output, easier to discover
codegraph triage                      # Ranked audit priority queue (connectivity + hotspots + roles)
codegraph triage -T --limit 20        # Top 20 riskiest functions, excluding tests
codegraph triage --level file -T      # File-level hotspot analysis
codegraph triage --level directory -T # Directory-level hotspot analysis
codegraph batch target1 target2 ...   # Batch query multiple targets in one call
codegraph batch --json targets.json   # Batch from a JSON file

CI Validation

codegraph check provides configurable pass/fail predicates for CI gates and state machines. Exit code 0 = pass, 1 = fail.

codegraph check                             # Run manifesto rules on whole codebase
codegraph check --staged                    # Check staged changes (diff predicates)
codegraph check --staged --rules            # Run both diff predicates AND manifesto rules
codegraph check --no-new-cycles             # Fail if staged changes introduce cycles
codegraph check --max-complexity 30         # Fail if any function exceeds complexity threshold
codegraph check --max-blast-radius 50       # Fail if blast radius exceeds limit
codegraph check --no-boundary-violations    # Fail on architecture boundary violations
codegraph check main                        # Check current branch vs main

CODEOWNERS

Map graph symbols to CODEOWNERS entries. Shows who owns each function and surfaces ownership boundaries.

codegraph owners                   # Show ownership for all symbols
codegraph owners src/queries.js    # Ownership for symbols in a specific file
codegraph owners --boundary        # Show ownership boundaries between modules
codegraph owners --owner @backend  # Filter by owner

Ownership data also enriches diff-impact — affected owners and suggested reviewers appear alongside the static dependency analysis.

Snapshots

Lightweight SQLite DB backup and restore — checkpoint before refactoring, instantly rollback without rebuilding.

codegraph snapshot save before-refactor   # Save a named snapshot
codegraph snapshot list                   # List all snapshots
codegraph snapshot restore before-refactor  # Restore a snapshot
codegraph snapshot delete before-refactor   # Delete a snapshot

Export & Visualization

codegraph export -f dot        # Graphviz DOT format
codegraph export -f mermaid    # Mermaid diagram
codegraph export -f json       # JSON graph
codegraph export -f graphml    # GraphML (XML standard)
codegraph export -f graphson   # GraphSON (TinkerPop v3 / Gremlin)
codegraph export -f neo4j      # Neo4j CSV (bulk import, separate nodes/relationships files)
codegraph export --functions -o graph.dot  # Function-level, write to file
codegraph plot                 # Interactive HTML viewer with force/hierarchical/radial layouts
codegraph cycles               # Detect circular dependencies
codegraph cycles --functions   # Function-level cycles

Semantic Search

Local embeddings for every function, method, and class — search by natural language. Everything runs locally using @huggingface/transformers — no API keys needed. Prefer a remote or self-hosted model instead? Set embeddings.provider: "openai" and llm.baseUrl in your config to call any OpenAI-compatible /embeddings endpoint — see configuration.md.

codegraph embed                # Build embeddings (default: nomic)
codegraph embed --model nomic-v1.5  # Use a different model
codegraph search "handle authentication"
codegraph search "parse config" --min-score 0.4 -n 10
codegraph search "parseConfig" --mode keyword   # BM25 keyword-only (exact names)
codegraph search "auth flow" --mode semantic    # Embedding-only (conceptual)
codegraph search "auth flow" --mode hybrid      # BM25 + semantic RRF fusion (default)
codegraph models               # List available models

Multi-query search

Separate queries with ; to search from multiple angles at once. Results are ranked using Reciprocal Rank Fusion (RRF) — items that rank highly across multiple queries rise to the top.

codegraph search "auth middleware; JWT validation"
codegraph search "parse config; read settings; load env" -n 20
codegraph search "error handling; retry logic" --kind function
codegraph search "database connection; query builder" --rrf-k 30

A single trailing semicolon is ignored (falls back to single-query mode). The --rrf-k flag controls the RRF smoothing constant (default 60) — lower values give more weight to top-ranked results.

Available Models

Per-model retrieval quality (Hit@N) and timing are measured on every release — see EMBEDDING-BENCHMARKS.md.

The model used during embed is stored in the database, so search auto-detects it — no need to pass --model when searching.

Multi-Repo Registry

Manage a global registry of codegraph-enabled projects. The registry stores paths to your built graphs so the MCP server can query them when multi-repo mode is enabled.

codegraph registry list        # List all registered repos
codegraph registry list --json # JSON output
codegraph registry add <dir>   # Register a project directory
codegraph registry add <dir> -n my-name  # Custom name
codegraph registry remove <name>  # Unregister

codegraph build auto-registers the project — no manual setup needed.

Configuration

Inspect and manage .codegraphrc.json settings.

codegraph config                    # Show all config keys with values and sources
codegraph config --json             # JSON output of the merged config
codegraph config --init             # Scaffold a .codegraphrc.json with all sections pre-populated
codegraph config --edit             # Open .codegraphrc.json in $EDITOR
codegraph config --enable-global    # Opt this repo into user-level global config
codegraph config --disable-global   # Opt this repo out of user-level global config
codegraph config --list-global      # Show the contents of the global config file

A user-level config file at ~/.config/codegraph/config.json (XDG) or ~/.codegraph/config.json lets you set personal defaults once and apply them to opted-in repos. The merge order is: DEFAULTS → global (if consented) → project → env. Non-interactive contexts (CI, MCP) never apply the global config without explicit consent. See docs/guides/configuration.md for full details.

Common Flags

🌐 Language Support

Language	Extensions	Imports	Exports	Call Sites	Heritage¹	Type Inference²	Dataflow
	.js, .jsx, .mjs, .cjs	✓	✓	✓	✓	✓	✓
	.ts, .tsx	✓	✓	✓	✓	✓	✓
	.py, .pyi	✓	✓	✓	✓	✓	✓
	.go	✓	✓	✓	✓	✓	✓
	.rs	✓	✓	✓	✓	✓	✓
	.java	✓	✓	✓	✓	✓	✓
	.cs	✓	✓	✓	✓	✓	✓
	.php, .phtml	✓	✓	✓	✓	✓	✓
	.rb, .rake, .gemspec	✓	✓	✓	✓	—³	✓
	.c, .h	✓	✓	✓	—⁴	—⁴	✓
	.cpp, .hpp, .cc, .cxx	✓	✓	✓	✓	—	✓
	.kt, .kts	✓	✓	✓	✓	—	✓
	.swift	✓	✓	✓	✓	—	✓
	.scala, .sc	✓	✓	✓	✓	—	✓
	.sh, .bash	✓	✓	✓	—⁴	—⁴	✓
	.ex, .exs	✓	✓	✓	—	—	✓
	.lua	✓	✓	✓	—	—	✓
	.dart	✓	✓	✓	✓	—	✓
	.zig	✓	✓	✓	—	—	✓
	.hs	✓	✓	✓	—	—	✓
	.ml, .mli	✓	✓	✓	—	—	✓
	.fs, .fsx, .fsi	✓	✓	✓	—	—	✓
	.gleam	✓	✓	✓	—	—	✓
	.clj, .cljs, .cljc	✓	✓	✓	—	—	✓
	.jl	✓	✓	✓	—	—	✓
	.r, .R	✓	✓	✓	—	—	✓
	.erl, .hrl	✓	✓	✓	—	—	✓
	.sol	✓	✓	✓	✓	—	✓
	.m	✓	✓	✓	✓	—	✓
	.cu, .cuh	✓	✓	✓	✓	—	✓
	.groovy, .gvy	✓	✓	✓	✓	—	✓
	.v, .sv	✓	✓	✓	—	—	✓
	.tf, .hcl	✓	—³	—³	—³	—³	—³

¹ Heritage = extends, implements, include/extend (Ruby), trait impl (Rust), receiver methods (Go). ² Type Inference extracts a per-file type map from annotations (const x: Router, MyType x, x: MyType) and new expressions, enabling the edge resolver to connect x.method() → Type.method(). ³ Not applicable — Ruby is dynamically typed; Terraform/HCL is declarative (no functions, classes, or type system). ⁴ Not applicable — C and Bash have no class/inheritance system. All languages have full parity between the native Rust engine and the WASM fallback.

⚙️ How It Works

┌──────────┐    ┌───────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐
│  Source  │──▶│ tree-sitter│──▶│  Extract  │──▶│  Resolve │──▶│ SQLite  │
│  Files   │    │   Parse   │    │  Symbols  │    │  Imports │    │   DB