Ops Codegraph Tool

<p align="center"> <img src="https://img.shields.io/badge/codegraph-dependency%20intelligence-blue?style=for-the-badge&logo=graphql&logoColor=white" alt="codegraph" /> </p> <h1 align="center">codegraph</h1> <p align="center"> <strong>Give your AI the map before it starts exploring.</strong> </p> <p align="center"> <a href="https://www.npmjs.com/package/@optave/codegraph"><img src="https://img.shields.io/npm/v/@optave/codegraph?style=flat-square&logo=npm&logoColor=white&label=npm" alt="npm version" /></a> <a href="https://github.com/optave/ops-codegraph-tool/blob/main/LICENSE"><img src="https://img.shields.io/github/license/optave/ops-codegraph-tool?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="Apache-2.0 License" /></a> <a href="https://github.com/optave/ops-codegraph-tool/actions"><img src="https://img.shields.io/github/actions/workflow/status/optave/ops-codegraph-tool/codegraph-impact.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI" /></a> <img src="https://img.shields.io/badge/node-%3E%3D22.12.0-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 22.12.0" /> </p> <p align="center"> <a href="#the-problem">The Problem</a> &middot; <a href="#what-codegraph-does">What It Does</a> &middot; <a href="#-quick-start">Quick Start</a> &middot; <a href="#-commands">Commands</a> &middot; <a href="#-language-support">Languages</a> &middot; <a href="#-ai-agent-integration-core">AI Integration</a> &middot; <a href="#-how-it-works">How It Works</a> &middot; <a href="#-recommended-practices">Practices</a> &middot; <a href="#-roadmap">Roadmap</a> </p>

---

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: June 2026. Claims verified against each repo's README/docs. Full analysis: <a href="generated/competitive/COMPETITIVE_ANALYSIS.md">COMPETITIVE_ANALYSIS.md</a>}

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