CodeGraphContext

🏗️ CodeGraphContext (CGC)

Turn code repositories into a queryable graph for AI agents.

🌐 Languages:

• 🇬🇧 [English](README.md)
• 🇨🇳 [中文](docs/translations/README.zh-CN.md)
• 🇰🇷 [한국어](docs/translations/README.kor.md)
• 🇺🇦 [Українська](docs/translations/README.uk.md)
• 🇷🇺 [Русский](docs/translations/README.ru-RU.md)
• 🇯🇵 [日本語](docs/translations/README.ja.md)
• 🇪🇸 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](#-installation--quick-start)
• [📋 Prerequisites](#-prerequisites)
• [🏃 How to Run the Project Locally](#-how-to-run-the-project-locally)
• [🌐 Supported Programming Languages](#supported-programming-languages)
• [🛠️ CLI Toolkit](#for-cli-toolkit-mode)
• [🤖 MCP Server](#-for-mcp-server-mode)
• [🗄️ Database Options](#database-options)
• [🔬 SCIP indexing (optional)](#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.

---

Project Details

• Version: 0.5.1
• Authors: Shashank Shekhar Singh
• License: MIT License (See [LICENSE](LICENSE) for details)
• Website: CodeGraphContext

---

👨‍💻 Maintainer

CodeGraphContext is created and actively maintained by:

Shashank Shekhar Singh

• 📧 Email: [shashankshekharsingh1205@gmail.com](mailto: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

[](https://www.star-history.com/#CodeGraphContext/CodeGraphContext&Date)

---

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](docs/docs/guides/bundles.md))
• 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).

---

Supported Programming Languages

CodeGraphContext provides comprehensive parsing and analysis for the following languages:

| | Language | | Language | | Language | | :--- | :--- | :--- | :--- | :--- | :--- | | 🐍 | Python | 📜 | JavaScript | 🔷 | TypeScript | | ☕ | Java | 🔵 | C | ➕ | C++ | | #️⃣ | C# | 🐹 | Go | 🦀 | Rust | | 💎 | Ruby | 🐘 | PHP | 🍎 | Swift | | 🎨 | Kotlin | 🎯 | Dart | 🐪 | Perl | | 🌙 | Lua | 🚀 | Scala | λ | Haskell | | 💧 | Elixir | 📜 | Emacs Lisp (elisp) | 🌐 | HTML | | 🎨 | CSS | ⚛️ | TSX | | |

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:

| Feature | KuzuDB | LadybugDB | FalkorDB Lite | Neo4j / Nornic DB | | :--- | :--- | :--- | :--- | :--- | | Typical default | Cross-platform fallback when FalkorDB Lite is unavailable | Optional embedded backend | Default on Unix (Python 3.12+, when falkordblite is installed) | When explicitly configured via cgc config db | | Setup | Zero-config / Embedded | Zero-config / Embedded | Zero-config / In-process | Docker / External | | Platform | All (Windows Native, macOS, Linux) | All (Windows Native, macOS, Linux) | Unix-only (Linux/macOS/WSL) | All Platforms | | Use Case | Desktop, IDE, Local development | Custom research projects | Specialized Unix development | Enterprise, Massive graphs | | Requirement| pip install kuzu | pip install ladybug | pip install falkordblite | Neo4j Server / Docker / Nornic Cloud | | Speed | ⚡ Extremely Fast | ⚡ Fast | 🚀 Scalable | | Persistence| Yes (to disk) | Yes (to disk) | Yes (to disk) |

---

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.21.0 (not installed on Python 3.13)
• tree-sitter-language-pack>=0.6.0 (not installed on Python 3.13)
• pyyaml
• pathspec>=0.12.1
• falkordb>=1.0,=0.7,=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 ``

1. 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 ``

1. 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.

---

📋 Prerequisites

Before installing CodeGraphContext, ensure you have:

• Python 3.10 or later
• pip package manager
• Git (optional, for cloning repositories)

Verify your Python installation:

python --version

---

🚀 Step-by-Step Setup Guide

Step 1: Install CodeGraphContext

pip install codegraphcontext

This command installs CodeGraphContext and all required dependencies.

Step 2: Verify Installation

codegraphcontext --help

If the command displays the available CLI commands, the installation was successful.

Step 3: Database Setup

CodeGraphContext automatically uses an embedded database by default, so no additional configuration is required for most users.

---

🏃 How to Run the Project Locally

Index a Repository

codegraphcontext index .

This scans the current project and creates a searchable code graph.

View Indexed Repositories

codegraphcontext list

Displays all repositories currently indexed by CodeGraphContext.

Analyze Code

codegraphcontext analyze dead-code

Finds potentially unused code in the indexed repository.

---

✅ Verify Everything Works

After indexing a repository, run:

codegraphcontext list

If the command executes successfully and displays indexed repositories, your setup is complete and CodeGraphContext is ready to use.

For CLI Toolkit Mode

Start using immediately with CLI commands:

# Index your current directory
codegraphcontext index .

# List all indexed repositories
codegraphcontext list

# Analyze who calls a function
codegraphcontext analyze callers my_function

# Find complex code
codegraphcontext analyze complexity --threshold 10

# Find dead code
codegraphcontext analyze dead-code

# Watch for live changes (optional)
codegraphcontext watch .

# See all commands
codegraphcontext help

See the full [CLI Commands Guide](docs/CLICOMPLETEREFERENCE.md) for all available commands and usage scenarios.

🎨 Premium Interactive Visualization

CodeGraphContext can generate stunning, interactive knowledge graphs of your code. Unlike static diagrams, these are premium web-based explorers:

• Premium Aesthetics: Dark mode, glassmorphism, and modern typography (Outfit/JetBrains Mono).
• Interactive Inspection: Click any node to open a detailed side panel with symbol information, file paths, and context.
• Quick Search: Live-search through the graph to find specific symbols instantly.
• Intelligent Layouts: Force-directed and hierarchical layouts that make complex relationships readable.
• Zero-Dependency Viewing: Standalone HTML files that work in any modern browser.

# Visualize function calls
codegraphcontext analyze calls my_function --viz

# Explore class hierarchies
codegraphcontext analyze tree MyClass --viz

# Visualize search results
codegraphcontext find pattern "Auth" --viz

---

🤖 For MCP Server Mode

Configure your AI assistant to use CodeGraphContext:

1. Setup: Run the MCP setup wizard to configure your IDE/AI assistant:

``bash codegraphcontext mcp setup ``

The wizard can automatically detect and configure:

• VS Code
• Cursor
• Windsurf
• Zed
• Claude
• Gemini CLI
• ChatGPT Codex
• Cline
• RooCode
• Amazon Q Developer
• Kiro
• Goose
• OpenCode

Upon successful configuration, codegraphcontext mcp setup will generate and place the necessary configuration files:

• It creates an mcp.json file in your current directory for reference.
• It stores your database credentials securely in ~/.codegraphcontext/.env.
• It updates the settings file of your chosen IDE/CLI (e.g., .claude.json or VS Code's settings.json).

1. Start: Launch the MCP server:

``bash codegraphcontext mcp start ``

1. Use: Now interact with your codebase through your AI assistant using natural language! See examples below.

---

Ignoring Files (.cgcignore)

You can tell CodeGraphContext to ignore specific files and directories by creating a .cgcignore file in the root of your project. This file uses the same syntax as .gitignore.

Example .cgcignore file:

# Ignore build artifacts
/build/
/dist/

# Ignore dependencies
/node_modules/
/vendor/

# Ignore logs
*.log

---

MCP Client Configuration

The codegraphcontext mcp setup command attempts to automatically configure your IDE/CLI. If you choose not to use the automatic setup, or if your tool is not supported, you can configure it manually.

Add the following server configuration to your client's settings file (e.g., VS Code's settings.json or .claude.json):

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "codegraphcontext",
      "args": [
        "mcp",
        "start"
      ],
      "env": {
        "NEO4J_URI": "YOUR_NEO4J_URI",
        "NEO4J_USERNAME": "YOUR_NEO4J_USERNAME",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

OpenCode Configuration

For instructions on installing and configuring MCP servers with OpenCode, see the OpenCode MCP Guide.

If installed via pipx

If you installed CodeGraphContext using pipx, use the following configuration instead:

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "pipx",
      "args": [
        "run",
        "codegraphcontext",
        "mcp",
        "start"
      ],
      "env": {
        "NEO4J_URI": "YOUR_NEO4J_URI",
        "NEO4J_USERNAME": "YOUR_NEO4J_USERNAME",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

---

Natural Language Interaction Examples

Once the server is running, you can interact with it through your AI assistant using plain English. Here are some examples of what you can say:

Indexing and Watching Files

• To index a new project:
• "Please index the code in the /path/to/my-project directory."

OR

• "Add the project at ~/dev/my-other-project to the code graph."

• To start watching a directory for live changes:
• "Watch the /path/to/my-active-project directory for changes."

OR

• "Keep the code graph updated for the project I'm working on at ~/dev/main-app."

When you ask to watch a directory, the system performs two actions at once:

1. It kicks off a full scan to index all the code in that directory. This process runs in the background, and you'll receive a job_id to track its progress.
2. It begins watching the directory for any file changes to keep the graph updated in real-time.

This means you can start by simply telling the system to watch a directory, and it will handle both the initial indexing and the continuous updates automatically.

Querying and Understanding Code

• Finding where code is defined:
• "Where is the process_payment function?"
• "Find the User class for me."
• "Show me any code related to 'database connection'."

• Analyzing relationships and impact:
• "What other functions call the get_user_by_id function?"
• "If I change the calculate_tax function, what other parts of the code will be affected?"
• "Show me the inheritance hierarchy for the BaseController class."
• "What methods does the Order class have?"

• Exploring dependencies:
• "Which files import the requests library?"
• "Find all implementations of the render method."

• Advanced Call Chain and Dependency Tracking (Spanning Hundreds of Files):

The CodeGraphContext excels at tracing complex execution flow

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CodeGraphContext
• Source: CodeGraphContext/CodeGraphContext
• License: MIT
• Homepage: https://cgc.codes

Install and usage instructions live in the source repository linked above.