🏗️ CodeGraphContext (CGC)

Turn code repositories into a queryable graph for AI agents.

🌐 Languages: - 🇬🇧 English - 🇨🇳 中文 - 🇰🇷 한국어 - 🇺🇦 Українська - 🇷🇺 Русский - 🇯🇵 日本語 - 🇪🇸 Español (Soon)

🌍 Help translate CodeGraphContext to your language by raising an issue & PR on GitHub Issues!

Bridge the gap between deep code graphs and AI context.

A powerful MCP server and CLI toolkit that indexes local code into a graph database to provide context to AI assistants and developers. Use it as a standalone CLI for comprehensive code analysis or connect it to your favorite AI IDE via MCP for AI-powered code understanding.

📍 Quick Navigation

• 🚀 Quick Start
• 📋 Prerequisites
• 🏃 How to Run the Project Locally
• 🌐 Supported Programming Languages
• 🛠️ CLI Toolkit
• 🤖 MCP Server
• 🗄️ Database Options
• 🔬 SCIP indexing (optional)

✨ Experience CGC

👨🏻‍💻 Installation and CLI

Install in seconds with pip and unlock a powerful CLI for code graph analysis.

🛠️ Indexing in Seconds

The CLI intelligently parses your tree-sitter nodes to build the graph.

🤖 Powering your AI Assistant

Use natural language to query complex call-chains via MCP.

Why CodeGraphContext?

CodeGraphContext is built for the moment when plain text search stops being enough. It turns a repository into a graph of files, symbols, calls, inheritance, imports, and relationships so you can move from "where is this defined?" to "how does this actually connect?" without jumping between tools.

flowchart LR
  A[Source code] --> B[Tree-sitter and SCIP indexers]
  B --> C[Graph database]
  C --> D[CLI queries]
  C --> E[MCP server]
  D --> F[Direct analysis]
  E --> G[AI assistants with repo context]

Comparison at a glance

Common use cases

• Trace call chains across files and packages.
• Understand class hierarchies, imports, and module boundaries.
• Find dead code, hotspots, and unexpected dependencies.
• Give an AI assistant the same structural context a maintainer would use.

FAQ

• Do I need a remote service? No. CGC works locally with embedded backends or with external graph databases when you want them.
• Is it only for one language? No. It supports a broad mix of mainstream languages and keeps expanding.
• Can I use it with an AI assistant? Yes. That is one of the main reasons the MCP server exists.

Project Details

• Version: 0.5.1
• Authors: Shashank Shekhar Singh shashankshekharsingh1205@gmail.com
• License: MIT License (See LICENSE for details)
• Website: CodeGraphContext

👨‍💻 Maintainer

CodeGraphContext is created and actively maintained by:

Shashank Shekhar Singh
- 📧 Email: shashankshekharsingh1205@gmail.com - 🐙 GitHub: @Shashankss1205 - 🔗 LinkedIn: Shashank Shekhar Singh - 🌐 Website: codegraphcontext.vercel.app

Contributions and feedback are always welcome! Feel free to reach out for questions, suggestions, or collaboration opportunities.

Star History

Features

• Code Indexing: Analyzes code and builds a knowledge graph of its components.
• Relationship Analysis: Query for callers, callees, class hierarchies, call chains and more.
• Pre-indexed Bundles: Load famous repositories instantly with .cgc bundles - no indexing required! (Learn more)
• Live File Watching: Watch directories for changes and automatically update the graph in real-time (cgc watch).
• Interactive Setup: A user-friendly command-line wizard for easy setup.
• Dual Mode: Works as a standalone CLI toolkit for developers and as an MCP server for AI agents.
• Multi-Language Support: Full support for 23 programming languages.
• Flexible Database Backend: FalkorDB Lite (Default), KuzuDB, LadybugDB, FalkorDB Remote, Nornic DB, or Neo4j (all platforms via Docker/native).

🏗️ Architecture & Workflow

CodeGraphContext parses your source code and builds a comprehensive knowledge graph. This graph can be queried directly via the CLI toolkit or exposed to AI assistants through the MCP server.

flowchart TD
    A[Code Repository] -->|Parsed by| B[Tree-sitter / SCIP Indexing]
    B -->|Generates| C[Knowledge Graph]
    C -->|Stored in| D[(Graph Database)]
    D -->|Queried via| E[CLI Toolkit]
    D -->|Served by| F[MCP Server]
    F -->|Provides context to| G[🤖 AI Assistant]

    classDef default fill:#1f2937,stroke:#8b5cf6,stroke-width:2px,color:#fff;
    classDef db fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef ai fill:#312e81,stroke:#a855f7,stroke-width:2px,color:#fff;

    D:::db
    G:::ai

Supported Programming Languages

CodeGraphContext provides comprehensive parsing and analysis for the following languages:

Each language parser extracts functions, classes, methods, parameters, inheritance relationships, function calls, and imports to build a comprehensive code graph.

Database Options

CodeGraphContext supports multiple graph database backends to suit your environment:

SCIP indexing (optional)

When SCIP_INDEXER=true in your CGC config (~/.codegraphcontext/.env), some languages use external SCIP indexers for more accurate calls and inheritance than Tree-sitter heuristics alone.

C and C++ use scip-clang, which requires a compile_commands.json file (a JSON compilation database): one entry per translation unit with the real compiler command (include paths, -D defines, -std, etc.). Without it, scip-clang cannot run; CGC logs a warning and falls back to Tree-sitter for that repo. Typical ways to produce the file: CMake with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON, or wrap your real build with Bear (e.g. bear -- make). CGC also looks under build/ and cmake-build-*/ for that filename.

C# uses scip-dotnet (Roslyn); you need a normal .csproj / .sln and a successful restore—no compile_commands.json.

SCIP is independent of which graph database you use (Kuzu, Neo4j, etc.); the same flag applies to all backends.

Used By

CodeGraphContext is already being explored by developers and projects for:

• Static code analysis in AI assistants
• Graph-based visualization of projects
• Dead code and complexity detection

If you’re using CodeGraphContext in your project, feel free to open a PR and add it here! 🚀

Dependencies

• neo4j>=5.15.0
• watchdog>=3.0.0
• stdlibs>=2023.11.18
• typer>=0.9.0
• rich>=13.7.0
• inquirerpy>=0.3.4
• python-dotenv>=1.0.0
• tree-sitter>=0.24.0,<0.26.0
• tree-sitter-language-pack>=1.6,<2.0
• pyyaml
• pathspec>=0.12.1
• falkordb>=1.0,<1.6
• falkordblite>=0.7,<0.10 (Unix only, Python 3.12+)
• kuzu (KuzuDB engine)
• fastapi>=0.100.0
• uvicorn>=0.22.0
• requests>=2.28.0
• protobuf>=3.20,<3.21

Note: Python 3.10-3.14 is supported.

🚀 Installation & Quick Start

1. Install the toolkit: bash pip install codegraphcontext

2. Troubleshooting (Command not found): If the codegraphcontext command is not found, run this one-line fix: bash curl -sSL https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh | bash

3. Database Setup (Automatic): CodeGraphContext uses an embedded graph database by default.

   • FalkorDB Lite: Default backend.
   • KuzuDB: Cross-platform embedded backend.
   • Neo4j: Run codegraphcontext neo4j setup to use an external server.

🧪 Local Development Setup

If you want to run CodeGraphContext from a local clone and contribute changes, use an editable install:

git clone https://github.com/CodeGraphContext/CodeGraphContext.git
cd CodeGraphContext
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Then verify the install and try the local commands:

```bash cgc --help cgc doctor cgc index . cgc analyze callers