{"id":50338088,"url":"https://github.com/colbymchenry/codegraph","last_synced_at":"2026-06-02T17:00:43.675Z","repository":{"id":333380569,"uuid":"1137078255","full_name":"colbymchenry/codegraph","owner":"colbymchenry","description":"Pre-indexed code knowledge graph for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent — fewer tokens, fewer tool calls, 100% local","archived":false,"fork":false,"pushed_at":"2026-06-02T11:45:41.000Z","size":3372,"stargazers_count":37618,"open_issues_count":250,"forks_count":2328,"subscribers_count":93,"default_branch":"main","last_synced_at":"2026-06-02T13:26:47.813Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://colbymchenry.github.io/codegraph/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colbymchenry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T21:45:37.000Z","updated_at":"2026-06-02T13:25:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/colbymchenry/codegraph","commit_stats":null,"previous_names":["colbymchenry/codegraph"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/colbymchenry/codegraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colbymchenry%2Fcodegraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colbymchenry%2Fcodegraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colbymchenry%2Fcodegraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colbymchenry%2Fcodegraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colbymchenry","download_url":"https://codeload.github.com/colbymchenry/codegraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colbymchenry%2Fcodegraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33831629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-29T15:00:23.637Z","updated_at":"2026-06-02T17:00:43.660Z","avatar_url":"https://github.com/colbymchenry.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Others","Repos","Integrations and Bridges","A01_文本生成_文本对话","🤖 AI \u0026 Machine Learning","Agent Infrastructure"],"sub_categories":["Usage","Plugins and add-ons","大语言对话模型及数据","Agent Skills \u0026 Tools"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# CodeGraph\n\n### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence\n\n**~16% cheaper · ~58% fewer tool calls · 100% local**\n\n### [Documentation \u0026 Website →](https://colbymchenry.github.io/codegraph/)\n\n[![npm version](https://img.shields.io/npm/v/@colbymchenry/codegraph.svg)](https://www.npmjs.com/package/@colbymchenry/codegraph)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Self-contained](https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen.svg)](https://nodejs.org/)\n\n[![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#supported-platforms)\n[![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#supported-platforms)\n[![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#supported-platforms)\n\n[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#supported-agents)\n[![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#supported-agents)\n[![Codex](https://img.shields.io/badge/Codex-supported-blueviolet.svg)](#supported-agents)\n[![opencode](https://img.shields.io/badge/opencode-supported-blueviolet.svg)](#supported-agents)\n[![Hermes Agent](https://img.shields.io/badge/Hermes_Agent-supported-blueviolet.svg)](#supported-agents)\n[![Gemini](https://img.shields.io/badge/Gemini-supported-blueviolet.svg)](#supported-agents)\n[![Antigravity](https://img.shields.io/badge/Antigravity-supported-blueviolet.svg)](#supported-agents)\n[![Kiro](https://img.shields.io/badge/Kiro-supported-blueviolet.svg)](#supported-agents)\n\n\u003c/div\u003e\n\n## Get Started\n\n**No Node.js required** — one command grabs the right build for your OS:\n\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex\n```\n\nAlready have Node? Use npm instead (works on any version):\n\n```bash\nnpx @colbymchenry/codegraph        # zero-install, or:\nnpm i -g @colbymchenry/codegraph\n```\n\n\u003csub\u003eCodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro.\u003c/sub\u003e\n\n### Initialize Projects\n\n```bash\ncd your-project\ncodegraph init -i\n```\n\n\u003csub\u003e`codegraph init` just creates the local `.codegraph/` index directory; adding `-i` (`--index`) also builds the initial graph in the same step. Without `-i`, run `codegraph index` afterwards to populate it.\u003c/sub\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n![1_C_VYnhpys0UHrOuOgpgoyw](https://github.com/user-attachments/assets/f168182f-4d9a-44e0-94d7-08d018cc8a3a)\n\n\u003c/div\u003e\n\n### Uninstall\n\nChanged your mind? One command removes CodeGraph from every agent it configured:\n\n```bash\ncodegraph uninstall\n```\n\n\u003csub\u003eReverses the installer — strips CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.\u003c/sub\u003e\n\n---\n\n## Why CodeGraph?\n\nWhen Claude Code explores a codebase, it spawns **Explore agents** that scan files with grep, glob, and Read — consuming tokens on every tool call.\n\n**CodeGraph gives those agents a pre-indexed knowledge graph** — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.\n\n### Benchmark Results\n\nTested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**. _Re-validated on Opus 4.8 (2026-06-02), on the current build (`codegraph_explore` as the primary tool)._\n\n\u003e **Average: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls**\n\n| Codebase | Language | Cost | Tokens | Time | Tool calls |\n|----------|----------|------|--------|------|------------|\n| **VS Code** | TypeScript · ~10k files | 18% cheaper | 64% fewer | 11% faster | 81% fewer |\n| **Excalidraw** | TypeScript · ~640 | even | 25% fewer | 27% faster | 40% fewer |\n| **Django** | Python · ~3k | 8% cheaper | 60% fewer | 13% faster | 77% fewer |\n| **Tokio** | Rust · ~790 | even | 38% fewer | 18% faster | 57% fewer |\n| **OkHttp** | Java · ~645 | 25% cheaper | 54% fewer | 31% faster | 50% fewer |\n| **Gin** | Go · ~110 | 19% cheaper | 23% fewer | 24% faster | 44% fewer |\n| **Alamofire** | Swift · ~110 | 40% cheaper | 64% fewer | 33% faster | 58% fewer |\n\nCodeGraph cuts **tokens, tool calls, and wall-clock time on every repo** — across small, medium, and large codebases — and answers them with **near-zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. `codegraph_explore` shows the answer in full — the mechanism plus the exact methods you asked about, even when they're buried in a multi-thousand-line file — while collapsing redundant interchangeable implementations to signatures, so the response is sized to the *answer* rather than the file count. **Cost stays flat-to-cheaper everywhere** — largest on the small repos (Alamofire, OkHttp), roughly break-even on the most response-heavy ones (Excalidraw, Tokio), where CodeGraph trades the no-CodeGraph agent's many small grep/read round-trips for a few large, cache-heavy tool responses.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePer-repo breakdown — WITH vs WITHOUT (median of 4)\u003c/strong\u003e\u003c/summary\u003e\n\n**VS Code** · ~10k files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 59s | 2m 13s | 11% faster |\n| File Reads | 0 | 9 | −9 |\n| Grep/Bash | 0 | 11 | −11 |\n| Tool calls | 4 | 21 | 81% fewer |\n| Total tokens | 640k | 1.79M | 64% fewer |\n| Cost | $0.68 | $0.83 | 18% cheaper |\n\n**Excalidraw** · ~640 files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 32s | 2m 6s | 27% faster |\n| File Reads | 0 | 7 | −7 |\n| Grep/Bash | 1 | 8 | −7 |\n| Tool calls | 9 | 15 | 40% fewer |\n| Total tokens | 1.27M | 1.69M | 25% fewer |\n| Cost | $0.78 | $0.78 | even |\n\n**Django** · ~3k files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 43s | 1m 58s | 13% faster |\n| File Reads | 0 | 9 | −9 |\n| Grep/Bash | 0 | 5 | −5 |\n| Tool calls | 3 | 13 | 77% fewer |\n| Total tokens | 559k | 1.41M | 60% fewer |\n| Cost | $0.57 | $0.62 | 8% cheaper |\n\n**Tokio** · ~790 files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 55s | 2m 20s | 18% faster |\n| File Reads | 0 | 8 | −8 |\n| Grep/Bash | 0 | 6 | −6 |\n| Tool calls | 6 | 14 | 57% fewer |\n| Total tokens | 1.08M | 1.73M | 38% fewer |\n| Cost | $0.82 | $0.82 | even |\n\n**OkHttp** · ~645 files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 1s | 1m 29s | 31% faster |\n| File Reads | 0 | 4 | −4 |\n| Grep/Bash | 2 | 6 | −4 |\n| Tool calls | 5 | 10 | 50% fewer |\n| Total tokens | 502k | 1.10M | 54% fewer |\n| Cost | $0.41 | $0.55 | 25% cheaper |\n\n**Gin** · ~110 files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 14s | 1m 37s | 24% faster |\n| File Reads | 1 | 6 | −5 |\n| Grep/Bash | 1 | 2 | −1 |\n| Tool calls | 5 | 9 | 44% fewer |\n| Total tokens | 651k | 847k | 23% fewer |\n| Cost | $0.46 | $0.57 | 19% cheaper |\n\n**Alamofire** · ~110 files\n| Metric | WITH cg | WITHOUT cg | Δ |\n|---|---|---|---|\n| Time | 1m 35s | 2m 21s | 33% faster |\n| File Reads | 0 | 9 | −9 |\n| Grep/Bash | 0 | 4 | −4 |\n| Tool calls | 5 | 12 | 58% fewer |\n| Total tokens | 766k | 2.10M | 64% fewer |\n| Cost | $0.57 | $0.95 | 40% cheaper |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull benchmark details\u003c/strong\u003e\u003c/summary\u003e\n\n**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them. Re-validated 2026-06-02 on the current build. These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).\n\n**Queries:**\n| Codebase | Query |\n|----------|-------|\n| VS Code | \"How does the extension host communicate with the main process?\" |\n| Excalidraw | \"How does Excalidraw render and update canvas elements?\" |\n| Django | \"How does Django's ORM build and execute a query from a QuerySet?\" |\n| Tokio | \"How does tokio schedule and run async tasks on its runtime?\" |\n| OkHttp | \"How does OkHttp process a request through its interceptor chain?\" |\n| Gin | \"How does gin route requests through its middleware chain?\" |\n| Alamofire | \"How does Alamofire build, send, and validate a request?\" |\n\n**Why CodeGraph wins:** with the index available, the agent answers directly — usually one `codegraph_explore` returns the relevant source — and stops, usually with zero file reads. Without it, the agent spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when queried *directly*, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.\n\n\u003c/details\u003e\n\n---\n\n## Key Features\n\n| | |\n|---|---|\n| **Smart Context Building** | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents |\n| **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 |\n| **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes |\n| **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |\n| **20+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Objective-C, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi |\n| **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 14 frameworks |\n| **Mixed iOS / React Native / Expo** | Closes cross-language flows that static parsing misses: Swift ↔ ObjC bridging, React Native legacy bridge + TurboModules + Fabric view components, native → JS event emitters, Expo Modules |\n| **100% Local** | No data leaves your machine. No API keys. No external services. SQLite database only |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow auto-syncing works — and why you don't need to run \u003ccode\u003ecodegraph sync\u003c/code\u003e manually\u003c/strong\u003e\u003c/summary\u003e\n\nWhen your agent (Claude Code, Cursor, Codex, opencode) launches `codegraph serve --mcp`, three layers keep the index in step with your code — and make sure the agent never gets a silent wrong answer in the brief window between an edit and the next sync:\n\n1. **File watcher with debounced auto-sync.** A native FSEvents / inotify / ReadDirectoryChangesW watcher captures every source-file create / modify / delete and triggers a re-index after a debounce window (default `2000ms`, tunable via `CODEGRAPH_WATCH_DEBOUNCE_MS`, clamped to `[100ms, 60s]`). Bursts of edits collapse into a single sync.\n\n2. **Per-file staleness banner.** During the brief debounce window, MCP tool responses that would reference a still-pending file prepend a `⚠️` banner naming it and telling the agent to `Read` it directly. Pending files NOT referenced by the response surface as a small footer instead. Either way, the agent gets an explicit signal — validated with Claude Code, where the agent literally says \"Reading the file directly for the live content\" before opening it.\n\n3. **Connect-time catch-up.** When the MCP server (re)connects, codegraph runs a fast `(size, mtime)` + content-hash reconciliation against the working tree before answering the first query — so edits made while no MCP server was running (a `git pull` from the terminal, edits from another editor, a previous agent session that exited) get absorbed on the next session's first tool call.\n\n```\nagent writes src/Widget.ts\n  → watcher fires (\u003c100ms)\n  → debounce (default 2s)\n  → sync; Widget.ts is in the index\n  → next agent query sees it\n```\n\n**Verify any time** with `codegraph_status` (via MCP) or `codegraph status` (CLI). If anything is pending, you'll see a `### Pending sync:` section naming the files and their edit age.\n\nThe handful of cases where manual `codegraph sync` makes sense: the watcher is disabled (sandboxed environments, or `CODEGRAPH_NO_DAEMON=1`), or you're scripting against the index outside an agent session and want a pre-flight sync at the start of your script.\n\n→ Full deep-dive in [Guides → Indexing a Project](https://colbymchenry.github.io/codegraph/guides/indexing/#stay-fresh-automatically).\n\n\u003c/details\u003e\n\n---\n\n## Framework-aware Routes\n\nCodeGraph detects web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions. Querying callers of a view/controller now surfaces the URL pattern that binds it.\n\n| Framework | Shapes recognized |\n|---|---|\n| **Django** | `path()`, `re_path()`, `url()`, `include()` in `urls.py` (CBV `.as_view()`, dotted paths) |\n| **Flask** | `@app.route('/path', methods=[...])`, blueprint routes |\n| **FastAPI** | `@app.get(...)`, `@router.post(...)`, all standard methods |\n| **Express** | `app.get(...)`, `router.post(...)` with middleware chains |\n| **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` |\n| **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |\n| **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |\n| **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=\u003e` syntax |\n| **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |\n| **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` |\n| **Axum / actix / Rocket** | `.route(\"/x\", get(handler))` |\n| **ASP.NET** | `[HttpGet(\"/x\")]` attributes on action methods |\n| **Vapor** | `app.get(\"x\", use: handler)` |\n| **React Router** / **SvelteKit** | Route component nodes |\n\n---\n\n## Mixed iOS / React Native / Expo bridging\n\nReal iOS and React Native codebases live across multiple languages — a Swift caller invokes an Objective-C selector that's been auto-bridged, a JS file calls into a native module via the React Native bridge, a JSX component delegates to a native view manager. Static tree-sitter extraction stops at each language boundary. CodeGraph bridges them so `trace`, `callers`, `callees`, and `impact` connect end-to-end across the gap.\n\n| Boundary | JS / Swift side | Native side | How |\n|---|---|---|---|\n| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC selector `-fooWithBar:` | `@objc` auto-bridging rules (including init/property/protocol forms) + Cocoa preposition prefixes (`With`/`For`/`By`/`In`/`On`/`At`/…) |\n| **ObjC → Swift** | ObjC `[obj fooWithBar:]` | Swift `@objc func foo(bar:)` | Reverse-bridge name candidates; verifies `@objc` exposure from source |\n| **React Native legacy bridge** | JS `NativeModules.X.fn(...)` | ObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` | Parses macro/annotation declarations to build a JS-name → native-method map |\n| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | Native impl matching the Codegen spec | Treats the `Native\u003cX\u003e.ts` spec interface as ground truth |\n| **RN native → JS events** | JS `new NativeEventEmitter(...).addListener('e', cb)` | ObjC `[self sendEventWithName:@\"e\" body:...]` · Swift `sendEvent(withName: \"e\", ...)` · Java/Kotlin `.emit(\"e\", ...)` | Synthesized cross-language event channel keyed by literal event name |\n| **Expo Modules** | JS `requireNativeModule('X').fn(...)` | Swift / Kotlin `Module { Name(\"X\"); AsyncFunction(\"fn\") { ... } }` | Parses the Expo DSL literals; synthetic method nodes resolve via existing name-match |\n| **Fabric view components** | JSX `\u003cMyView prop={v}/\u003e` | TS Codegen spec + native impl class | Spec → `component` node; convention-based name+suffix lookup (`View`/`ComponentView`/`Manager`/`ViewManager`) bridges to native |\n| **Legacy Paper view managers** | JSX `\u003cMyView prop={v}/\u003e` | ObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` | Same as Fabric — Paper-era declarations also produce `component` + `property` nodes |\n\n**Validated on real codebases** (small + medium + large for each bridge):\n\n| Bridge | Small | Medium | Large |\n|---|---|---|---|\n| Swift ↔ ObjC | [Charts](https://github.com/danielgindi/Charts) | [realm-swift](https://github.com/realm/realm-swift) | [Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios) |\n| RN legacy bridge | [AsyncStorage](https://github.com/react-native-async-storage/async-storage) | [react-native-svg](https://github.com/software-mansion/react-native-svg) | [react-native-firebase](https://github.com/invertase/react-native-firebase) |\n| RN native → JS events | [RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service) | — | react-native-firebase |\n| Expo Modules | expo-haptics | expo-camera | expo SDK sweep (7 packages) |\n| Fabric / Paper views | [react-native-segmented-control](https://github.com/react-native-segmented-control/segmented-control) | [react-native-screens](https://github.com/software-mansion/react-native-screens) | [react-native-skia](https://github.com/Shopify/react-native-skia) |\n\nEach bridge emits edges tagged `provenance:'heuristic'` with `metadata.synthesizedBy:` set to a stable channel name (e.g. `swift-objc-bridge`, `rn-event-channel`, `fabric-native-impl`, `expo-module-extract`), so the agent can tell at a glance how a hop got into the graph.\n\n---\n\n## Quick Start\n\n### 1. Run the Installer\n\n```bash\nnpx @colbymchenry/codegraph\n```\n\nThe installer will:\n- Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, **Kiro**\n- Prompt to install `codegraph` on your PATH (so agents can launch the MCP server)\n- Ask whether configs apply to all your projects or just this one\n- Write each chosen agent's MCP server config (the codegraph usage guide is delivered by the MCP server itself, so no instructions file is added to `CLAUDE.md` / `AGENTS.md` / etc.)\n- Set up auto-allow permissions when Claude Code is one of the targets\n- Initialize your current project (local installs only)\n\n**Non-interactive (scripting / CI):**\n\n```bash\ncodegraph install --yes                              # auto-detect agents, install global\ncodegraph install --target=cursor,claude --yes       # explicit target list\ncodegraph install --target=auto --location=local     # detected agents, project-local\ncodegraph install --print-config codex               # print snippet, no file writes\n```\n\n| Flag | Values | Default |\n|---|---|---|\n| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,...`) | prompt |\n| `--location` | `global`, `local` | prompt |\n| `--yes` | (boolean) | prompt every step |\n| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |\n| `--print-config \u003cid\u003e` | dump snippet for one agent and exit | — |\n\n### 2. Restart Your Agent\n\nRestart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.\n\n### 3. Initialize Projects\n\n```bash\ncd your-project\ncodegraph init -i\n```\n\nBuilds the per-project knowledge graph index. A single global `codegraph install` works in every project you open — no need to re-run the installer per project.\n\nThat's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eManual Setup (Alternative)\u003c/strong\u003e\u003c/summary\u003e\n\n**Install globally:**\n```bash\nnpm install -g @colbymchenry/codegraph\n```\n\n**Add to `~/.claude.json`:**\n```json\n{\n  \"mcpServers\": {\n    \"codegraph\": {\n      \"type\": \"stdio\",\n      \"command\": \"codegraph\",\n      \"args\": [\"serve\", \"--mcp\"]\n    }\n  }\n}\n```\n\n**Add to `~/.claude/settings.json` (optional, for auto-allow):**\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__codegraph__codegraph_search\",\n      \"mcp__codegraph__codegraph_explore\",\n      \"mcp__codegraph__codegraph_callers\",\n      \"mcp__codegraph__codegraph_callees\",\n      \"mcp__codegraph__codegraph_impact\",\n      \"mcp__codegraph__codegraph_node\",\n      \"mcp__codegraph__codegraph_status\",\n      \"mcp__codegraph__codegraph_files\"\n    ]\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAgent Tool Guidance\u003c/strong\u003e\u003c/summary\u003e\n\nCodeGraph's MCP server delivers its usage guidance to your agent **automatically**, in the MCP `initialize` response — there's no instructions file to manage and nothing is added to your `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`. In short, it tells the agent to:\n\n- **Answer structural questions directly with CodeGraph** — it *is* the pre-built index, so a grep/read loop just repeats work it already did. Treat the returned source as already read.\n- **Pick the tool by intent:** `codegraph_explore` for almost anything — \"how does X work\", a flow/\"how does X reach Y\", or surveying an area (one call returns the relevant symbols' source grouped by file); `codegraph_search` to just locate a symbol; `codegraph_callers`/`codegraph_callees` to walk call flow; `codegraph_impact` before editing; `codegraph_node` for one specific symbol's full source (it returns every overload for an ambiguous name).\n- **Trust the results — don't re-verify with grep**, and check the staleness banner after edits.\n- If `.codegraph/` doesn't exist yet, offer to run `codegraph init -i`.\n\nThe exact text is `src/mcp/server-instructions.ts` — the single source of truth.\n\n\u003c/details\u003e\n\n---\n\n## How It Works\n\n```\n┌───────────────────────────────────────────────────────────────────┐\n│                            Claude Code                            │\n│                                                                   │\n│   \"How does a request reach the database?\"                        │\n│       calls CodeGraph tools directly — no Explore sub-agent       │\n│                                 │                                 │\n└─────────────────────────────────┬─────────────────────────────────┘\n                                  │\n                                  ▼\n┌───────────────────────────────────────────────────────────────────┐\n│                        CodeGraph MCP Server                       │\n│                                                                   │\n│       explore · search · callers · callees · impact · node        │\n│                                 │                                 │\n│                                 ▼                                 │\n│                       SQLite knowledge graph                      │\n│          symbols · edges · files · FTS5 full-text search          │\n└───────────────────────────────────────────────────────────────────┘\n```\n\n1. **Extraction** — [tree-sitter](https://tree-sitter.github.io/) parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).\n\n2. **Storage** — Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search.\n\n3. **Resolution** — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.\n\n4. **Auto-Sync** — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed.\n\n---\n\n## CLI Reference\n\n```bash\ncodegraph                         # Run interactive installer\ncodegraph install                 # Run installer (explicit)\ncodegraph uninstall               # Remove CodeGraph from your agents (inverse of install)\ncodegraph init [path]             # Initialize in a project (--index to also index)\ncodegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)\ncodegraph index [path]            # Full index (--force to re-index, --quiet for less output)\ncodegraph sync [path]             # Incremental update\ncodegraph status [path]           # Show statistics\ncodegraph query \u003csearch\u003e          # Search symbols (--kind, --limit, --json)\ncodegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)\ncodegraph callers \u003csymbol\u003e        # Find what calls a function/method (--limit, --json)\ncodegraph callees \u003csymbol\u003e        # Find what a function/method calls (--limit, --json)\ncodegraph impact \u003csymbol\u003e         # Analyze what code is affected by changing a symbol (--depth, --json)\ncodegraph affected [files...]     # Find test files affected by changes (see below)\ncodegraph serve --mcp             # Start MCP server\n```\n\n### `codegraph affected`\n\nTraces import dependencies transitively to find which test files are affected by changed source files.\n\n```bash\ncodegraph affected src/utils.ts src/api.ts         # Pass files as arguments\ngit diff --name-only | codegraph affected --stdin   # Pipe from git diff\ncodegraph affected src/auth.ts --filter \"e2e/*\"     # Custom test file pattern\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--stdin` | Read file list from stdin | `false` |\n| `-d, --depth \u003cn\u003e` | Max dependency traversal depth | `5` |\n| `-f, --filter \u003cglob\u003e` | Custom glob to identify test files | auto-detect |\n| `-j, --json` | Output as JSON | `false` |\n| `-q, --quiet` | Output file paths only | `false` |\n\n**CI/hook example:**\n\n```bash\n#!/usr/bin/env bash\nAFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)\nif [ -n \"$AFFECTED\" ]; then\n  npx vitest run $AFFECTED\nfi\n```\n\n---\n\n## MCP Tools\n\nWhen running as an MCP server, CodeGraph exposes these tools to Claude Code:\n\n| Tool | Purpose |\n|------|---------|\n| `codegraph_explore` | **Primary.** Answer almost any question in one call — \"how does X work\", a flow (\"how does X reach Y\"), or surveying an area — returning the relevant symbols' verbatim source grouped by file, plus a relationship map and blast radius. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. |\n| `codegraph_search` | Find symbols by name across the codebase |\n| `codegraph_callers` | Find what calls a function |\n| `codegraph_callees` | Find what a function calls |\n| `codegraph_impact` | Analyze what code is affected by changing a symbol |\n| `codegraph_node` | Get one specific symbol's details + full source (returns every overload for an ambiguous name) |\n| `codegraph_files` | Get indexed file structure (faster than filesystem scanning) |\n| `codegraph_status` | Check index health and statistics |\n\n---\n\n## Library Usage\n\nCodeGraph can be embedded directly. The npm package re-exports its programmatic\nAPI, so both `import` and `require` resolve the `CodeGraph` class in your own\nprocess — handy for embedding it in an app (e.g. an Electron main process).\n\n```typescript\nimport CodeGraph from '@colbymchenry/codegraph';\n// CommonJS works too:\n//   const { CodeGraph } = require('@colbymchenry/codegraph');\n\nconst cg = await CodeGraph.init('/path/to/project');\n// Or: const cg = await CodeGraph.open('/path/to/project');\n\nawait cg.indexAll({\n  onProgress: (p) =\u003e console.log(`${p.phase}: ${p.current}/${p.total}`)\n});\n\nconst results = cg.searchNodes('UserService');\nconst callers = cg.getCallers(results[0].node.id);\nconst context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });\nconst impact = cg.getImpactRadius(results[0].node.id, 2);\n\ncg.watch();   // auto-sync on file changes\ncg.unwatch(); // stop watching\ncg.close();\n```\n\nLower-level building blocks are exported from the same entry point for callers\nthat drive the graph directly: `DatabaseConnection`, `QueryBuilder`,\n`getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, and `FileLock`.\n\n**Embedding requirements**\n\n- Install from npm (`npm i @colbymchenry/codegraph`) so the matching\n  per-platform package — which carries the compiled library and its\n  dependencies — is fetched alongside the shim.\n- The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in\n  `node:sqlite` (Electron qualifies when its bundled Node is 22.5+). The CLI and\n  MCP server are unaffected — they run on the self-contained bundled runtime.\n- TypeScript types ship with the package. As with any Node-targeting library,\n  keep `@types/node` available and `skipLibCheck: true` (the common default).\n\n---\n\n## Configuration\n\nThere isn't any — CodeGraph is zero-config, with **no config file** to write or\nkeep in sync. Language support is automatic from the file extension; there's\nnothing to wire up per language.\n\nWhat it skips out of the box:\n\n- **Dependency, build, and cache directories** — `node_modules`, `vendor`,\n  `dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every\n  [supported stack](#supported-languages) — so the graph is your code, not\n  third-party noise. This holds even with no `.gitignore`.\n- **Anything in your `.gitignore`** — honored in git repos via git, and in\n  non-git projects by reading `.gitignore` directly (root and nested).\n- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.\n\nTo keep something else out, add it to `.gitignore`. To pull a default-excluded\ndirectory back **in** (say you really do want a vendored dependency indexed),\nadd a negation — `!vendor/`. The defaults apply uniformly, so committing a\ndependency or build directory doesn't force it into the graph; the `.gitignore`\nnegation is the explicit opt-in.\n\n## Supported Platforms\n\nEvery release ships a self-contained build (bundled Node runtime — nothing to\ncompile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):\n\n| Platform | Architectures | Install |\n|----------|---------------|---------|\n| Windows | x64, arm64 | PowerShell installer or npm |\n| macOS | x64, arm64 | shell installer or npm |\n| Linux | x64, arm64 | shell installer or npm |\n\nSee [Get Started](#get-started) for the one-line install commands.\n\n## Supported Agents\n\nThe interactive installer auto-detects and configures each of these — wiring up\nthe MCP server (which delivers its own usage guidance, so no instructions file\nis written):\n\n- **Claude Code**\n- **Cursor**\n- **Codex CLI**\n- **opencode**\n- **Hermes Agent**\n- **Gemini CLI**\n- **Antigravity IDE**\n- **Kiro**\n\n## Supported Languages\n\n| Language | Extension | Status |\n|----------|-----------|--------|\n| TypeScript | `.ts`, `.tsx` | Full support |\n| JavaScript | `.js`, `.jsx`, `.mjs` | Full support |\n| Python | `.py` | Full support |\n| Go | `.go` | Full support |\n| Rust | `.rs` | Full support |\n| Java | `.java` | Full support |\n| C# | `.cs` | Full support |\n| PHP | `.php` | Full support |\n| Ruby | `.rb` | Full support |\n| C | `.c`, `.h` | Full support |\n| C++ | `.cpp`, `.hpp`, `.cc` | Full support |\n| Objective-C | `.m`, `.mm`, `.h` | Partial support (classes, protocols, methods, `@property`, `#import`, message sends; `.mm` ObjC++ may parse incompletely) |\n| Swift | `.swift` | Full support |\n| Kotlin | `.kt`, `.kts` | Full support |\n| Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) |\n| Dart | `.dart` | Full support |\n| Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |\n| Vue | `.vue` | Full support (script + script-setup extraction, Nuxt page/API/middleware routes) |\n| Liquid | `.liquid` | Full support |\n| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX form files) |\n| Lua | `.lua` | Full support (functions, methods with receivers, local variables, `require` imports, call edges) |\n| Luau | `.luau` | Full support (everything in Lua, plus `type`/`export type` aliases, typed signatures, and Roblox instance-path `require`) |\n\n## Troubleshooting\n\n**\"CodeGraph not initialized\"** — Run `codegraph init` in your project directory first.\n\n**Indexing is slow** — Check that `node_modules` and other large directories are excluded. Use `--quiet` to reduce output overhead.\n\n**MCP hits `database is locked`** — current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:\n\n- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.\n- **`codegraph status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.\n\n**MCP server not connecting** — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `codegraph serve --mcp` works from the command line.\n\n**Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph sync` manually if needed. Check that the file's language is supported and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`).\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=colbymchenry%2Fcodegraph\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=colbymchenry/codegraph\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=colbymchenry/codegraph\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=colbymchenry/codegraph\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\nMIT\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro**\n\n[Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolbymchenry%2Fcodegraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolbymchenry%2Fcodegraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolbymchenry%2Fcodegraph/lists"}