CodeGraphContext

Parses source code from 14 programming languages (Python, JavaScript, TypeScript, Java, C++, Go, Rust, Ruby, PHP, C#, Swift, Kotlin, Scala, Lua) using Tree-sitter's incremental parsing engine to build abstract syntax trees. Extracts semantic entities (functions, classes, variables, imports) and their relationships with structural awareness, enabling precise code graph construction rather than regex-based pattern matching. The parser layer feeds directly into the GraphBuilder service, which normalizes language-specific syntax into a unified graph schema.

Builds a queryable property graph of code entities and relationships, storing nodes (functions, classes, modules) and edges (calls, inherits, imports, references) in a graph database. Supports four database backends via a DatabaseManager singleton pattern: KùzuDB (default, zero-config, in-process), FalkorDB Lite (Unix only), FalkorDB Remote (networked), and Neo4j (all platforms). The GraphBuilder service constructs the graph incrementally, and the database abstraction layer enables backend switching without changing query logic, allowing teams to scale from local development (KùzuDB) to production deployments (Neo4j).

Manages long-running operations (code indexing, bundle downloads, graph updates) as background jobs tracked by a JobManager service. Each job has a unique ID, status (pending, in-progress, completed, failed), and progress metadata. Jobs are stored in-memory and exposed through both CLI and MCP interfaces, allowing clients to poll job status without blocking. The job system prevents MCP client timeouts by returning immediately with a job ID, then allowing clients to check progress asynchronously. Enables responsive UX for operations that take seconds or minutes.

Provides configuration management that supports multiple deployment environments (local development, Docker, production) with environment-specific database backends, logging levels, and bundle registry URLs. Configuration is loaded from environment variables, config files, and command-line arguments with a clear precedence order. Enables teams to use KùzuDB locally, FalkorDB in staging, and Neo4j in production without code changes. The configuration layer also handles database connection pooling, retry logic, and fallback strategies (e.g., falling back from FalkorDB to KùzuDB if connection fails).

Implements incremental indexing that detects changed files and updates only affected graph nodes and edges rather than re-indexing the entire codebase. The GraphBuilder service tracks file modification times and checksums to identify changes, re-parses only modified files, and updates the graph with new/modified/deleted entities. Enables fast re-indexing of large codebases where only a few files change between updates. Integrates with the CodeWatcher to automatically trigger incremental updates when files change, keeping the graph synchronized with the codebase.

Provides Docker images and docker-compose configurations for deploying CodeGraphContext with Neo4j or other production databases. The Docker setup includes the MCP server, CLI tools, and optional visualization server, with environment-based configuration for different deployment scenarios. Enables teams to deploy code intelligence as a containerized service with persistent database storage, making it suitable for production environments and CI/CD integration.

Monitors local file system changes using a CodeWatcher service and automatically updates the indexed graph database when source files are modified, created, or deleted. Implements debouncing to batch rapid file changes and avoid thrashing the database with individual updates. The watcher integrates with the JobManager to track synchronization status and expose progress through both CLI and MCP interfaces, enabling AI assistants to work with current code context without manual re-indexing.

Exposes the code graph as a Model Context Protocol (MCP) server using JSON-RPC 2.0 over stdio, enabling AI assistants (Claude, Cursor, VS Code) to query code relationships, search entities, and analyze dependencies without direct database access. The MCP server wraps core services (GraphBuilder, CodeFinder, CodeWatcher) and translates MCP tool calls into service method invocations, returning structured results. Implements background job tracking so long-running operations (indexing, bundle downloads) can be polled asynchronously, preventing MCP client timeouts.

Provides command-line interface for developers to index codebases, query relationships, analyze dependencies, and visualize graphs locally without AI assistance. The CLI invokes the same core services as the MCP server (GraphBuilder, CodeFinder, CodeWatcher), ensuring feature parity. Includes commands for indexing, searching entities, finding relationships, watching files, and serving a web-based graph visualization. The CLI toolkit enables developers to explore code structure interactively and understand their codebase before sharing context with AI assistants.

Distributes pre-indexed code graphs as .cgc bundle files for popular open-source libraries (React, Django, FastAPI, etc.), enabling instant loading without parsing and indexing. Bundles are generated offline and published to a registry, reducing initial setup time from minutes to seconds. The bundle system uses a BundleManager service that downloads bundles on-demand, validates checksums, and merges them into the local graph database. Bundles achieve 30-60x speedup by eliminating parsing and graph construction overhead, making it practical to include large dependencies in AI context.

Provides a CodeFinder service that searches the indexed graph for code entities (functions, classes, variables, modules) by name, type, or pattern. Supports substring matching, regex patterns, and type-based filtering (e.g., 'find all functions that return a specific type'). Search results include entity metadata (file location, line number, signature) and can be filtered by language, file path, or scope. The search layer integrates with both CLI and MCP interfaces, enabling developers and AI assistants to locate relevant code quickly without manual file browsing.

Analyzes code relationships stored in the graph to identify dependencies, call chains, inheritance hierarchies, and circular references. Provides traversal algorithms that follow edges (calls, imports, inherits) to compute transitive relationships and impact analysis. For example, finding all functions that transitively call a specific function, or identifying all classes that depend on a specific module. The relationship analysis layer supports both breadth-first and depth-first traversal, with configurable depth limits to prevent infinite loops in circular dependencies.

Serves an embedded web application that visualizes the code graph as an interactive node-link diagram, allowing developers to explore relationships visually. The visualization server (viz/server.py) renders nodes as code entities and edges as relationships, with interactive features like zooming, panning, filtering by entity type, and clicking to view entity details. The visualization is generated from the indexed graph database and updates in real-time as the graph changes. Developers can use the visualization to understand system architecture, identify bottlenecks, and communicate code structure to team members.

Normalizes heterogeneous code entities from 14 different languages into a unified graph schema with consistent entity types (Function, Class, Variable, Module, Import) and relationship types (Calls, Inherits, Imports, References). The normalization layer maps language-specific syntax to canonical entity representations, enabling queries and analysis to work across languages without language-specific logic. For example, a Python function definition, JavaScript function declaration, and Java method are all normalized to the same Function entity type with consistent properties (name, signature, file, line).