![\"codegraph\"](\"https://img.shields.io/badge/codegraph-dependency%20intelligence-blue?style=for-the-badge&logo=graphql&logoColor=white\"){kind=icon}
\n\n
\n Give your AI the map before it starts exploring.\n
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/@optave/codegraph?style=flat-square&logo=npm&logoColor=white&label=npm\")
![\"Apache-2.0](\"https://img.shields.io/github/license/optave/ops-codegraph-tool?style=flat-square&logo=opensourceinitiative&logoColor=white\")
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/optave/ops-codegraph-tool/codegraph-impact.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI\")
![\"Node](\"https://img.shields.io/badge/node-%3E%3D22.12.0-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n The Problem ·\n What It Does ·\n Quick Start ·\n Commands ·\n Languages ·\n AI Integration ·\n How It Works ·\n Practices ·\n Roadmap\n
\n\n---\n\n## The Problem\n\nAI 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.\n\nAn 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.\n\nThe 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.\n\n## What Codegraph Does\n\nCodegraph 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.\n\nIt parses your code with [tree-sitter](https://tree-sitter.github.io/) (native Rust or WASM), stores the graph in SQLite, and exposes it where it matters most:\n\n- **MCP server** — AI agents query the graph directly through 34 tools — one call instead of dozens of `grep`/`find`/`cat` invocations\n- **CLI** — developers and agents explore, query, and audit code from the terminal\n- **CI gates** — `check` and `manifesto` commands enforce quality thresholds with exit codes\n- **Programmatic API** — embed codegraph in your own tools via `npm install`\n\nInstead 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.\n\n**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.\n\n**Three commands to a queryable graph:**\n\n```bash\nnpm install -g @optave/codegraph\ncd your-project\ncodegraph build\n```\n\nNo 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.\n\n### Why it matters\n\n| | Without codegraph | With codegraph |\n|---|---|---|\n| **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 |\n| **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 |\n| **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 |\n| **AI agents** | Produce code that works but doesn't fit the codebase structure | `context![\"npm](\"https://img.shields.io/npm/unpacked-size/@optave/codegraph?style=flat-square&label=unpacked%20size\")
\n\nOnly **4 runtime dependencies** — everything else is optional or a devDependency:\n\n| Dependency | What it does | | |\n|---|---|---|---|\n| [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) | SQLite driver (WASM engine; lazy-loaded, not used for native-engine reads) |  |  |\n| [commander](https://github.com/tj/commander.js) | CLI argument parsing |  |  |\n| [smol-toml](https://github.com/squirrelchat/smol-toml) | TOML parsing — reads `Cargo.toml` for Rust `crate::` target overrides and `pyproject.toml` for Python import roots |  |  |\n| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | WASM tree-sitter bindings |  |  |\n\nOptional: `@huggingface/transformers` (semantic search), `@modelcontextprotocol/sdk` (MCP server) — lazy-loaded only when needed.\n\n## 🤖 AI Agent Integration (Core)\n\n### MCP Server\n\nCodegraph is built around a [Model Context Protocol](https://modelcontextprotocol.io/) server with 34 tools (35 in multi-repo mode) — the primary way agents consume the graph:\n\n```bash\ncodegraph mcp # Single-repo mode (default) — only local project\ncodegraph mcp --multi-repo # Enable access to all registered repos\ncodegraph mcp --repos a,b # Restrict to specific repos (implies --multi-repo)\n```\n\n**Single-repo mode (default):** Tools operate only on the local `.codegraph/graph.db`. The `repo` parameter and `list_repos` tool are not exposed to the AI agent.\n\n**Multi-repo mode (`--multi-repo`):** All tools gain an optional `repo` parameter to target any registered repository, and `list_repos` becomes available. Use `--repos` to restrict which repos the agent can access.\n\n### CLAUDE.md / Agent Instructions\n\nAdd this to your project's `CLAUDE.md` to help AI agents use codegraph. Full template with all commands in the [AI Agent Guide](docs/guides/ai-agent-guide.md#claudemd-template).\n\n```markdown\n## Codegraph\n\nThis project uses codegraph for dependency analysis. The graph is at `.codegraph/graph.db`.\n\n### Before modifying code:\n1. `codegraph where