Purpose
CodeGraphContext (CGC) is used to turn code repositories into queryable graphs, providing context for AI agents. It targets scenarios where "plain text search is no longer enough," building repositories into graphs containing files, symbols, calls, inheritance, imports, and relationships, thereby answering "how things are connected" rather than merely "where they are defined."
Main Capabilities
- Code indexing: analyzes code and builds a component knowledge graph.
- Relationship analysis: queries callers, callees, class hierarchies, call chains, and more.
- Pre-indexed packages: instantly load well-known repositories via .cgc packages without indexing.
- Real-time file watching: use cgc watch to monitor directory changes and update the graph in real time.
- Interactive setup: provides a user-friendly command-line wizard.
- Dual mode: can serve as both a standalone CLI tool and an MCP server for AI agents.
- Multi-language support: full support for 23 programming languages.
- Flexible database backends: FalkorDB Lite (default), KuzuDB, LadybugDB, FalkorDB Remote, Nornic DB, or Neo4j.
- Interactive visualization: generates a web-based interactive knowledge graph with dark mode, glassmorphism, click-a-node-to-view-details, real-time search, force-directed and hierarchical layouts, output as a standalone HTML file.
- Token-optimized output (GCF): the optional GCF output format can reduce tool response tokens by about 62%, falling back to JSON if gcf-python is not installed.
Usage
Install: pip install codegraphcontext. If the command is not found, run a one-line fix script. The database uses an embedded graph database by default with no additional configuration required; for Neo4j, run codegraphcontext neo4j setup to use an external server.
CLI mode: index repositories, view indexed repositories, find unused code, and more.
MCP mode: run the codegraphcontext mcp setup wizard, which can automatically detect and configure VS Code, Cursor, Windsurf, Zed, Claude, Gemini CLI, ChatGPT, Codex, Cline, RooCode, Amazon Q Developer, Kiro, Goose, OpenCode, and more. The wizard generates mcp.json, stores database credentials in ~/.codegraphcontext/.env, and updates the settings files of the selected IDE/CLI. Then run codegraphcontext mcp start to start the server, and you can interact with the codebase in natural language.
Specific files and directories can be ignored via a .cgcignore file in the project root (syntax same as .gitignore).
Applicable Scenarios
- Trace call chains across files and packages.
- Understand class hierarchies, imports, and module boundaries.
- Find dead code, hotspots, and unexpected dependencies.
- Provide AI assistants with the same structural context as maintainers.
- Static code analysis in AI assistants, graph-based project visualization, dead code and complexity detection.
Limitations and Notes
- Requires Python 3.10 or higher and the pip package manager; Git is optional.
- Supports Python 3.10-3.14.
- Embedded KuzuDB/LadybugDB uses a 4 GiB buffer pool by default, adjustable via CGC_EMBEDDED_BUFFER_POOL_MB; set it to 0 to use the library default (about 80% of system memory).
- SCIP indexing is an optional feature: after setting SCIP_INDEXER=true in the configuration, some languages use external SCIP indexers to obtain more accurate calls and inheritance than Tree-sitter heuristics. C and C++ use scip-clang, which requires compile_commands.json; C# uses scip-dotnet, which requires a normal .csproj/.sln with a successful restore. SCIP is independent of the graph database used.
- Solidity uses Tree-sitter and does not support SCIP; Kotlin annotations are recorded as decorators on functions and classes, while annotations on interfaces, objects, constructors, parameters, and properties are not yet recorded.
- License: MIT.
- Author: Shashank Shekhar Singh.
- Specific fees, prices, platform restrictions, etc. are not yet provided.
