How colbymchenry/codegraph works
Purpose and entry points
CodeGraph is a local semantic-code-intelligence system for AI agents and CLI users. It indexes a project into a SQLite knowledge graph, resolves cross-file and framework relationships, and serves focused source/context, call paths, and impact analysis. Main CLI dispatch is src/bin/codegraph.ts; embeddable API exports originate at src/index.ts. Agent integration runs through the MCP server in src/mcp/index.ts.
1. CLI lifecycle and project boundary
The CLI owns project commands (init, index, sync, query/explore, daemon, install, upgrade) and supervises fatal errors and runtime checks. A project’s durable boundary is its local .codegraph/ directory/database, with configuration loaded from project-root conventions. Installation is a separate concern: it writes MCP configuration/instructions for supported agent hosts.
Paths: src/bin/codegraph.ts, src/project-config.ts, src/installer/index.ts.
2. Extraction pipeline
Indexing discovers eligible source files, selects language extractors, parses them through Tree-sitter or the native kernel, and emits structural nodes and raw relationships. Extraction supports worker-based parsing/storage so full indexing can parallelize while writes are coordinated. Composite/template languages have dedicated extractors alongside per-language implementations.
Paths: src/extraction/index.ts, src/extraction/parse-pool.ts, src/extraction/store-writer.ts.
3. Rust kernel / portable parser boundary
The Rust crate is the high-performance extraction backend for a large subset of languages. TypeScript loads its compiled artifact, decodes kernel output, and falls back to portable WASM Tree-sitter parsing when unavailable or unsuitable per file. This boundary preserves a common graph shape regardless of parsing engine.
Paths: codegraph-kernel/src/lib.rs, src/extraction/kernel/loader.ts, src/extraction/kernel/decode.ts.
4. Persistent graph and search
SQLite is the system of record for files, symbols, edges, and FTS-backed retrieval. The DB layer encapsulates schema/migrations and query operations; WAL handling is explicitly managed to keep reads available during sync. Higher-level graph traversal and query modules operate on this persisted representation rather than source files directly.
Paths: src/db/schema.sql, src/db/index.ts, src/graph/traversal.ts.
5. Resolution and synthesized relationships
After extraction, resolution maps imports, references, calls, aliases, and workspace/module relationships to graph entities. Worker pools and caches control CPU/memory use. Framework resolvers and specialized synthesizers add relationships static syntax alone cannot express—routes, callbacks, dispatch, Swift/ObjC bridging, React Native, and similar conventions—marking heuristic edges distinctly.
Paths: src/resolution/index.ts, src/resolution/resolver-pool.ts, src/resolution/frameworks/index.ts.
6. Query/context serving
Graph queries power symbol search, caller/callee traversal, impact analysis, and ranked context construction. The context layer formats selected source and relationships into agent-facing output. MCP exposes this primarily as an explore workflow, with request/session orchestration isolated from graph execution.
Paths: src/graph/queries.ts, src/context/index.ts, src/mcp/engine.ts.
7. MCP daemon and continuous synchronization
MCP runs over stdio but can attach sessions to a per-project background daemon. Startup performs handshake/catch-up; query workers isolate concurrent requests. Native file watching applies debounced incremental sync and tracks pending edits so responses can signal staleness rather than silently serving outdated graph data.
Paths: src/mcp/daemon.ts, src/mcp/session.ts, src/sync/watcher.ts.
Runtime, infrastructure, and external boundaries
Core runtime is TypeScript/Node; the library API requires modern Node SQLite support, while distributed CLI builds bundle Node. Rust provides the native kernel; Tree-sitter WASM assets provide portable parsing. Storage and indexing are local SQLite only. Optional anonymous telemetry is aggregated locally then sent to a Cloudflare Worker endpoint; the product graph itself does not require external services.
Paths: package.json, codegraph-kernel/Cargo.toml, telemetry-worker/src/index.ts.
Main entry points: db/index.ts SQLite knowledge graph · extraction/index.ts Extraction coordinator · codegraph.ts CLI dispatcher · loader.ts Kernel loader
Components 24
Entry points
- CLI dispatcher · Owns project commands and runtime supervision.
src/bin/codegraph.ts - Project configuration · Loads root conventions and the local durable project state.
src/project-config.ts - Agent host installer · Writes MCP configuration and instructions for supported hosts.
src/installer/index.ts - Embeddable API
src/index.ts
Indexing pipeline
- Extraction coordinator · Discovers files, selects extractors, and emits structural graph data.
src/extraction/index.ts - Parse worker pool · Parallelizes eligible file parsing.
src/extraction/parse-pool.ts - Coordinated graph writer · Coordinates indexing writes from worker-based extraction.
src/extraction/store-writer.ts - Kernel loader · Chooses native kernel output or portable parsing per file.
src/extraction/kernel/loader.ts - Kernel output decoder · Converts native output into the common graph shape.
src/extraction/kernel/decode.ts - Relationship resolution · Maps raw syntax relationships to graph entities.
src/resolution/index.ts - Resolver worker pool · Controls CPU and memory during resolution.
src/resolution/resolver-pool.ts - Framework synthesizers · Adds convention-based edges such as routes and callbacks.
src/resolution/frameworks/index.ts
Persistent graph
- SQLite knowledge graph · Stores files, symbols, edges, and FTS retrieval data.
src/db/index.ts - SQLite schema and migrations · Defines persisted graph and search structures.
src/db/schema.sql - Graph traversal · Traverses the persisted graph rather than source files.
src/graph/traversal.ts
Query and MCP
- Graph queries · Provides search, call paths, and impact analysis.
src/graph/queries.ts - Context builder · Ranks and formats source and relationships into focused context.
src/context/index.ts - MCP explore engine · Isolates request orchestration from graph execution.
src/mcp/engine.ts - MCP daemon · Attaches project sessions and performs startup catch-up.
src/mcp/daemon.ts - MCP session · Coordinates stdio sessions and daemon attachment.
src/mcp/session.ts - Incremental sync watcher · Debounces edits and records staleness during incremental sync.
src/sync/watcher.ts
Runtime boundaries
- Rust extraction kernel · High-performance backend for a large language subset.
codegraph-kernel/src/lib.rs - Tree-sitter WASM · Fallback parser when the native kernel is unavailable or unsuitable.
- Telemetry worker · Receives aggregated anonymous telemetry only.
telemetry-worker/src/index.ts
Connections 28
- CLI dispatcher → Project configuration: loads
- CLI dispatcher → Extraction coordinator: runs index/sync
- CLI dispatcher → Agent host installer: runs install
- Embeddable API → Extraction coordinator: embeds
- Extraction coordinator → Parse worker pool: dispatches files
- Parse worker pool → Kernel loader: parses through
- Kernel loader → Rust extraction kernel: uses when supported
- Kernel loader → Tree-sitter WASM: falls back to
- Rust extraction kernel → Kernel output decoder: emits native output
- Kernel output decoder → Coordinated graph writer: normalizes graph data
- Tree-sitter WASM → Coordinated graph writer: emits common graph data
- Coordinated graph writer → SQLite knowledge graph: writes nodes and raw edges
- SQLite knowledge graph → SQLite schema and migrations: uses
- Extraction coordinator → Relationship resolution: runs after extraction
- Relationship resolution → Resolver worker pool: parallelizes
- Resolver worker pool → Framework synthesizers: applies conventions
- Relationship resolution → SQLite knowledge graph: resolves persisted entities
- Framework synthesizers → SQLite knowledge graph: writes heuristic edges
- SQLite knowledge graph → Graph traversal: provides graph
- Graph traversal → Graph queries: supports
- Graph queries → Context builder: selects ranked results
- MCP explore engine → Graph queries: executes explore
- MCP explore engine → Context builder: returns context
- MCP session → MCP daemon: attaches to
- MCP session → MCP explore engine: routes requests
- MCP daemon → Incremental sync watcher: runs continuous sync
- Incremental sync watcher → Extraction coordinator: triggers incremental index
- Telemetry worker → SQLite knowledge graph: does not access product graph