{"slug": "codegraph", "title": "Codegraph", "summary": "CodeGraph, a semantic code intelligence platform built for AI coding agents, launches with a CLI that generates a complete local code graph for surgical context, supporting Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro. The tool offers 100% local operation, auto-sync on file changes, and framework-aware routes for mixed iOS/React Native/Expo projects, with early beta access available at getcodegraph.com.", "body_md": "Already installed? Run `codegraph upgrade`\n\nFollow [@getcodegraph](https://x.com/getcodegraph) on X for updates.\n\n### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence\n\n**The fastest complete code graph · surgical context · built for how agents actually work · 100% local**\n\n**The CodeGraph platform is coming** — for every PR, know exactly what to test, what could break, which flows are affected, and whether business logic is compromised.\n\nGet early beta access to the hosted product · getcodegraph.com\n\n[Get Started](#get-started)[Language Support](#language-support)[Why CodeGraph?](#why-codegraph)[Key Features](#key-features)[Framework-aware Routes](#framework-aware-routes)[Mixed iOS / React Native / Expo bridging](#mixed-ios--react-native--expo-bridging)[Quick Start](#quick-start)[How It Works](#how-it-works)[CLI Reference](#cli-reference)[MCP Tools](#mcp-tools)[Library Usage](#library-usage)[Configuration](#configuration)[Telemetry](#telemetry)[Verified releases](#verified-releases)[Supported Platforms](#supported-platforms)[Supported Agents](#supported-agents)[Supported Languages](#supported-languages)[Measured cross-file coverage](#measured-cross-file-coverage)[Troubleshooting](#troubleshooting)[License](#license)\n\n**No Node.js required** — one command grabs the right build for your OS:\n\n```\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\n**Already have Node? Use npm instead (works on any version)**\n\n```\nnpm i -g @colbymchenry/codegraph\n```\n\nCodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts codegraph on your PATH but doesn't change your current shell — open a new terminal before the next step so the command resolves.\n\n**Upgrade any time** with `codegraph upgrade`\n\n— it detects how you installed (bundle, npm, or npx) and updates in place. Add `--check`\n\nto see if an update is available, or `codegraph upgrade <version>`\n\nto pin one.\n\nIn a **new terminal**, run the installer to connect CodeGraph to the agents you use:\n\n```\ncodegraph install\n```\n\nDetects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. This is the step that connects CodeGraph to your agent; installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does not index any code; building each project's graph is the separate\n\n`codegraph init`\n\nin step 3. (Shortcut: `npx @colbymchenry/codegraph`\n\ndownloads and runs this in one go.)\n\n```\ncd your-project\ncodegraph init\n```\n\n`codegraph init`\n\ncreates the local `.codegraph/`\n\ndirectory and builds the full graph in the same step — one command, done.\n\nAuto-sync is enabled by default. CodeGraph watches the project and updates the graph on every file change — while your agent edits code, or you add, modify, or delete files. **The index is never stale, and there is nothing to re-run.**\n\nChanged your mind? One command removes CodeGraph from every agent it configured **and** the CLI itself — every install it finds (standalone bundle, npm global package, launcher link), shown to you before anything is deleted:\n\n```\ncodegraph uninstall\n```\n\nPass `--keep-cli`\n\nto remove only the agent configurations and keep the CLI installed.\n\nReverses 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.\n\nEvery language below gets the same treatment — full structural extraction and cross-file resolution into one graph, no per-language setup:\n\nPer-language details — extensions, frameworks, and what exactly gets extracted — in Supported Languages.\n\nWhen an AI agent needs to understand code — to answer a question or make a change — it discovers structure the slow way: grep, glob, and Read, one file at a time, rebuilding call paths and dependencies by hand. That's a pile of tool calls and round-trips before it even starts the real work.\n\n**CodeGraph hands the agent the exact code it needs in one call.** It's a pre-built knowledge graph of every symbol, call edge, and dependency in your codebase — so instead of crawling files, the agent asks one question and gets back the relevant source, the call paths between those symbols (including dynamic-dispatch hops grep can't follow), and the blast radius of a change. **Surgical context, not a file-by-file search** — which means fewer tool calls and faster answers on every codebase, large or small.\n\nA note on cost:CodeGraph's win oneverycodebase is precision — the agent stops crawling files and answers from the graph. On current models that precision is also a large direct saving: the 2026-07 re-validation measured60% lower cost and 69% fewer tokens on averageacross the seven benchmark repos, because a strong modelwithoutthe graph burns millions of tokens re-deriving structure. The savings scale with repo size and tangle — dramatic on VS-Code-class trees, modest on a 100-file project — and compound across a team's daily agent usage.\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, at the **median of 4 runs per arm**. *Re-validated 2026-07-21 on Claude Opus 4.8 against the current build — the Rust kernel plus this cycle's resolution overhaul.*\n\nThe universal win — every repo, every size: 89% fewer tool calls · 60% cheaper · 69% fewer tokens · file reads cut to zero on all seven repos.\n\nWith the index available, the agent answers from a couple of `codegraph_explore`\n\ncalls and stops. Without it, the agent burns its budget on discovery — up to **57 tool calls and 4.3M tokens** re-deriving what the graph already knew. The **Time** column averages 20% faster but is the noisiest metric: on two small repos a strong model's raw grep loop finishes the wall-clock race sooner while still spending 5–10× the tokens and money — noted per-row below.\n\n| Codebase | Language | Tool calls | Time | File reads | Tokens | Cost |\n|---|---|---|---|---|---|---|\nVS Code |\nTypeScript · ~11k files | 2 vs 40 |\n5× faster (41s vs 3m 24s) |\n0 vs 17 |\n83% fewer | 75% cheaper |\nExcalidraw |\nTypeScript · ~640 | 3 vs 55 | 36s vs 23s¹ | 0 vs 24 |\n89% fewer | 78% cheaper |\nDjango |\nPython · ~3k | 2 vs 29 |\n38% faster | 0 vs 16 |\n78% fewer | 69% cheaper |\nTokio |\nRust · ~790 | 3 vs 57 | 65% faster | 0 vs 15 |\n91% fewer | 86% cheaper |\nOkHttp |\nJava · ~645 | 1 vs 5 | 10% faster | 0 vs 1 |\n33% fewer | ~even² |\nGin |\nGo · ~110 | 3 vs 10 | 57% faster | 0 vs 4 |\n18% fewer | 41% cheaper |\nAlamofire |\nSwift · ~110 | 3 vs 53 | 49s vs 31s¹ | 0 vs 18 |\n90% fewer | 86% cheaper |\n\n¹ The small-repo floor effect: Opus 4.8 greps small trees fast enough to win wall-clock while spending ~5–10× the tokens and ~4–7× the cost — the with-arm still answers from zero file reads. ² OkHttp's without-arm got lucky in 5 calls; the with-arm answered in 1 call for ~$0.03 more. File reads = median files opened — the surgical-context win in one column: the agent never reads a file on any of the seven repos when CodeGraph is present.\n\n**Per-repo breakdown — WITH vs WITHOUT (median of 4)**\n\n| Codebase | Metric | WITH cg | WITHOUT cg |\n|---|---|---|---|\nVS Code |\nTime / Tools / Tokens / Cost | 41s / 2 / 265k / $0.36 | 3m 24s / 40 / 1.5M / $1.41 |\nExcalidraw |\nTime / Tools / Tokens / Cost | 36s / 3 / 324k / $0.40 | 23s / 55 / 2.9M / $1.81 |\nDjango |\nTime / Tools / Tokens / Cost | 42s / 2 / 254k / $0.35 | 1m 8s / 29 / 1.2M / $1.13 |\nTokio |\nTime / Tools / Tokens / Cost | 46s / 3 / 386k / $0.44 | 2m 11s / 57 / 4.3M / $3.04 |\nOkHttp |\nTime / Tools / Tokens / Cost | 27s / 1 / 156k / $0.23 | 30s / 5 / 233k / $0.20 |\nGin |\nTime / Tools / Tokens / Cost | 30s / 3 / 246k / $0.27 | 1m 10s / 10 / 300k / $0.46 |\nAlamofire |\nTime / Tools / Tokens / Cost | 49s / 3 / 316k / $0.35 | 31s / 53 / 3.1M / $2.51 |\n\n**Full benchmark details**\n\n**Methodology.** Each arm is `claude -p`\n\n(Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`\n\n: **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`\n\n; 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`\n\nand indexed by the same CodeGraph build that served them. Re-validated 2026-07-21 on the current build (native Rust kernel, adaptive parallel resolution, scoped sync).\n\n**Queries:**\n\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`\n\nreturns the relevant source — and stops, with zero file reads on every benchmark repo. 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\nCodeGraph's parsing engine is a **native Rust kernel**: 20 languages — TypeScript, JavaScript, Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, R, Lua, Luau (Metal and CUDA ride the C++ path) — parse in compiled code with one boundary crossing per file. Every language shipped only after its graphs proved **byte-for-byte identical** to the reference engine on real repositories, from small libraries up to the Linux kernel; platforms without a prebuilt binary and files with syntax errors fall back per-file automatically, same graph either way.\n\n**And it scales itself to the machine it's on.** Worker pools, parallel resolution, and analysis caches are sized from what the system actually has — real core counts (container/cgroup-aware, so a VPS that grants 2 cores gets sized for 2, not the host's 64), honestly-measured available RAM on macOS and Linux, and the measured cost of *your* project's resolution work:\n\n**On a workstation:** the full parallel pipeline — native parse workers, a multi-worker resolver pool that engages the moment it pays for itself, memory-gated analysis caches. The Swift compiler repository (27k files of Swift and C++) fresh-indexes in about 100 seconds; a one-file edit re-syncs in ~4.**On a 2-core / 6GB VPS:** the same graph, from a pipeline tuned to*finish*— the Linux kernel (70k files, 2M symbols, 6.4M relationships) indexes to completion in under 12 minutes where RAM-first designs run out of memory before reaching 1%.**Every day after day one:** saving a file updates the graph in well under a second — the watcher fires 300ms after a lone save and syncs exactly what changed (~0.3s of work on a 4,400-file project, ~0.4s on the 27,000-file Swift compiler repo), never re-scanning the tree. Measured against the fastest competing indexer's re-index-on-change: 2–7× faster on medium and larger repos across a 31-repo, 30-language benchmark — and the gap widens with repo size, because their cost grows with the repository and ours grows with the change.\n\nNative Rust Kernel |\nParsing and extraction run in a compiled Rust engine for 20 languages — with graphs verified byte-for-byte identical to the reference engine, and automatic per-file fallback so nothing ever breaks |\nAdapts to Your Machine |\nSizes its worker pools and caches from what the system actually has — real core counts (container-aware), honest available RAM, measured per-project cost. A workstation gets the full parallel pipeline; a 2-core VPS gets one tuned to finish reliably |\nSurgical Context |\nOne tool call returns entry points, related symbols, and code snippets — no slow file-by-file exploration |\nFull-Text Search |\nFind code by name instantly across your entire codebase, powered by FTS5 |\nImpact Analysis |\nTrace callers, callees, and the full impact radius of any symbol before making changes |\nAlways Fresh |\nFile watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |\n20+ Languages |\nTypeScript, JavaScript, ArkTS, Python, Go, Rust, Java, C#, VB.NET, PHP, Ruby, C, C++, CUDA, Objective-C, Metal, Swift, Kotlin, Scala, Dart, Lua, Luau, R, Nix, Erlang, CFML, COBOL, Solidity, Terraform/OpenTofu, Svelte, Vue, Astro, Liquid, Pascal/Delphi |\nFramework-aware Routes |\nRecognizes web-framework routing files and links URL patterns to their handlers across 17 frameworks |\nMixed iOS / React Native / Expo |\nCloses cross-language flows that static parsing misses: Swift ↔ ObjC bridging, React Native legacy bridge + TurboModules + Fabric view components, native → JS event emitters, Expo Modules |\n100% Local |\nNo data leaves your machine. No API keys. No external services. SQLite database only |\n\n**How auto-syncing works — and why you don't need to run **`codegraph sync`\n\nmanually\n\n`codegraph sync`\n\nmanuallyWhen your agent (Claude Code, Cursor, Codex, opencode) launches `codegraph serve --mcp`\n\n, 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\n-\n**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`\n\n, tunable via`CODEGRAPH_WATCH_DEBOUNCE_MS`\n\n, clamped to`[100ms, 60s]`\n\n). Bursts of edits collapse into a single sync. -\n**Per-file staleness banner.** During the brief debounce window, MCP tool responses that would reference a still-pending file prepend a`⚠️`\n\nbanner naming it and telling the agent to`Read`\n\nit 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**Connect-time catch-up.** When the MCP server (re)connects, codegraph runs a fast`(size, mtime)`\n\n+ content-hash reconciliation against the working tree before answering the first query — so edits made while no MCP server was running (a`git pull`\n\nfrom 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 (<100ms)\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`\n\n(CLI). If anything is pending, you'll see a `### Pending sync:`\n\nsection naming the files and their edit age.\n\nThe handful of cases where manual `codegraph sync`\n\nmakes sense: the watcher is disabled (sandboxed environments, or `CODEGRAPH_NO_DAEMON=1`\n\n), 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\nCodeGraph detects web-framework routing files and emits `route`\n\nnodes linked by `references`\n\nedges 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|---|---|\nDjango |\n`path()` , `re_path()` , `url()` , `include()` in `urls.py` (CBV `.as_view()` , dotted paths) |\nFlask |\n`@app.route('/path', methods=[...])` , blueprint routes |\nFastAPI |\n`@app.get(...)` , `@router.post(...)` , all standard methods |\nExpress |\n`app.get(...)` , `router.post(...)` with middleware chains |\nNestJS |\n`@Controller` + `@Get/@Post/...` , GraphQL `@Resolver` + `@Query/@Mutation` , `@MessagePattern` /`@EventPattern` , `@SubscribeMessage` |\nLaravel |\n`Route::get()` , `Route::resource()` , `Controller@action` , tuple syntax |\nDrupal |\n`*.routing.yml` routes (`_controller` , `_form` , entity handlers); `hook_*` implementations in `.module` /`.theme` /`.install` /`.inc` |\nRails |\n`get '/x', to: 'users#index'` , hash-rocket `=>` syntax |\nSpring |\n`@GetMapping` , `@PostMapping` , `@RequestMapping` on methods |\nPlay |\n`GET` /`POST` /… verb routes in `conf/routes` → `Controller.method` actions (Scala + Java) |\nGin / chi / gorilla / mux |\n`r.GET(...)` , `router.HandleFunc(...)` |\nAxum / actix / Rocket |\n`.route(\"/x\", get(handler))` |\nASP.NET |\n`[HttpGet(\"/x\")]` attributes on action methods |\nVapor |\n`app.get(\"x\", use: handler)` |\nReact Router / SvelteKit |\nRoute component nodes |\nVue Router / Nuxt |\n`pages/` file-based routes, `server/api/` endpoints, route middleware |\nAstro |\n`src/pages/` file-based routes (`.astro` pages + `.ts` endpoints, `[param]` /`[...rest]` syntax) |\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 `codegraph_explore`\n\nconnects the flow end-to-end across the gap — call paths and blast radius cross the boundary instead of stopping at it.\n\n| Boundary | JS / Swift side | Native side | How |\n|---|---|---|---|\nSwift → ObjC |\nSwift `obj.foo(bar:)` |\nObjC selector `-fooWithBar:` |\n`@objc` auto-bridging rules (including init/property/protocol forms) + Cocoa preposition prefixes (`With` /`For` /`By` /`In` /`On` /`At` /…) |\nObjC → Swift |\nObjC `[obj fooWithBar:]` |\nSwift `@objc func foo(bar:)` |\nReverse-bridge name candidates; verifies `@objc` exposure from source |\nReact Native legacy bridge |\nJS `NativeModules.X.fn(...)` |\nObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` |\nParses macro/annotation declarations to build a JS-name → native-method map |\nReact Native TurboModules |\nJS `import M from './NativeM'; M.fn(...)` |\nNative impl matching the Codegen spec | Treats the `Native<X>.ts` spec interface as ground truth |\nRN native → JS events |\nJS `new NativeEventEmitter(...).addListener('e', cb)` |\nObjC `[self sendEventWithName:@\"e\" body:...]` · Swift `sendEvent(withName: \"e\", ...)` · Java/Kotlin `.emit(\"e\", ...)` |\nSynthesized cross-language event channel keyed by literal event name |\nExpo Modules |\nJS `requireNativeModule('X').fn(...)` |\nSwift / Kotlin `Module { Name(\"X\"); AsyncFunction(\"fn\") { ... } }` |\nParses the Expo DSL literals; synthetic method nodes resolve via existing name-match |\nFabric view components |\nJSX `<MyView prop={v}/>` |\nTS Codegen spec + native impl class | Spec → `component` node; convention-based name+suffix lookup (`View` /`ComponentView` /`Manager` /`ViewManager` ) bridges to native |\nLegacy Paper view managers |\nJSX `<MyView prop={v}/>` |\nObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` |\nSame 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 |\n|\n\n[realm-swift](https://github.com/realm/realm-swift)[Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios)[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)[RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service)[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)Each bridge emits edges tagged `provenance:'heuristic'`\n\nwith `metadata.synthesizedBy:`\n\nset to a stable channel name (e.g. `swift-objc-bridge`\n\n, `rn-event-channel`\n\n, `fabric-native-impl`\n\n, `expo-module-extract`\n\n), so the agent can tell at a glance how a hop got into the graph.\n\n```\nnpx @colbymchenry/codegraph\n```\n\nThe installer will:\n\n- Ask which agent(s) to configure — auto-detects installed ones from:\n**Claude Code**,** Cursor**,** Codex CLI**,** opencode**,** Hermes Agent**,** Gemini CLI**,** Antigravity IDE**,** Kiro** - Prompt to install\n`codegraph`\n\non your PATH (so agents can launch the MCP server) - Ask whether configs apply to all your projects or just this one\n- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (\n`CLAUDE.md`\n\n/`AGENTS.md`\n\n/`GEMINI.md`\n\n) — that's how subagents and non-MCP agents learn the`codegraph explore`\n\ncommand, since the MCP server's own guidance only reaches the main agent. Removed cleanly by`codegraph uninstall`\n\n. - Set up auto-allow permissions when Claude Code is one of the targets\n\nThe installer **wires up your agents only — it does not index your code.** After it finishes, build each project's graph yourself with `codegraph init`\n\n(step 3). One global `codegraph install`\n\ncovers every project; you run `codegraph init`\n\nonce per project.\n\n**Non-interactive (scripting / CI):**\n\n```\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` |\n`auto` , `all` , `none` , or csv (`claude,cursor,...` ) |\nprompt |\n`--location` |\n`global` , `local` |\nprompt |\n`--yes` |\n(boolean) | prompt every step |\n`--no-permissions` |\n(boolean) skip Claude auto-allow list | permissions on |\n`--print-config <id>` |\ndump snippet for one agent and exit | — |\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```\ncd your-project\ncodegraph init\n```\n\nBuilds the per-project knowledge graph index, which then auto-syncs on every file change. A single global `codegraph install`\n\nworks 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/`\n\ndirectory exists.\n\n**Manual Setup (Alternative)**\n\n**Install globally:**\n\n```\nnpm install -g @colbymchenry/codegraph\n```\n\n**Add to ~/.claude.json:**\n\n```\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\n```\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__codegraph__*\"\n    ]\n  }\n}\n```\n\nOne wildcard auto-approves every CodeGraph tool — codegraph_explore is the only one listed by default, but if you re-enable others via CODEGRAPH_MCP_TOOLS they're already permitted, no prompt.\n\n**Agent Tool Guidance**\n\nCodeGraph's MCP server delivers its usage guidance to your agent **automatically**, in the MCP `initialize`\n\nresponse. 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.**Reach for**— \"how does X work\", a flow/\"how does X reach Y\", or surveying an area. One call returns the relevant symbols' verbatim source grouped by file, the call paths between them (dynamic-dispatch hops included), and a blast-radius summary. Name a file or symbol in the query to read its current line-numbered source.`codegraph_explore`\n\nfor almost anything**Trust the results — don't re-verify with grep**, and check the staleness banner after edits.- Works\n**per project**: query any project that has a`.codegraph/`\n\nindex by passing`projectPath`\n\n— so a monorepo where only some services are indexed, or a second repo, works in one session. A path with no index returns clean guidance to use built-in tools; indexing stays your decision.\n\nThe exact text is `src/mcp/server-instructions.ts`\n\n— the single source of truth for the main agent. Because subagents and non-MCP harnesses never see the MCP guidance, the installer also writes a short marker-fenced section into the agent's instructions file pointing at the `codegraph explore`\n\nCLI equivalent.\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  ·  one call → verbatim source + call flow + blast radius │\n│                                 │                                 │\n│                                 ▼                                 │\n│                       SQLite knowledge graph                      │\n│          symbols · edges · files · FTS5 full-text search          │\n└───────────────────────────────────────────────────────────────────┘\n```\n\n-\n**Extraction**— a native** Rust kernel**parses source with[tree-sitter](https://tree-sitter.github.io/)grammars compiled into it, extracting nodes (functions, classes, methods) and edges (calls, imports, extends, implements) for 20 languages; remaining languages and per-file fallbacks use the same extraction logic on the portable engine, producing identical graphs. -\n**Storage**— Everything goes into a local SQLite database (`.codegraph/codegraph.db`\n\n) with FTS5 full-text search. -\n**Resolution**— After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. -\n**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```\ncodegraph                         # Run interactive installer\ncodegraph install                 # Run installer (explicit)\ncodegraph uninstall               # Remove CodeGraph from your agents AND the CLI (--keep-cli for configs only)\ncodegraph init [path]             # Initialize a project + build its graph (one step)\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 unlock [path]           # Remove a stale lock file that's blocking indexing\ncodegraph query <search>          # Search symbols (--kind, --limit, --json)\ncodegraph explore <query>         # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)\ncodegraph node <symbol|file>      # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)\ncodegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)\ncodegraph callers <symbol>        # Find what calls a function/method (--limit, --json)\ncodegraph callees <symbol>        # Find what a function/method calls (--limit, --json)\ncodegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)\ncodegraph affected [files...]     # Find test files affected by changes (see below)\ncodegraph daemon                  # Manage background daemons — pick one to stop (alias: daemons)\ncodegraph telemetry [on|off]      # Show or change anonymous usage telemetry\ncodegraph upgrade [version]       # Update to the latest release (--check, --force)\ncodegraph version                 # Print the installed version (also -v, --version)\ncodegraph help [command]          # Show help, optionally for one command\n```\n\nTraces import dependencies transitively to find which test files are affected by changed source files.\n\n```\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` |\nRead file list from stdin | `false` |\n`-d, --depth <n>` |\nMax dependency traversal depth | `5` |\n`-f, --filter <glob>` |\nCustom glob to identify test files | auto-detect |\n`-j, --json` |\nOutput as JSON | `false` |\n`-q, --quiet` |\nOutput 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\nWhen running as an MCP server, CodeGraph exposes a **single tool** — `codegraph_explore`\n\n. Measured agent behavior showed that one strong tool steers agents better than a menu of narrower ones — fewer mis-picks, and it saves context every session:\n\n| Tool | Purpose |\n|---|---|\n`codegraph_explore` |\nAnswer 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 the call paths between them and a blast-radius summary. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. Name a file or symbol in the query to read its current line-numbered source, the same shape the Read tool gives you. |\n\nThe other tools (`codegraph_node`\n\n, `codegraph_search`\n\n, `codegraph_callers`\n\n, `codegraph_callees`\n\n, `codegraph_impact`\n\n, `codegraph_files`\n\n, `codegraph_status`\n\n) stay fully functional but **unlisted by default** — everything they return already arrives inline on `codegraph_explore`\n\n(its blast-radius section, the relationship map, a symbol's body as its callee list). Re-enable any of them for the MCP surface with the `CODEGRAPH_MCP_TOOLS`\n\nenvironment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`\n\n), or use their CLI equivalents (`codegraph node`\n\n/ `query`\n\n/ `callers`\n\n/ `callees`\n\n/ `impact`\n\n/ `files`\n\n/ `status`\n\n).\n\nEven when the server's own root has no `.codegraph/`\n\nindex, the tools stay available: pass `projectPath`\n\nto query any indexed project — a sub-service in a monorepo, or a second repo — in the same session. A path that has no index returns clean guidance to use built-in tools instead, so nothing fails loudly, and indexing stays your decision.\n\nCodeGraph can be embedded directly. The npm package re-exports its programmatic\nAPI, so both `import`\n\nand `require`\n\nresolve the `CodeGraph`\n\nclass in your own\nprocess — handy for embedding it in an app (e.g. an Electron main process).\n\n``` python\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) => 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`\n\n, `QueryBuilder`\n\n,\n`getDatabasePath`\n\n, `initGrammars`\n\n/ `loadGrammarsForLanguages`\n\n, and `FileLock`\n\n.\n\n**Embedding requirements**\n\n- Install from npm (\n`npm i @colbymchenry/codegraph`\n\n) so the matching per-platform package — which carries the compiled library and its dependencies — is fetched alongside the shim. - The API runs on\n**your** runtime, so it needs**Node 22.5+** for the built-in`node:sqlite`\n\n(Electron qualifies when its bundled Node is 22.5+). The CLI and MCP server are unaffected — they run on the self-contained bundled runtime. - TypeScript types ship with the package. As with any Node-targeting library,\nkeep\n`@types/node`\n\navailable and`skipLibCheck: true`\n\n(the common default).\n\nNext to none — CodeGraph is **zero-config by default**, with nothing to write or\nkeep in sync to get started. Language support is automatic from the file\nextension; there's nothing to wire up per language. The one optional file is for\nmapping [custom file extensions](#custom-file-extensions).\n\nWhat it skips out of the box:\n\n**Dependency, build, and cache directories**—`node_modules`\n\n,`vendor`\n\n,`dist`\n\n,`build`\n\n,`target`\n\n,`.venv`\n\n,`Pods`\n\n,`.next`\n\n, and the like across every[supported stack](#supported-languages)— so the graph is your code, not third-party noise. This holds even with no`.gitignore`\n\n.**Anything in your**— honored in git repos via git, and in non-git projects by reading`.gitignore`\n\n`.gitignore`\n\ndirectly (root and nested).**Files larger than 1 MB**— generated bundles, minified JS, vendored blobs.\n\nTo keep something else out, add it to `.gitignore`\n\n. To pull a default-excluded\ndirectory back **in** (say you really do want a vendored dependency indexed),\nadd a negation — `!vendor/`\n\n. The defaults apply uniformly, so committing a\ndependency or build directory doesn't force it into the graph; the `.gitignore`\n\nnegation is the explicit opt-in.\n\n`.gitignore`\n\ncan't drop a directory you've **committed**, though. For a vendored\ntheme or SDK that's checked into the repo (e.g. a Metronic theme under\n`static/`\n\n), list it under `exclude`\n\nin `codegraph.json`\n\n— gitignore-style\npatterns, matched against repo-root-relative paths, honored on index, sync, and\nwatch:\n\n```\n{\n  \"exclude\": [\"static/\", \"**/vendor/**\"]\n}\n```\n\nConversely, when real source is gitignored on purpose — a project under a second\nVCS (SVN, Perforce) that `.gitignore`\n\ns its own source so it stays out of Git —\nforce it back in with `include`\n\n(the opposite of `exclude`\n\n; `includeIgnored`\n\nonly revives embedded git repos, not plain source):\n\n```\n{\n  \"include\": [\"Tools/\", \"Local/typescript/\"]\n}\n```\n\nCodeGraph discovers those files off disk, overriding `.gitignore`\n\n, on index,\nsync, and watch. An explicit `exclude`\n\nstill wins, and built-in skips\n(`node_modules`\n\n, `dist`\n\n, `.git`\n\n) are never re-included.\n\nIf your project uses a non-standard extension for a [supported\nlanguage](#supported-languages) — say `.dota_lua`\n\nfor Lua, or `.tpl`\n\nfor PHP —\nthose files are skipped by default, because the extension isn't one CodeGraph\nrecognizes. Map them with an optional ** codegraph.json** at your project root:\n\n```\n{\n  \"extensions\": {\n    \".dota_lua\": \"lua\",\n    \".tpl\": \"php\"\n  }\n}\n```\n\nEach value is a supported language id. The mappings merge on top of the built-in\ndefaults and win on conflict, so you can also re-point a built-in (e.g.\n`\".h\": \"cpp\"`\n\n). Commit the file to share the mapping with your team. A typo'd\nlanguage or a malformed file is warned about and skipped — it never breaks\nindexing — and a project with no `codegraph.json`\n\nbehaves exactly as before.\nRe-index (`codegraph index`\n\n) after adding or changing mappings.\n\nCodeGraph collects **anonymous usage statistics** — which tools and commands get\nused, which languages get indexed — to guide where language and agent support\nwork goes. **Never** any code, paths, file or symbol names, queries, or IP\naddresses; usage is aggregated locally into daily totals before anything is\nsent, and the ingest endpoint is [public code in this repo](/colbymchenry/codegraph/blob/main/telemetry-worker)\nthat enforces the documented field list. The installer asks up front; turn it\noff any time:\n\n```\ncodegraph telemetry off    # or: CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1\n```\n\n[ TELEMETRY.md](/colbymchenry/codegraph/blob/main/TELEMETRY.md) lists every field, with the off-switches and the\nfull data-handling story.\n\nEvery artifact is built and published by the public\n[Release workflow](/colbymchenry/codegraph/blob/main/.github/workflows/release.yml) — never from a laptop — and\ncarries cryptographic proof of it:\n\n-\n**npm packages** are published via[trusted publishing](https://docs.npmjs.com/trusted-publishers)(OIDC — no long-lived npm tokens exist that could be stolen) with[provenance attestations](https://docs.npmjs.com/generating-provenance-statements)linking every version to the exact commit and workflow run that built it. Verify what's installed:\n\n```\nnpm audit signatures\n```\n\n-\n**GitHub Release bundles**(and`SHA256SUMS`\n\n) carry signed[build attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)(SLSA v1.0 Build Level 2). Verify any downloaded bundle:\n\n```\ngh attestation verify codegraph-darwin-arm64.tar.gz -R colbymchenry/codegraph\n```\n\nReleases published before July 2026 predate this pipeline and don't carry attestations.\n\nEvery release ships a self-contained build (bundled Node runtime — nothing to compile) 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\nThe interactive installer auto-detects and configures each of these — wiring up the MCP server (which delivers its own usage guidance, so no instructions file is written):\n\n**Claude Code****Cursor****Codex CLI****opencode****Hermes Agent****Gemini CLI****Antigravity IDE****Kiro**\n\n| Language | Extension | Status |\n|---|---|---|\n| TypeScript | `.ts` , `.tsx` |\nFull support |\n| JavaScript | `.js` , `.jsx` , `.mjs` |\nFull support |\n| ArkTS (HarmonyOS) | `.ets` |\nFull support (everything TypeScript has, plus `@Component` /`@ComponentV2` structs with their ArkUI decorators (`@State` /`@Prop` /`@Link` /`@Local` /`@Builder` /…), `build()` view trees — parent→child component edges, chained-attribute links to `@Extend` /`@Styles` functions, `.onClick(this.handler)` event bindings — dynamic-dispatch bridges for state→`build()` re-renders, `@ohos.events.emitter` emit→subscriber pairs (static event keys only), and `router.pushUrl` literal urls → the target page struct; ohpm workspace modules resolve bare `import { X } from \"data\"` through `oh-package.json5` `file:` dependencies, honoring each module's `main` entry) |\n| Python | `.py` |\nFull support |\n| Go | `.go` |\nFull support |\n| Rust | `.rs` |\nFull support |\n| Java | `.java` |\nFull support |\n| C# | `.cs` |\nFull support |\n| PHP | `.php` |\nFull support |\n| Ruby | `.rb` |\nFull support |\n| C | `.c` , `.h` |\nFull support |\n| C++ | `.cpp` , `.hpp` , `.cc` |\nFull support |\n| Objective-C | `.m` , `.mm` , `.h` |\nPartial support (classes, protocols, methods, `@property` , `#import` , message sends; `.mm` ObjC++ may parse incompletely) |\n| Metal | `.metal` |\nFull support (vertex/fragment/kernel functions, structs, type aliases, call edges — MSL parses as C++, with `[[attribute]]` annotations handled) |\n| CUDA | `.cu` , `.cuh` |\nFull support (kernels and device/host functions, structs, classes, host→kernel call edges through `<<<grid, block>>>` launch syntax — templated launches, function-pointer launches (`auto kernel = &fn<...>` ), `dim3{...}` configs, and macro-defined kernels included; `__global__` /`__device__` /`__launch_bounds__` specifiers handled; CUDA in plain `.h` /`.hpp` headers recognized by content) |\n| Swift | `.swift` |\nFull support |\n| Kotlin | `.kt` , `.kts` |\nFull support |\n| Scala | `.scala` , `.sc` |\nFull support (classes, traits, methods, type aliases, Scala 3 enums) |\n| Dart | `.dart` |\nFull support |\n| Svelte | `.svelte` |\nFull support (script extraction, Svelte 5 runes, SvelteKit routes) |\n| Vue | `.vue` |\nFull support (script + script-setup extraction, Nuxt page/API/middleware routes) |\n| Astro | `.astro` |\nFull support (frontmatter + script extraction, template component/call references, `src/pages/` routes) |\n| Liquid | `.liquid` |\nFull support |\n| Pascal / Delphi | `.pas` , `.dpr` , `.dpk` , `.lpr` |\nFull support (classes, records, interfaces, enums, DFM/FMX form files) |\n| Lua | `.lua` |\nFull support (functions, methods with receivers, local variables, `require` imports, call edges) |\n| R | `.R` `.r` |\nFull support (functions in every assignment form, S4/R5/R6 classes with methods, `library` /`require` imports, `source()` file references, call edges) |\n| Luau | `.luau` |\nFull support (everything in Lua, plus `type` /`export type` aliases, typed signatures, and Roblox instance-path `require` ) |\n| CFML | `.cfc` , `.cfm` , `.cfs` |\nFull support (tag-based `<cfcomponent>` /`<cffunction>` and bare-script `component { ... }` styles, `extends` /`implements` , embedded `<cfscript>` delegation, call edges) |\n| COBOL | `.cbl` , `.cob` , `.cpy` |\nFull support (programs, sections/paragraphs with PERFORM/GO TO call edges, CALL 'literal' cross-program calls, COPY copybook imports — including standalone `.cpy` files — DATA DIVISION records/fields/88-levels, EXEC CICS LINK/XCTL and EXEC SQL INCLUDE targets; fixed and free format) |\n| Visual Basic .NET | `.vb` |\nFull support (classes, Modules, interfaces, structures, enums, properties, events, `Declare` P/Invoke, `Handles` /`WithEvents` , `Inherits` /`Implements` edges, call edges through VB's call/index paren ambiguity, `As New` instantiation, interpolated strings, LINQ, Unicode identifiers) |\n| Erlang | `.erl` , `.hrl` , `.escript` , `.app.src` , `.app` |\nFull support (functions with multi-clause/multi-arity grouping, `-spec` signatures, records with fields, `-type` /`-opaque` aliases, `-define` macros, `-include` /`-include_lib` /`-import` edges, local and `mod:fn` remote call edges, `fun name/arity` references, `spawn` /`apply` /`proc_lib` /`timer` /`rpc` MFA-argument call edges, `gen_server:call/cast(?MODULE)` → own `handle_call` /`handle_cast` links, `-behaviour` links, `-export` -based visibility) |\n| Solidity | `.sol` |\nFull support (contracts, libraries, interfaces, structs, enums, modifiers, events, errors, state variables, `import` /`using` directives, `emit` /`revert` calls) |\n| Terraform / OpenTofu | `.tf` , `.tfvars` , `.tofu` |\nFull support (resources, data sources, modules, variables, outputs, providers incl. aliases, `locals` ; `var.` /`local.` /`module.` /resource references with Terraform's per-directory scoping enforced; module calls bridged across the boundary — inputs to the child module's variables, `module.M.out` to the child's output, `source` to the module's files; cloudposse/atmos `remote-state` cross-component wiring when the component is statically named; `provider = aws.east` selections resolved up the module tree; `moved` /`import` /`removed` /`check` block references; `.tfvars` assignments linked to the variables they set) |\n| Nix | `.nix` |\nFull support (functions with simple/destructured/curried params, `let` /attrset bindings, `inherit` , `import ./path` file edges — `./dir` resolving through `default.nix` — plus NixOS module `imports = [ ./x.nix ]` lists and `callPackage ./pkg.nix` file edges; call edges; module-system option wiring — a config write like `launchd.user.agents.x = { ... }` links to the module declaring `options.launchd.user.agents` , so option flows trace across modules) |\n\nImpact and blast-radius queries are only as good as the dependency graph behind them, so coverage is measured rather than asserted. **Fair coverage** = the share of symbol-bearing source files that have at least one *resolved cross-file dependent* — something that imports, calls, references, or (through a framework convention) routes to them — on a real-world benchmark repo per language. The residual is always a genuine static-analysis frontier (runtime dynamic dispatch, reflection / DI containers, framework-convention entry points, vendored third-party code), never hidden by gaming the denominator.\n\n| Language | Benchmark repo | Coverage |\n|---|---|---|\n| TypeScript / JavaScript | this repo | 95.8% |\n| Python | psf/requests | 100% |\n| Go | gin-gonic/gin | 96.6% |\n| Rust | BurntSushi/ripgrep | 86.7% |\n| Java | google/gson | 93.3% |\n| C# | jbogard/MediatR | 85.2% |\n| PHP | guzzle/guzzle | 100% |\n| Ruby | sidekiq/sidekiq | 100% |\n| C | redis/redis | 92.2% |\n| C++ | google/leveldb | 94.8% |\n| Objective-C | SDWebImage | 91.6% |\n| Swift | Alamofire | 95.3% |\n| Kotlin | square/okhttp | 96.2% |\n| Scala | gatling/gatling | 91.2% |\n| Dart | flutter/packages | 92.4% |\n| Svelte / SvelteKit | sveltejs/realworld | 100% |\n| Vue / Nuxt | nuxt/movies | 93.5% |\n| Astro | xingwangzhe/stalux | 93.0% |\n| Lua | nvim-telescope/telescope.nvim | 84.2% |\n| Luau | dphfox/Fusion | 92.2% |\n| Liquid | Shopify/dawn | 73.8% |\n| Pascal / Delphi | PascalCoin | 77.4% |\n\nFramework routing is validated the same way, on a canonical app per framework: Express 100%, FastAPI 98%, Flask 100%, NestJS 96.8%, Gin 96.5%, Axum 100%, Rocket 93.8%, Vapor 100%, Laravel 92%, Rails 89.6%, React Router 100% — and the convention/reflection-heavy ones at their honest static-analysis ceiling: ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Play 76.3%, Django 74.1%. SvelteKit, Vue/Nuxt, and Astro use file-based routing, so their page/endpoint coverage is the Svelte/SvelteKit (100%), Vue/Nuxt (93.5%), and Astro (93.0% — every `src/pages/`\n\nfile maps to a route node on the two validation repos) figures in the table above.\n\n**\"CodeGraph not initialized\"** — Run `codegraph init`\n\nin your project directory first.\n\n**Indexing is slow** — Check that `node_modules`\n\nand other large directories are excluded. Use `--quiet`\n\nto 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\n\n`node:sqlite`\n\nin WAL mode, where concurrent reads never block on a writer. If you still see it:**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`\n\n(macOS/Linux),`irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex`\n\n(Windows), or`npm i -g @colbymchenry/codegraph@latest`\n\n.— WAL couldn't be enabled on this filesystem (common on network shares and WSL2`codegraph status`\n\nshows`Journal:`\n\nother than`wal`\n\n`/mnt`\n\n), so reads can block on writes. Move the project (with its`.codegraph/`\n\nfolder) onto a local disk.\n\n**MCP server not connecting** — Your agent starts the server itself, so you don't launch it by hand. Make sure the project is initialized and indexed (`codegraph status`\n\n) and that the path in your MCP config is correct. If it still won't connect, re-run `codegraph install`\n\nto rewrite the config.\n\n**MCP tool calls fail with Transport closed while codegraph status/sync are healthy** — almost always WSL2 with the project on a Windows drive (a\n\n`/mnt/c`\n\nor `/mnt/d`\n\npath), where the local socket CodeGraph uses to share one background server across sessions is unreliable. CodeGraph now falls back to serving the session in-process instead of dropping the connection, but if you still hit it, set `CODEGRAPH_NO_DAEMON=1`\n\nin your MCP server's environment to skip the shared server entirely (each session runs in its own process). Moving the project onto the Linux-native filesystem (e.g. under `~/`\n\ninstead of `/mnt/`\n\n) restores the shared server.**Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph sync`\n\nmanually if needed. Check that the file's language is supported and isn't inside a `.gitignore`\n\nd or default-excluded directory (e.g. `node_modules`\n\n, `dist`\n\n).\n\n**Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph/`\n\n: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR`\n\nto a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win`\n\non Windows, leaving WSL on the default `.codegraph`\n\n. CodeGraph skips any sibling `.codegraph-*`\n\ndirectory when indexing and watching, so the two never trip over each other.\n\nMIT\n\n**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro**", "url": "https://wpnews.pro/news/codegraph", "canonical_source": "https://github.com/colbymchenry/codegraph", "published_at": "2026-07-26 04:19:41+00:00", "updated_at": "2026-07-26 04:52:23.050205+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "artificial-intelligence"], "entities": ["CodeGraph", "Claude Code", "Cursor", "Codex", "OpenCode", "Hermes Agent", "Gemini", "Antigravity"], "alternates": {"html": "https://wpnews.pro/news/codegraph", "markdown": "https://wpnews.pro/news/codegraph.md", "text": "https://wpnews.pro/news/codegraph.txt", "jsonld": "https://wpnews.pro/news/codegraph.jsonld"}}