unknownswordsman/codegraph

1. What this repo is

- CodeGraph is a TypeScript/Node-based CLI plus embeddable library that builds a local code knowledge graph for a project.

- The core product boundary is the per-project .codegraph/ directory, which holds the SQLite index and metadata; everything else orchestrates how that index is built, queried, kept fresh, and exposed to AI agents.

2. Top-level runtime split

- There are two execution modes:

- Bundled CLI/runtime for end users (src/bin, install scripts, bundle scripts).

- Library/API mode for embedding in another Node 22.5+ process (src/index.ts and exports from the package entrypoint).

- The CLI is what agents and users interact with; the library is the same engine used programmatically.

3. Indexing pipeline

- The indexing flow lives mainly under src/extraction, src/resolution, src/graph, and src/db.

- Source files are parsed with tree-sitter, language-specific extractors identify symbols/edges, then a resolution pass connects references across files, imports, call sites, inheritance, and framework conventions.

- The result is stored in SQLite with FTS5 for search.

4. Storage boundary

- src/db defines schema, migrations, and query helpers for the on-disk graph database.

- The repository uses SQLite as the single source of truth; the architecture is intentionally local-first and does not depend on a remote indexing service.

- Tests around reopen/locking/performance indicate the DB layer is tuned for concurrent read-heavy access and resilience to file replacement.

5. Graph and query subsystem

- src/graph and src/search provide read/query primitives over the indexed data: symbol lookup, callers/callees, impact radius, and search parsing.

- src/context builds “agent-ready” context bundles from the graph: ranked symbols, formatted snippets, and boundary markers used to answer questions directly.

- This is the main data-serving layer once indexing is complete.

6. Resolution and cross-language synthesis

- src/resolution is where CodeGraph becomes more than syntax extraction.

- It contains framework resolvers, import resolution, path aliases, workspace package handling, and synthetic edge generators for hard-to-follow flows such as callbacks, dispatch systems, Swift/ObjC bridging, React Native bridges, Expo modules, and framework-specific route conventions.

- These heuristics are a major architectural boundary because they close gaps that raw AST parsing cannot.

7. Language frontends

- src/extraction/languages contains per-language extractors for TypeScript/JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Swift, Kotlin, Scala, Dart, Lua/Luau, R, Liquid, Pascal/Delphi, and several frontend frameworks.

- Some extra file-format extractors exist alongside the language layer, such as Astro, Svelte, Vue, Liquid, Razor, MyBatis, and DFM-like forms.

- The extractors are modular, which makes language support an additive subsystem rather than a monolith.

8. MCP server architecture

- src/mcp implements the server that AI agents actually talk to.

- It exposes the CodeGraph query surface through MCP, manages session lifecycle, transport, query workers, daemon/shared-process behavior, and watchdogs for liveness and parent-process death.

- This layer is the boundary between agent tool calls and the local graph database.

9. Freshness and syncing

- src/sync handles watch-based incremental updates using native file-system events, debounce policy, git-hook support, and worktree awareness.

- The architecture favors “always fresh” indexes: change detection feeds incremental resyncs, and stale-file safeguards are surfaced to the agent when the graph may lag behind the working tree.

- This is important because the agent-facing answers depend on the current project state, not a stale snapshot.

10. Installer and agent integration

- src/installer and scripts/add-lang / install.sh / install.ps1 are the operational layer that wires CodeGraph into external agents and user machines.

- The installer detects supported agents, writes their MCP configuration, and optionally injects instructions into agent-specific guidance files.

- This is the integration boundary to Claude Code, Cursor, Codex, opencode, Gemini, Antigravity, Kiro, and Hermes.

11. Telemetry and external service boundary

- src/telemetry collects anonymous usage data, while telemetry-worker/ hosts the ingestion endpoint as a separate deployable service.

- The architecture keeps code-content and file/path data local; telemetry is limited to aggregated usage metadata.

- In contrast to the core product, telemetry is the only clearly separate cloud-facing subsystem in the repo.

12. Distribution, website, and validation

- site/ is an Astro documentation/marketing site published via GitHub Pages workflows.

- scripts/ contains release, packaging, benchmark, and evaluation tooling; this repo treats release engineering and agent-eval experiments as first-class operational concerns.

- __tests__ is extensive and maps directly onto the major boundaries above, especially extraction, resolution, daemon/watch behavior, MCP behavior, installer behavior, and SQLite persistence.

13. End-to-end data flow

- A user initializes a project → the CLI scans source files → extractors build symbols and raw edges → resolvers add cross-file/framework/bridge links → SQLite stores the graph → MCP queries read from that graph → watch/sync keeps it current as files change.

- The same graph also powers CLI commands like search, callers/callees, impact analysis, and affected-test detection.

14. Primary architectural shape

- This repo is best understood as a local indexing engine with three outer shells:

- Build shell: extraction + resolution + storage.

- Serve shell: CLI + MCP + query/context APIs.

- Operate shell: installer, watcher/sync, telemetry, packaging, and docs.

- The center of gravity is the project-local SQLite graph; everything else exists to populate it, keep it fresh, or expose it to agents.