{"id":45422055,"url":"https://github.com/optave/codegraph","last_synced_at":"2026-03-17T07:30:49.853Z","repository":{"id":339750272,"uuid":"1163218957","full_name":"optave/codegraph","owner":"optave","description":"Always-fresh code dependency graph — sub-second incremental rebuilds, function-level tracing across 11 languages, 20-tool MCP server for AI agents, git diff impact with co-change analysis, A→B pathfinding, node role classification, local semantic search. Zero API keys required.","archived":false,"fork":false,"pushed_at":"2026-03-02T02:15:14.000Z","size":5285,"stargazers_count":20,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-02T02:18:16.395Z","etag":null,"topics":["ai-agents","cli","code-analysis","dependency-graph","impact-analysis","incremental-builds","mcp-server","semantic-search","sqlite","static-analysis","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/optave.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"docs/roadmap/BACKLOG.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["optave"]}},"created_at":"2026-02-21T09:31:55.000Z","updated_at":"2026-03-02T02:15:16.000Z","dependencies_parsed_at":"2026-02-27T09:00:54.837Z","dependency_job_id":null,"html_url":"https://github.com/optave/codegraph","commit_stats":null,"previous_names":["optave/codegraph"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/optave/codegraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optave%2Fcodegraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optave%2Fcodegraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optave%2Fcodegraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optave%2Fcodegraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/optave","download_url":"https://codeload.github.com/optave/codegraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optave%2Fcodegraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30071895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T03:25:38.285Z","status":"ssl_error","status_checked_at":"2026-03-04T03:25:05.086Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","code-analysis","dependency-graph","impact-analysis","incremental-builds","mcp-server","semantic-search","sqlite","static-analysis","tree-sitter"],"created_at":"2026-02-22T01:40:28.190Z","updated_at":"2026-03-17T07:30:49.833Z","avatar_url":"https://github.com/optave.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/codegraph-dependency%20intelligence-blue?style=for-the-badge\u0026logo=graphql\u0026logoColor=white\" alt=\"codegraph\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ecodegraph\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eGive your AI the map before it starts exploring.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@optave/codegraph\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@optave/codegraph?style=flat-square\u0026logo=npm\u0026logoColor=white\u0026label=npm\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/optave/codegraph/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/optave/codegraph?style=flat-square\u0026logo=opensourceinitiative\u0026logoColor=white\" alt=\"Apache-2.0 License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/optave/codegraph/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/optave/codegraph/codegraph-impact.yml?style=flat-square\u0026logo=githubactions\u0026logoColor=white\u0026label=CI\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white\" alt=\"Node \u003e= 20\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#the-problem\"\u003eThe Problem\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#what-codegraph-does\"\u003eWhat It Does\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-commands\"\u003eCommands\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-language-support\"\u003eLanguages\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-ai-agent-integration-core\"\u003eAI Integration\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-how-it-works\"\u003eHow It Works\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-recommended-practices\"\u003ePractices\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-roadmap\"\u003eRoadmap\u003c/a\u003e\n\u003c/p\u003e\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 30 tools — one call instead of 30 `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 \u003cname\u003e -T` returns source, deps, callers, and tests — the agent writes code that fits |\n| **CI pipelines** | Catch test failures but miss structural degradation | `check --staged` fails the build when blast radius or complexity thresholds are exceeded |\n| **Developers** | Inherit a codebase and grep for hours to understand what calls what | `context handleAuth -T` gives the same structured view agents use |\n| **Architects** | Draw boundary rules that erode within weeks | `manifesto` and `boundaries` enforce architecture rules on every commit |\n\n### Feature comparison\n\n\u003csub\u003eComparison last verified: March 2026. Full analysis: \u003ca href=\"generated/competitive/COMPETITIVE_ANALYSIS.md\"\u003eCOMPETITIVE_ANALYSIS.md\u003c/a\u003e\u003c/sub\u003e\n\n| Capability | codegraph | [joern](https://github.com/joernio/joern) | [narsil-mcp](https://github.com/postrv/narsil-mcp) | [code-graph-rag](https://github.com/vitali87/code-graph-rag) | [cpg](https://github.com/Fraunhofer-AISEC/cpg) | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | [CodeMCP](https://github.com/SimplyLiz/CodeMCP) | [axon](https://github.com/harshkedia177/axon) |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|\n| MCP / AI agent support | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |\n| Batch querying | **Yes** | — | — | — | — | — | — | — |\n| Composite audit command | **Yes** | — | — | — | — | — | — | — |\n| Function-level analysis | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |\n| Multi-language | **11** | **14** | **32** | **11** | **~10** | **12** | **12** | **3** |\n| Semantic search | **Yes** | — | **Yes** | **Yes** | — | **Yes** | — | **Yes** |\n| Hybrid BM25 + semantic | **Yes** | — | — | — | — | **Yes** | — | **Yes** |\n| CODEOWNERS integration | **Yes** | — | — | — | — | — | — | — |\n| Architecture boundary rules | **Yes** | — | — | — | — | — | — | — |\n| CI validation predicates | **Yes** | — | — | — | — | — | — | — |\n| Graph snapshots | **Yes** | — | — | — | — | — | — | — |\n| Git diff impact | **Yes** | — | — | — | — | **Yes** | **Yes** | **Yes** |\n| Branch structural diff | **Yes** | — | — | — | — | — | — | **Yes** |\n| Git co-change analysis | **Yes** | — | — | — | — | — | — | **Yes** |\n| Watch mode | **Yes** | — | **Yes** | **Yes** | — | — | **Yes** | **Yes** |\n| Dead code / role classification | **Yes** | — | **Yes** | — | — | — | **Yes** | **Yes** |\n| Cycle detection | **Yes** | — | — | — | — | — | — | — |\n| Incremental rebuilds | **O(changed)** | — | O(n) Merkle | — | — | — | Go only | **Yes** |\n| Zero config | **Yes** | — | **Yes** | — | — | **Yes** | — | **Yes** |\n| Embeddable JS library (`npm install`) | **Yes** | — | — | — | — | — | — | — |\n| LLM-optional (works without API keys) | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |\n| Dataflow analysis | **Yes** | **Yes** | — | — | **Yes** | — | — | — |\n| Control flow graph (CFG) | **Yes** | **Yes** | — | — | **Yes** | — | — | — |\n| AST node querying | **Yes** | **Yes** | — | — | **Yes** | — | — | — |\n| Expanded node/edge types | **Yes** | **Yes** | — | — | **Yes** | — | — | — |\n| GraphML / Neo4j export | **Yes** | **Yes** | — | — | — | — | — | — |\n| Interactive graph viewer | **Yes** | — | — | — | — | — | — | — |\n| Commercial use allowed | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | No | Paid | **Yes** |\n| Open source | **Yes** | Yes | Yes | Yes | Yes | No | No | Yes |\n\n### What makes codegraph different\n\n| | Differentiator | In practice |\n|---|---|---|\n| **🤖** | **AI-first architecture** | 30-tool [MCP server](https://modelcontextprotocol.io/) — agents query the graph directly instead of scraping the filesystem. One call replaces 20+ grep/find/cat invocations |\n| **🏷️** | **Role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` — agents understand a symbol's architectural role without reading surrounding code |\n| **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |\n| **⚡** | **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 |\n| **💥** | **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 |\n| **🌐** | **Multi-language, one graph** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph — agents don't need per-language tools |\n| **🧠** | **Hybrid search** | BM25 keyword + semantic embeddings fused via RRF — `hybrid` (default), `semantic`, or `keyword` mode; multi-query via `\"auth; token; JWT\"` |\n| **🔬** | **Dataflow + CFG** | Track how data flows through functions (`flows_to`, `returns`, `mutates`) and visualize intraprocedural control flow graphs for all 11 languages |\n| **🔓** | **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 |\n\n---\n\n## 🚀 Quick Start\n\n```bash\nnpm install -g @optave/codegraph\ncd your-project\ncodegraph build        # → .codegraph/graph.db created\n```\n\nThat's it. The graph is ready. Now connect your AI agent.\n\n### For AI agents (primary use case)\n\nConnect directly via MCP — your agent gets 30 tools to query the graph:\n\n```bash\ncodegraph mcp          # 30-tool MCP server — AI queries the graph directly\n```\n\nOr add codegraph to your agent's instructions (e.g. `CLAUDE.md`):\n\n```markdown\nBefore modifying code, always:\n1. `codegraph where \u003cname\u003e` — find where the symbol lives\n2. `codegraph context \u003cname\u003e -T` — get full context (source, deps, callers)\n3. `codegraph fn-impact \u003cname\u003e -T` — check blast radius before editing\n\nAfter modifying code:\n4. `codegraph diff-impact --staged -T` — verify impact before committing\n```\n\nFull agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) \u0026middot; [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-template)\n\n### For developers\n\nThe same graph is available via CLI:\n\n```bash\ncodegraph map          # see most-connected files\ncodegraph query myFunc # find any function, see callers \u0026 callees\ncodegraph deps src/index.ts  # file-level import/export map\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/optave/codegraph.git\ncd codegraph \u0026\u0026 npm install \u0026\u0026 npm link\n```\n\n\u003e **Dev builds:** Pre-release tarballs are attached to [GitHub Releases](https://github.com/optave/codegraph/releases). Install with `npm install -g \u003cpath-to-tarball\u003e`. Note that `npm install -g \u003ctarball-url\u003e` does not work because npm cannot resolve optional platform-specific dependencies from a URL — download the `.tgz` first, then install from the local file.\n\n---\n\n## ✨ Features\n\n| | Feature | Description |\n|---|---|---|\n| 🤖 | **MCP server** | 30-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |\n| 🎯 | **Deep context** | `context` gives agents source, deps, callers, signature, and tests for a function in one call; `audit --quick` gives structural summaries |\n| 🏷️ | **Node role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` based on connectivity — agents instantly know architectural role |\n| 📦 | **Batch querying** | Accept a list of targets and return all results in one JSON payload — enables multi-agent parallel dispatch |\n| 💥 | **Impact analysis** | Trace every file affected by a change (transitive) |\n| 🧬 | **Function-level tracing** | Call chains, caller trees, function-level impact, and A→B pathfinding with qualified call resolution |\n| 📍 | **Fast lookup** | `where` shows exactly where a symbol is defined and used — minimal, fast |\n| 🔍 | **Symbol search** | Find any function, class, or method by name — exact match priority, relevance scoring, `--file` and `--kind` filters |\n| 📁 | **File dependencies** | See what a file imports and what imports it |\n| 📊 | **Diff impact** | Parse `git diff`, find overlapping functions, trace their callers |\n| 🔗 | **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 |\n| 🗺️ | **Module map** | Bird's-eye view of your most-connected files |\n| 🏗️ | **Structure \u0026 hotspots** | Directory cohesion scores, fan-in/fan-out hotspot detection, module boundaries |\n| 🔄 | **Cycle detection** | Find circular dependencies at file or function level |\n| 📤 | **Export** | DOT, Mermaid, JSON, GraphML, GraphSON, and Neo4j CSV graph export |\n| 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |\n| 👀 | **Watch mode** | Incrementally update the graph as files change |\n| ⚡ | **Always fresh** | Three-tier incremental detection — sub-second rebuilds even on large codebases |\n| 🔬 | **Data flow analysis** | Intraprocedural parameter tracking, return consumers, argument flows, and mutation detection — all 11 languages |\n| 🧮 | **Complexity metrics** | Cognitive, cyclomatic, nesting depth, Halstead, and Maintainability Index per function |\n| 🏘️ | **Community detection** | Louvain clustering to discover natural module boundaries and architectural drift |\n| 📜 | **Manifesto rule engine** | Configurable pass/fail rules with warn/fail thresholds for CI gates via `check` (exit code 1 on fail) |\n| 👥 | **CODEOWNERS integration** | Map graph nodes to CODEOWNERS entries — see who owns each function, ownership boundaries in `diff-impact` |\n| 💾 | **Graph snapshots** | `snapshot save`/`restore` for instant DB backup and rollback — checkpoint before refactoring, restore without rebuilding |\n| 🔎 | **Hybrid BM25 + semantic search** | FTS5 keyword search + embedding-based semantic search fused via Reciprocal Rank Fusion — `hybrid`, `semantic`, or `keyword` modes |\n| 📄 | **Pagination \u0026 NDJSON streaming** | Universal `--limit`/`--offset` pagination on all MCP tools and CLI commands; `--ndjson` for newline-delimited JSON streaming |\n| 🔀 | **Branch structural diff** | Compare code structure between two git refs — added/removed/changed symbols with transitive caller impact |\n| 🛡️ | **Architecture boundaries** | User-defined dependency rules between modules with onion architecture preset — violations flagged in manifesto and CI |\n| ✅ | **CI validation predicates** | `check` command with configurable gates: complexity, blast radius, cycles, boundary violations — exit code 0/1 for CI |\n| 📋 | **Composite audit** | Single `audit` command combining explain + impact + health metrics per function — one call instead of 3-4 |\n| 🚦 | **Triage queue** | `triage` merges connectivity, hotspots, roles, and complexity into a ranked audit priority queue |\n| 🔬 | **Dataflow analysis** | Track how data moves through functions with `flows_to`, `returns`, and `mutates` edges — all 11 languages, included by default, skip with `--no-dataflow` |\n| 🧩 | **Control flow graph** | Intraprocedural CFG construction for all 11 languages — `cfg` command with text/DOT/Mermaid output, included by default, skip with `--no-cfg` |\n| 🔎 | **AST node querying** | Stored queryable AST nodes (calls, `new`, string, regex, throw, await) — `ast` command with SQL GLOB pattern matching |\n| 🧬 | **Expanded node/edge types** | `parameter`, `property`, `constant` node kinds with `parent_id` for sub-declaration queries; `contains`, `parameter_of`, `receiver` edge kinds |\n| 📊 | **Exports analysis** | `exports \u003cfile\u003e` shows all exported symbols with per-symbol consumers, re-export detection, and counts |\n| 📈 | **Interactive viewer** | `codegraph plot` generates an interactive HTML graph viewer with hierarchical/force/radial layouts, complexity overlays, and drill-down |\n| 🏷️ | **Stable JSON schema** | `normalizeSymbol` utility ensures consistent 7-field output (name, kind, file, line, endLine, role, fileHash) across all commands |\n\nSee [docs/examples](docs/examples) for real-world CLI and MCP usage examples.\n\n## 📦 Commands\n\n### Build \u0026 Watch\n\n```bash\ncodegraph build [dir]          # Parse and build the dependency graph\ncodegraph build --no-incremental  # Force full rebuild\ncodegraph build --dataflow     # Extract data flow edges (flows_to, returns, mutates)\ncodegraph build --engine wasm  # Force WASM engine (skip native)\ncodegraph watch [dir]          # Watch for changes, update graph incrementally\n```\n\n### Query \u0026 Explore\n\n```bash\ncodegraph query \u003cname\u003e         # Find a symbol — shows callers and callees\ncodegraph deps \u003cfile\u003e          # File imports/exports\ncodegraph map                  # Top 20 most-connected files\ncodegraph map -n 50 --no-tests # Top 50, excluding test files\ncodegraph where \u003cname\u003e         # Where is a symbol defined and used?\ncodegraph where --file src/db.js  # List symbols, imports, exports for a file\ncodegraph stats                # Graph health: nodes, edges, languages, quality score\ncodegraph roles                # Node role classification (entry, core, utility, adapter, dead, leaf)\ncodegraph roles --role dead -T # Find dead code (unreferenced, non-exported symbols)\ncodegraph roles --role core --file src/  # Core symbols in src/\ncodegraph exports src/queries.js  # Per-symbol consumer analysis (who calls each export)\ncodegraph children \u003cname\u003e         # List parameters, properties, constants of a symbol\n```\n\n### Deep Context (designed for AI agents)\n\n```bash\ncodegraph context \u003cname\u003e       # Full context: source, deps, callers, signature, tests\ncodegraph context \u003cname\u003e --depth 2 --no-tests  # Include callee source 2 levels deep\ncodegraph audit \u003cfile\u003e --quick    # Structural summary: public API, internals, data flow\ncodegraph audit \u003cfunction\u003e --quick  # Function summary: signature, calls, callers, tests\n```\n\n### Impact Analysis\n\n```bash\ncodegraph impact \u003cfile\u003e        # Transitive reverse dependency trace\ncodegraph query \u003cname\u003e         # Function-level: callers, callees, call chain\ncodegraph query \u003cname\u003e --no-tests --depth 5\ncodegraph fn-impact \u003cname\u003e     # What functions break if this one changes\ncodegraph path \u003cfrom\u003e \u003cto\u003e            # Shortest path between two symbols (A calls...calls B)\ncodegraph path \u003cfrom\u003e \u003cto\u003e --reverse  # Follow edges backward\ncodegraph path \u003cfrom\u003e \u003cto\u003e --depth 5 --kinds calls,imports\ncodegraph diff-impact          # Impact of unstaged git changes\ncodegraph diff-impact --staged # Impact of staged changes\ncodegraph diff-impact HEAD~3   # Impact vs a specific ref\ncodegraph diff-impact main --format mermaid -T  # Mermaid flowchart of blast radius\ncodegraph branch-compare main feature-branch    # Structural diff between two refs\ncodegraph branch-compare main HEAD --no-tests   # Symbols added/removed/changed vs main\ncodegraph branch-compare v2.4.0 v2.5.0 --json   # JSON output for programmatic use\ncodegraph branch-compare main HEAD --format mermaid  # Mermaid diagram of structural changes\n```\n\n### Co-Change Analysis\n\nAnalyze git history to find files that always change together — surfaces hidden coupling the static graph can't see. Requires a git repository.\n\n```bash\ncodegraph co-change --analyze          # Scan git history and populate co-change data\ncodegraph co-change src/queries.js     # Show co-change partners for a file\ncodegraph co-change                    # Show top co-changing file pairs globally\ncodegraph co-change --since 6m         # Limit to last 6 months of history\ncodegraph co-change --min-jaccard 0.5  # Only show strong coupling (Jaccard \u003e= 0.5)\ncodegraph co-change --min-support 5    # Minimum co-commit count\ncodegraph co-change --full             # Include all details\n```\n\nCo-change data also enriches `diff-impact` — historically coupled files appear in a `historicallyCoupled` section alongside the static dependency analysis.\n\n### Structure \u0026 Hotspots\n\n```bash\ncodegraph structure            # Directory overview with cohesion scores\ncodegraph triage --level file  # Files with extreme fan-in, fan-out, or density\ncodegraph triage --level directory --sort coupling --no-tests\n```\n\n### Code Health \u0026 Architecture\n\n```bash\ncodegraph complexity              # Per-function cognitive, cyclomatic, nesting, MI\ncodegraph complexity --health -T  # Full Halstead health view (volume, effort, bugs, MI)\ncodegraph complexity --sort mi -T # Sort by worst maintainability index\ncodegraph complexity --above-threshold -T  # Only functions exceeding warn thresholds\ncodegraph communities             # Louvain community detection — natural module boundaries\ncodegraph communities --drift -T  # Drift analysis only — split/merge candidates\ncodegraph communities --functions # Function-level community detection\ncodegraph check                   # Pass/fail rule engine (exit code 1 on fail)\ncodegraph check -T                # Exclude test files from rule evaluation\n```\n\n### Dataflow, CFG \u0026 AST\n\n```bash\ncodegraph dataflow \u003cname\u003e             # Data flow edges for a function (flows_to, returns, mutates)\ncodegraph dataflow \u003cname\u003e --impact    # Transitive data-dependent blast radius\ncodegraph cfg \u003cname\u003e                  # Control flow graph (text format)\ncodegraph cfg \u003cname\u003e --format dot     # CFG as Graphviz DOT\ncodegraph cfg \u003cname\u003e --format mermaid # CFG as Mermaid diagram\ncodegraph ast                         # List all stored AST nodes\ncodegraph ast \"handleAuth\"            # Search AST nodes by pattern (GLOB)\ncodegraph ast -k call                 # Filter by kind: call, new, string, regex, throw, await\ncodegraph ast -k throw --file src/    # Combine kind and file filters\n```\n\n\u003e **Note:** Dataflow and CFG are included by default for all 11 languages. Use `--no-dataflow` / `--no-cfg` for faster builds.\n\n\n### Audit, Triage \u0026 Batch\n\nComposite commands for risk-driven workflows and multi-agent dispatch.\n\n```bash\ncodegraph audit \u003cfile-or-function\u003e    # Combined structural summary + impact + health in one report\ncodegraph audit \u003ctarget\u003e --quick      # Structural summary only (skip impact and health)\ncodegraph audit src/queries.js -T     # Audit all functions in a file\ncodegraph triage                      # Ranked audit priority queue (connectivity + hotspots + roles)\ncodegraph triage -T --limit 20        # Top 20 riskiest functions, excluding tests\ncodegraph triage --level file -T      # File-level hotspot analysis\ncodegraph triage --level directory -T # Directory-level hotspot analysis\ncodegraph batch target1 target2 ...   # Batch query multiple targets in one call\ncodegraph batch --json targets.json   # Batch from a JSON file\n```\n\n### CI Validation\n\n`codegraph check` provides configurable pass/fail predicates for CI gates and state machines. Exit code 0 = pass, 1 = fail.\n\n```bash\ncodegraph check                             # Run manifesto rules on whole codebase\ncodegraph check --staged                    # Check staged changes (diff predicates)\ncodegraph check --staged --rules            # Run both diff predicates AND manifesto rules\ncodegraph check --no-new-cycles             # Fail if staged changes introduce cycles\ncodegraph check --max-complexity 30         # Fail if any function exceeds complexity threshold\ncodegraph check --max-blast-radius 50       # Fail if blast radius exceeds limit\ncodegraph check --no-boundary-violations    # Fail on architecture boundary violations\ncodegraph check main                        # Check current branch vs main\n```\n\n### CODEOWNERS\n\nMap graph symbols to CODEOWNERS entries. Shows who owns each function and surfaces ownership boundaries.\n\n```bash\ncodegraph owners                   # Show ownership for all symbols\ncodegraph owners src/queries.js    # Ownership for symbols in a specific file\ncodegraph owners --boundary        # Show ownership boundaries between modules\ncodegraph owners --owner @backend  # Filter by owner\n```\n\nOwnership data also enriches `diff-impact` — affected owners and suggested reviewers appear alongside the static dependency analysis.\n\n### Snapshots\n\nLightweight SQLite DB backup and restore — checkpoint before refactoring, instantly rollback without rebuilding.\n\n```bash\ncodegraph snapshot save before-refactor   # Save a named snapshot\ncodegraph snapshot list                   # List all snapshots\ncodegraph snapshot restore before-refactor  # Restore a snapshot\ncodegraph snapshot delete before-refactor   # Delete a snapshot\n```\n\n### Export \u0026 Visualization\n\n```bash\ncodegraph export -f dot        # Graphviz DOT format\ncodegraph export -f mermaid    # Mermaid diagram\ncodegraph export -f json       # JSON graph\ncodegraph export -f graphml    # GraphML (XML standard)\ncodegraph export -f graphson   # GraphSON (TinkerPop v3 / Gremlin)\ncodegraph export -f neo4j      # Neo4j CSV (bulk import, separate nodes/relationships files)\ncodegraph export --functions -o graph.dot  # Function-level, write to file\ncodegraph plot                 # Interactive HTML viewer with force/hierarchical/radial layouts\ncodegraph cycles               # Detect circular dependencies\ncodegraph cycles --functions   # Function-level cycles\n```\n\n### Semantic Search\n\nLocal embeddings for every function, method, and class — search by natural language. Everything runs locally using [@huggingface/transformers](https://huggingface.co/docs/transformers.js) — no API keys needed.\n\n```bash\ncodegraph embed                # Build embeddings (default: nomic-v1.5)\ncodegraph embed --model nomic  # Use a different model\ncodegraph search \"handle authentication\"\ncodegraph search \"parse config\" --min-score 0.4 -n 10\ncodegraph search \"parseConfig\" --mode keyword   # BM25 keyword-only (exact names)\ncodegraph search \"auth flow\" --mode semantic    # Embedding-only (conceptual)\ncodegraph search \"auth flow\" --mode hybrid      # BM25 + semantic RRF fusion (default)\ncodegraph models               # List available models\n```\n\n#### Multi-query search\n\nSeparate queries with `;` to search from multiple angles at once. Results are ranked using [Reciprocal Rank Fusion (RRF)](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) — items that rank highly across multiple queries rise to the top.\n\n```bash\ncodegraph search \"auth middleware; JWT validation\"\ncodegraph search \"parse config; read settings; load env\" -n 20\ncodegraph search \"error handling; retry logic\" --kind function\ncodegraph search \"database connection; query builder\" --rrf-k 30\n```\n\nA 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.\n\n#### Available Models\n\n| Flag | Model | Dimensions | Size | License | Notes |\n|---|---|---|---|---|---|\n| `minilm` | all-MiniLM-L6-v2 | 384 | ~23 MB | Apache-2.0 | Fastest, good for quick iteration |\n| `jina-small` | jina-embeddings-v2-small-en | 512 | ~33 MB | Apache-2.0 | Better quality, still small |\n| `jina-base` | jina-embeddings-v2-base-en | 768 | ~137 MB | Apache-2.0 | High quality, 8192 token context |\n| `jina-code` | jina-embeddings-v2-base-code | 768 | ~137 MB | Apache-2.0 | Best for code search, trained on code+text (requires HF token) |\n| `nomic` | nomic-embed-text-v1 | 768 | ~137 MB | Apache-2.0 | Good quality, 8192 context |\n| `nomic-v1.5` (default) | nomic-embed-text-v1.5 | 768 | ~137 MB | Apache-2.0 | **Improved nomic, Matryoshka dimensions** |\n| `bge-large` | bge-large-en-v1.5 | 1024 | ~335 MB | MIT | Best general retrieval, top MTEB scores |\n\nThe model used during `embed` is stored in the database, so `search` auto-detects it — no need to pass `--model` when searching.\n\n### Multi-Repo Registry\n\nManage 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.\n\n```bash\ncodegraph registry list        # List all registered repos\ncodegraph registry list --json # JSON output\ncodegraph registry add \u003cdir\u003e   # Register a project directory\ncodegraph registry add \u003cdir\u003e -n my-name  # Custom name\ncodegraph registry remove \u003cname\u003e  # Unregister\n```\n\n`codegraph build` auto-registers the project — no manual setup needed.\n\n### Common Flags\n\n| Flag | Description |\n|---|---|\n| `-d, --db \u003cpath\u003e` | Custom path to `graph.db` |\n| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on most query commands including `query`, `fn-impact`, `path`, `context`, `where`, `diff-impact`, `search`, `map`, `roles`, `co-change`, `deps`, `impact`, `complexity`, `communities`, `branch-compare`, `audit`, `triage`, `check`, `dataflow`, `cfg`, `ast`, `exports`, `children`) |\n| `--depth \u003cn\u003e` | Transitive trace depth (default varies by command) |\n| `-j, --json` | Output as JSON |\n| `-v, --verbose` | Enable debug output |\n| `--engine \u003cengine\u003e` | Parser engine: `native`, `wasm`, or `auto` (default: `auto`) |\n| `-k, --kind \u003ckind\u003e` | Filter by kind: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` |\n| `-f, --file \u003cpath\u003e` | Scope to a specific file (`fn`, `context`, `where`) |\n| `--mode \u003cmode\u003e` | Search mode: `hybrid` (default), `semantic`, or `keyword` (`search`) |\n| `--ndjson` | Output as newline-delimited JSON (one object per line) |\n| `--table` | Output as auto-column aligned table |\n| `--csv` | Output as CSV (RFC 4180, nested objects flattened) |\n| `--limit \u003cn\u003e` | Limit number of results |\n| `--offset \u003cn\u003e` | Skip first N results (pagination) |\n| `--rrf-k \u003cn\u003e` | RRF smoothing constant for multi-query search (default 60) |\n\n## 🌐 Language Support\n\n| Language | Extensions | Coverage |\n|---|---|---|\n| ![JavaScript](https://img.shields.io/badge/-JavaScript-F7DF1E?style=flat-square\u0026logo=javascript\u0026logoColor=black) | `.js`, `.jsx`, `.mjs`, `.cjs` | Full — functions, classes, imports, call sites, dataflow |\n| ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white) | `.ts`, `.tsx` | Full — interfaces, type aliases, `.d.ts`, dataflow |\n| ![Python](https://img.shields.io/badge/-Python-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white) | `.py` | Functions, classes, methods, imports, decorators, dataflow |\n| ![Go](https://img.shields.io/badge/-Go-00ADD8?style=flat-square\u0026logo=go\u0026logoColor=white) | `.go` | Functions, methods, structs, interfaces, imports, call sites, dataflow |\n| ![Rust](https://img.shields.io/badge/-Rust-000000?style=flat-square\u0026logo=rust\u0026logoColor=white) | `.rs` | Functions, methods, structs, traits, `use` imports, call sites, dataflow |\n| ![Java](https://img.shields.io/badge/-Java-ED8B00?style=flat-square\u0026logo=openjdk\u0026logoColor=white) | `.java` | Classes, methods, constructors, interfaces, imports, call sites, dataflow |\n| ![C#](https://img.shields.io/badge/-C%23-512BD4?style=flat-square\u0026logo=dotnet\u0026logoColor=white) | `.cs` | Classes, structs, records, interfaces, enums, methods, constructors, using directives, invocations, dataflow |\n| ![PHP](https://img.shields.io/badge/-PHP-777BB4?style=flat-square\u0026logo=php\u0026logoColor=white) | `.php` | Functions, classes, interfaces, traits, enums, methods, namespace use, calls, dataflow |\n| ![Ruby](https://img.shields.io/badge/-Ruby-CC342D?style=flat-square\u0026logo=ruby\u0026logoColor=white) | `.rb` | Classes, modules, methods, singleton methods, require/require_relative, include/extend, dataflow |\n| ![Terraform](https://img.shields.io/badge/-Terraform-844FBA?style=flat-square\u0026logo=terraform\u0026logoColor=white) | `.tf`, `.hcl` | Resource, data, variable, module, output blocks |\n\n## ⚙️ How It Works\n\n```\n┌──────────┐    ┌───────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐\n│  Source  │──▶│ tree-sitter│──▶│  Extract  │──▶│  Resolve │──▶│ SQLite  │\n│  Files   │    │   Parse   │    │  Symbols  │    │  Imports │    │   DB    │\n└──────────┘    └───────────┘    └───────────┘    └──────────┘    └─────────┘\n                                                                       │\n                                                                       ▼\n                                                                 ┌─────────┐\n                                                                 │  Query  │\n                                                                 └─────────┘\n```\n\n1. **Parse** — tree-sitter parses every source file into an AST (native Rust engine or WASM fallback)\n2. **Extract** — Functions, classes, methods, interfaces, imports, exports, call sites, parameters, properties, and constants are extracted\n3. **Resolve** — Imports are resolved to actual files (handles ESM conventions, `tsconfig.json` path aliases, `baseUrl`)\n4. **Store** — Everything goes into SQLite as nodes + edges with tree-sitter node boundaries, plus structural edges (`contains`, `parameter_of`, `receiver`)\n5. **Analyze** (opt-in) — Complexity metrics, control flow graphs (`--cfg`), dataflow edges (`--dataflow`), and AST node storage\n6. **Query** — All queries run locally against the SQLite DB — typically under 100ms\n\n### Incremental Rebuilds\n\nThe graph stays current without re-parsing your entire codebase. Three-tier change detection ensures rebuilds are proportional to what changed, not the size of the project:\n\n1. **Tier 0 — Journal (O(changed)):** If `codegraph watch` was running, a change journal records exactly which files were touched. The next build reads the journal and only processes those files — zero filesystem scanning\n2. **Tier 1 — mtime+size (O(n) stats, O(changed) reads):** No journal? Codegraph stats every file and compares mtime + size against stored values. Matching files are skipped without reading a single byte\n3. **Tier 2 — Hash (O(changed) reads):** Files that fail the mtime/size check are read and MD5-hashed. Only files whose hash actually changed get re-parsed and re-inserted\n\n**Result:** change one file in a 3,000-file project and the rebuild completes in under a second. Put it in a commit hook, a file watcher, or let your AI agent trigger it.\n\n### Dual Engine\n\nCodegraph ships with two parsing engines:\n\n| Engine | How it works | When it's used |\n|--------|-------------|----------------|\n| **Native** (Rust) | napi-rs addon built from `crates/codegraph-core/` — parallel multi-core parsing via rayon | Auto-selected when the prebuilt binary is available |\n| **WASM** | `web-tree-sitter` with pre-built `.wasm` grammars in `grammars/` | Fallback when the native addon isn't installed |\n\nBoth engines produce identical output. Use `--engine native|wasm|auto` to control selection (default: `auto`).\n\n### Call Resolution\n\nCalls are resolved with **qualified resolution** — method calls (`obj.method()`) are distinguished from standalone function calls, and built-in receivers (`console`, `Math`, `JSON`, `Array`, `Promise`, etc.) are filtered out automatically. Import scope is respected: a call to `foo()` only resolves to functions that are actually imported or defined in the same file, eliminating false positives from name collisions.\n\n| Priority | Source | Confidence |\n|---|---|---|\n| 1 | **Import-aware** — `import { foo } from './bar'` → link to `bar` | `1.0` |\n| 2 | **Same-file** — definitions in the current file | `1.0` |\n| 3 | **Same directory** — definitions in sibling files (standalone calls only) | `0.7` |\n| 4 | **Same parent directory** — definitions in sibling dirs (standalone calls only) | `0.5` |\n| 5 | **Method hierarchy** — resolved through `extends`/`implements` | varies |\n\nMethod calls on unknown receivers skip global fallback entirely — `stmt.run()` will never resolve to a standalone `run` function in another file. Duplicate caller/callee edges are deduplicated automatically. Dynamic patterns like `fn.call()`, `fn.apply()`, `fn.bind()`, and `obj[\"method\"]()` are also detected on a best-effort basis.\n\nCodegraph also extracts symbols from common callback patterns: Commander `.command().action()` callbacks (as `command:build`), Express route handlers (as `route:GET /api/users`), and event emitter listeners (as `event:data`).\n\n## 📊 Performance\n\nSelf-measured on every release via CI ([build benchmarks](generated/benchmarks/BUILD-BENCHMARKS.md) | [embedding benchmarks](generated/benchmarks/EMBEDDING-BENCHMARKS.md)):\n\n| Metric | Latest |\n|---|---|\n| Build speed (native) | **3.5 ms/file** |\n| Build speed (WASM) | **9.6 ms/file** |\n| Query time | **3ms** |\n| No-op rebuild (native) | **9ms** |\n| 1-file rebuild (native) | **265ms** |\n| Query: fn-deps | **0.9ms** |\n| Query: path | **0.9ms** |\n| ~50,000 files (est.) | **~175.0s build** |\n\nMetrics are normalized per file for cross-version comparability. Times above are for a full initial build — incremental rebuilds only re-parse changed files.\n\n### Lightweight Footprint\n\n\u003ca href=\"https://www.npmjs.com/package/@optave/codegraph\"\u003e\u003cimg src=\"https://img.shields.io/npm/unpacked-size/@optave/codegraph?style=flat-square\u0026label=unpacked%20size\" alt=\"npm unpacked size\" /\u003e\u003c/a\u003e\n\nOnly **3 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) | Fast, synchronous SQLite driver | ![GitHub stars](https://img.shields.io/github/stars/WiseLibs/better-sqlite3?style=flat-square\u0026label=%E2%AD%90) | ![npm downloads](https://img.shields.io/npm/dw/better-sqlite3?style=flat-square\u0026label=%F0%9F%93%A5%2Fwk) |\n| [commander](https://github.com/tj/commander.js) | CLI argument parsing | ![GitHub stars](https://img.shields.io/github/stars/tj/commander.js?style=flat-square\u0026label=%E2%AD%90) | ![npm downloads](https://img.shields.io/npm/dw/commander?style=flat-square\u0026label=%F0%9F%93%A5%2Fwk) |\n| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | WASM tree-sitter bindings | ![GitHub stars](https://img.shields.io/github/stars/tree-sitter/tree-sitter?style=flat-square\u0026label=%E2%AD%90) | ![npm downloads](https://img.shields.io/npm/dw/web-tree-sitter?style=flat-square\u0026label=%F0%9F%93%A5%2Fwk) |\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 30 tools (31 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 \u003cname\u003e` — find where the symbol lives\n2. `codegraph audit --quick \u003ctarget\u003e` — understand the structure\n3. `codegraph context \u003cname\u003e -T` — get full context (source, deps, callers)\n4. `codegraph fn-impact \u003cname\u003e -T` — check blast radius before editing\n\n### After modifying code:\n5. `codegraph diff-impact --staged -T` — verify impact before committing\n\n### Other useful commands\n- `codegraph build .` — rebuild graph (incremental by default)\n- `codegraph map` — module overview · `codegraph stats` — graph health\n- `codegraph query \u003cname\u003e -T` — call chain · `codegraph path \u003cfrom\u003e \u003cto\u003e -T` — shortest path\n- `codegraph deps \u003cfile\u003e` — file deps · `codegraph exports \u003cfile\u003e -T` — export consumers\n- `codegraph audit \u003ctarget\u003e -T` — full risk report · `codegraph triage -T` — priority queue\n- `codegraph check --staged` — CI gate · `codegraph batch t1 t2 -T --json` — batch query\n- `codegraph search \"\u003cquery\u003e\"` — semantic search · `codegraph cycles` — cycle detection\n- `codegraph roles --role dead -T` — dead code · `codegraph complexity -T` — metrics\n- `codegraph dataflow \u003cname\u003e -T` — data flow · `codegraph cfg \u003cname\u003e -T` — control flow\n\n### Flags\n- `-T` — exclude test files (use by default) · `-j` — JSON output\n- `-f, --file \u003cpath\u003e` — scope to file · `-k, --kind \u003ckind\u003e` — filter kind\n```\n\n## 📋 Recommended Practices\n\nSee **[docs/guides/recommended-practices.md](docs/guides/recommended-practices.md)** for integration guides:\n\n- **Git hooks** — auto-rebuild on commit, impact checks on push, commit message enrichment\n- **CI/CD** — PR impact comments, threshold gates, graph caching\n- **AI agents** — MCP server, CLAUDE.md templates, Claude Code hooks\n- **Developer workflow** — watch mode, explore-before-you-edit, semantic search\n- **Secure credentials** — `apiKeyCommand` with 1Password, Bitwarden, Vault, macOS Keychain, `pass`\n\nFor AI-specific integration, see the **[AI Agent Guide](docs/guides/ai-agent-guide.md)** — a comprehensive reference covering the 6-step agent workflow, complete command-to-MCP mapping, Claude Code hooks, and token-saving patterns.\n\n## 🔁 CI / GitHub Actions\n\nCodegraph ships with a ready-to-use GitHub Actions workflow that comments impact analysis on every pull request.\n\nCopy `.github/workflows/codegraph-impact.yml` to your repo, and every PR will get a comment like:\n\n\u003e **3 functions changed** → **12 callers affected** across **7 files**\n\n## 🛠️ Configuration\n\nCreate a `.codegraphrc.json` in your project root to customize behavior:\n\n```json\n{\n  \"include\": [\"src/**\", \"lib/**\"],\n  \"exclude\": [\"**/*.test.js\", \"**/__mocks__/**\"],\n  \"ignoreDirs\": [\"node_modules\", \".git\", \"dist\"],\n  \"extensions\": [\".js\", \".ts\", \".tsx\", \".py\"],\n  \"aliases\": {\n    \"@/\": \"./src/\",\n    \"@utils/\": \"./src/utils/\"\n  },\n  \"build\": {\n    \"incremental\": true\n  },\n  \"query\": {\n    \"excludeTests\": true\n  }\n}\n```\n\n\u003e **Tip:** `excludeTests` can also be set at the top level as a shorthand — `{ \"excludeTests\": true }` is equivalent to nesting it under `query`. If both are present, the nested `query.excludeTests` takes precedence.\n\n### Manifesto rules\n\nConfigure pass/fail thresholds for `codegraph check` (manifesto mode):\n\n```json\n{\n  \"manifesto\": {\n    \"rules\": {\n      \"cognitive_complexity\": { \"warn\": 15, \"fail\": 30 },\n      \"cyclomatic_complexity\": { \"warn\": 10, \"fail\": 20 },\n      \"nesting_depth\": { \"warn\": 4, \"fail\": 6 },\n      \"maintainability_index\": { \"warn\": 40, \"fail\": 20 },\n      \"halstead_bugs\": { \"warn\": 0.5, \"fail\": 1.0 }\n    }\n  }\n}\n```\n\nWhen any function exceeds a `fail` threshold, `codegraph check` exits with code 1 — perfect for CI gates.\n\n### LLM credentials\n\nCodegraph supports an `apiKeyCommand` field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:\n\n```json\n{\n  \"llm\": {\n    \"provider\": \"openai\",\n    \"apiKeyCommand\": \"op read op://vault/openai/api-key\"\n  }\n}\n```\n\nThe command is split on whitespace and executed with `execFileSync` (no shell injection risk). Priority: **command output \u003e `CODEGRAPH_LLM_API_KEY` env var \u003e file config**. On failure, codegraph warns and falls back to the next source.\n\nWorks with any secret manager: 1Password CLI (`op`), Bitwarden (`bw`), `pass`, HashiCorp Vault, macOS Keychain (`security`), AWS Secrets Manager, etc.\n\n## 📖 Programmatic API\n\nCodegraph also exports a full API for use in your own tools:\n\n```js\nimport { buildGraph, queryNameData, findCycles, exportDOT, normalizeSymbol } from '@optave/codegraph';\n\n// Build the graph\nbuildGraph('/path/to/project');\n\n// Query programmatically\nconst results = queryNameData('myFunction', '/path/to/.codegraph/graph.db');\n// All query results use normalizeSymbol for a stable 7-field schema\n```\n\n```js\nimport { parseFileAuto, getActiveEngine, isNativeAvailable } from '@optave/codegraph';\n\n// Check which engine is active\nconsole.log(getActiveEngine());      // 'native' or 'wasm'\nconsole.log(isNativeAvailable());    // true if Rust addon is installed\n\n// Parse a single file (uses auto-selected engine)\nconst symbols = await parseFileAuto('/path/to/file.ts');\n```\n\n```js\nimport { searchData, multiSearchData, buildEmbeddings } from '@optave/codegraph';\n\n// Build embeddings (one-time)\nawait buildEmbeddings('/path/to/project');\n\n// Single-query search\nconst { results } = await searchData('handle auth', dbPath);\n\n// Multi-query search with RRF ranking\nconst { results: fused } = await multiSearchData(\n  ['auth middleware', 'JWT validation'],\n  dbPath,\n  { limit: 10, minScore: 0.3 }\n);\n// Each result has: { name, kind, file, line, rrf, queryScores[] }\n```\n\n## ⚠️ Limitations\n\n- **No full type inference** — parses `.d.ts` interfaces but doesn't use TypeScript's type checker for overload resolution\n- **Dynamic calls are best-effort** — complex computed property access and `eval` patterns are not resolved\n- **Python imports** — resolves relative imports but doesn't follow `sys.path` or virtual environment packages\n- **Dataflow analysis** — intraprocedural (single-function scope), not interprocedural\n\n## 🗺️ Roadmap\n\nSee **[ROADMAP.md](docs/roadmap/ROADMAP.md)** for the full development roadmap and **[STABILITY.md](STABILITY.md)** for the stability policy and versioning guarantees. Current plan:\n\n1. ~~**Rust Core**~~ — **Complete** (v1.3.0) — native tree-sitter parsing via napi-rs, parallel multi-core parsing, incremental re-parsing, import resolution \u0026 cycle detection in Rust\n2. ~~**Foundation Hardening**~~ — **Complete** (v1.4.0) — parser registry, 12-tool MCP server with multi-repo support, test coverage 62%→75%, `apiKeyCommand` secret resolution, global repo registry\n3. ~~**Deep Analysis**~~ — **Complete** (v3.0.0) — dataflow analysis (flows_to, returns, mutates), intraprocedural CFG for all 11 languages, stored AST nodes, expanded node/edge types (parameter, property, constant, contains, parameter_of, receiver), GraphML/GraphSON/Neo4j CSV export, interactive HTML viewer, CLI consolidation, stable JSON schema\n4. ~~**Architectural Refactoring**~~ — **Complete** (v3.1.5) — unified AST analysis, composable MCP, domain errors, builder pipeline, embedder subsystem, graph model, qualified names, presentation layer, InMemoryRepository, domain directory grouping, CLI composability\n5. **Natural Language Queries** — `codegraph ask` command, conversational sessions\n6. **Expanded Language Support** — 8 new languages (12 → 20)\n7. **GitHub Integration \u0026 CI** — reusable GitHub Action, PR review, SARIF output\n8. **TypeScript Migration** — gradual migration from JS to TypeScript\n\n## 🤝 Contributing\n\nContributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide — setup, workflow, commit convention, testing, and architecture notes.\n\n```bash\ngit clone https://github.com/optave/codegraph.git\ncd codegraph\nnpm install\nnpm test\n```\n\nLooking to add a new language? Check out **[Adding a New Language](docs/guides/adding-a-language.md)**.\n\n## 📄 License\n\n[Apache-2.0](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with \u003ca href=\"https://tree-sitter.github.io/\"\u003etree-sitter\u003c/a\u003e and \u003ca href=\"https://github.com/WiseLibs/better-sqlite3\"\u003ebetter-sqlite3\u003c/a\u003e. Your code stays on your machine.\u003c/sub\u003e\n\u003c/p\u003e\n","funding_links":["https://github.com/sponsors/optave"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptave%2Fcodegraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptave%2Fcodegraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptave%2Fcodegraph/lists"}