CGraph

English · 简体中文

*Scan a project · extract structure into a deterministic graph · query it in ~10 ms from a daemon, a thin client, or an MCP server.*

Contents

Why CGraph? · Architecture · Repository layout · What it produces · Output formats · Performance · Retrieval benchmark · Languages · Quick start · Install & Setup · Use with coding agents · CLI · daemon · MCP reference · Host integrations & enrichment · Development notes · Contributing · License

Why CGraph?

Reading a large repo to answer "what calls this?" or "what breaks if I change it?" means loading dozens of files — and those answers aren't in any single file. They live in the *relationships between* files. CGraph precomputes them so you (and your AI agent) navigate by graph, not grep.

The pitch in one line: for a codebase too big to hold in your head, CGraph is the index that decides *which* code to read — ctags/"find all references", precomputed, centrality-ranked, and exposed over MCP.

Architecture

• `cgraph` — one-shot scan → portable disk exports (graph.json, graph.html, graph.svg, obsidian.md, cypher.txt, modules.mmd, modules.svg, design.mmd, design.md).
• `graphd` + `cgraph-client` — a resident per-project daemon with live file-watching; warm query / path / explain / impact / context in ~10 ms.
• `cgraph-mcp` — a Model Context Protocol server so agents navigate the graph directly.

The engine owns deterministic extraction, fragment validation, cache state, and local graph mutation; hosts own model choice and semantic enrichment.

Repository layout

src/cli/          One-shot CLI entrypoint: cgraph

src/daemon/ Daemon entrypoint: graphd src/client/ Thin client runtime and cgraph-client executable src/mcp/ MCP request handling and cgraph-mcp executable src/engine/ Detection, extraction, graph building, analysis, daemon ops tests/smoke/ CTest smoke coverage for engine, daemon, MCP, and integration paths tests/fuzz/ Optional libFuzzer targets integrations/ Host hook and always-on integration scripts docs/ Host integration contract and benchmark notes vendor/ Vendored tree-sitter core and grammars

What it produces

A single scan turns a source tree into an interactive, explorable graph — communities colored, hubs sized by centrality:

The real graph.html viewer on a 10,708-node / 28,945-edge codebase — self-contained HTML, no external JS.

Output formats

• graph.json — directed node-link JSON with graph metadata, nodes, and links. Node ids derive from each file's path relative to the project root, so the same commit built from two checkouts yields the same ids and two graphs can be joined by id; source_file stays the path the graph was read from
• graph.html — browser-readable interactive graph view
• graph.svg — static graph visualization
• obsidian.md — markdown export for Obsidian-style navigation
• cypher.txt — Neo4j Cypher statements
• modules.mmd — module dependency diagram as Mermaid
• modules.svg — module dependency diagram as a layered static image
• design.mmd — entry points and their top call flows as a Mermaid flowchart TD
• design.md — the same as Markdown: entry-point table, nested flows, layers by call distance

Performance

The interactive viewer used to run an O(N²) force simulation in the browser on every open. Layout is now precomputed once in C++ (via igraph), and repaints are viewport-culled — both dependency-free:

Retrieval benchmark

CGraph has been scored on Agent Retrieval Bench: 427 samples from 25 repositories, each checked out at its base commit, scored with the benchmark's own metric code. The table covers all 345 positive samples.

How bin-v0.9.1 compares:

• Recall@20. Level with RepoMap (the difference is inside run-to-run noise of about 0.006). Below Qwen3-Embedding-8B. Above the other published single methods.
• MRR. Higher than every published single method.
• BCY@8k. Higher than every published single method, by more than the noise floor.
• Against the paper's fusion of Qwen3-Embedding-8B and RepoMap, on the 287-sample core it reports: MRR is level (the fusion scores only its top 20; CGraph's MRR over its top 20 is 0.276 vs 0.271, inside the noise floor); Recall@20 (0.633 vs 0.733) and BCY@8k (0.440 vs 0.488) are lower.
• Abstention. CGraph does not abstain on no-gold samples.

Per-task tables, pins, the noise floor and caveats are in bench/arb/RESULTS.md. Reproduce with bench/arb/run.sh.

Languages

Tree-sitter-backed structural extraction, with regex/structured extraction for a few config formats:

Plus structured/regex extraction for Apex, Delphi form/source, MSBuild/XML project files, and MCP config files.

Type members

Seven languages emit a field node per declared member, with a defines edge from the owner:

Members are declared members only: no inherited-member expansion, no alias flattening, no runtime attribute inference. A declaration that is already a node of its own — a TypeScript method_signature, a Rust trait method or type alias — keeps its function or type node and is not also a field. A field never takes the id a function or type holds; it moves instead, so a symbol's id stays stable.

A class-like declaration without a body (struct FileCacheEntry;) is a forward declaration and mints no node; only the body-bearing definition does.

Fields are members, not navigation targets: graph_context packs the owner (whose snippet spans its members) rather than the members, and report modules symbol counts exclude them.

HTTP endpoints

JavaScript and TypeScript services get one endpoint node per route the code serves, with the full path composed across files: an Elysia, Express or Hono chain's own prefix (new Elysia({ prefix: '/notebooks' }), .basePath('/v1')) beneath every .use(child), .use('/p', child) or .route('/p', child) that mounts it, up to the top-level chain, read through as any and as unknown as T casts and resolved through imports (aliased ones included). A chain built inline inside .use(new Elysia({ prefix }).get(…)), a .group('/v2', app => app.get(…)) or .guard() callback, and a module re-exported as export const deckModule = deckRoutes as unknown as Elysia all compose the same way. A Next.js app/api/x/[id]/route.ts exporting GET is GET /api/x/:id. A repository holding a langgraph.json with a non-empty graphs object is a LangGraph Agent Server: its 49 framework routes (POST /runs/wait, POST /threads/{thread_id}/runs/stream, GET /assistants/{assistant_id}, ..., the table @langchain/langgraph-api 1.5.1 registers, less its fo