Architecture

CGraph is a small set of programs around one shared engine. The engine extracts and resolves the graph; the programs are different front doors onto it.

The shape of the system

                          +-------------------+
   Repository  ------->   |     engine        |   ----->  exports (json/html/svg/...)
                          |  detect · extract |
                          |  resolve · analyze|
                          +---------+---------+
                                    |
                 +------------------+------------------+
                 |                  |                  |
              cgraph             graphd            cgraph-mcp
             (one-shot)     (warm daemon)     (MCP over stdio)
                                    |
                              cgraph-client
                              (thin client)

The four programs

• cgraph — the one-shot CLI. Scans a tree, builds the graph, writes exports, exits. Good for CI and one-off analysis.
• graphd — the daemon. Keeps the graph warm, watches the tree, and folds in edits incrementally. Good for an interactive session.
• cgraph-client — a thin client that sends operations to a running daemon.
• cgraph-mcp — an MCP server that exposes the graph to coding agents; its tool calls route through the same daemon operation handler as the thin client.

The engine

src/engine owns the deterministic core: detection, extraction, graph building, analysis, and daemon operations. Because extraction is deterministic, the same tree always produces the same graph — which is what lets the daemon diff and fold in changes rather than rebuilding.

Repository layout

src/cli/       one-shot CLI: cgraph
src/daemon/    daemon: graphd
src/client/    thin client: cgraph-client
src/mcp/       MCP server: cgraph-mcp
src/engine/    detection, extraction, graph building, analysis, daemon ops
vendor/        vendored tree-sitter core and grammars

Reading order

The rest of this section follows a request through the system: how the graph is built (Indexing Pipeline), how it stays warm (Daemon Architecture and Incremental Updates), and how a query is answered (Retrieval and Context Packing).