Ops Codegraph Tool

codegraph

Give your AI the map before it starts exploring.

= 22.6" />

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 -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: 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

| | 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 ` — find where the symbol lives
2. `codegraph context  -T` — get full context (source, deps, callers)
3. `codegraph fn-impact  -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](docs/guides/ai-agent-guide.md) · [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-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 . Note that npm install -g 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 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](docs/examples) f

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: optave
• Source: optave/ops-codegraph-tool
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.