CodeGraph - Knowledge Graph Visualization Tool

Visualize codebases as knowledge graphs to analyze dependencies, detect bottlenecks, and optimize projects.

Connect and ask questions:

Live Demo

Project Structure

code-graph/
├── api/                  # Python backend (FastAPI)
│   ├── index.py          # FastAPI app, auth deps, API routes, SPA serving
│   ├── graph.py          # FalkorDB graph operations
│   ├── llm.py            # GraphRAG + LiteLLM chat integration
│   ├── project.py        # Repository cloning and analysis orchestration
│   ├── info.py           # Repository metadata stored in Redis/FalkorDB
│   ├── prompts.py        # LLM system and prompt templates
│   ├── cli.py            # cgraph CLI tool (typer)
│   ├── auto_complete.py  # Prefix search helper
│   ├── analyzers/        # Source analyzers (Python, Java, C#)
│   ├── entities/         # Graph/entity models
│   ├── git_utils/        # Git history graph utilities
│   └── code_coverage/    # Coverage utilities
├── app/                  # React frontend (Vite)
│   ├── src/              # Frontend source code
│   ├── public/           # Static assets
│   ├── package.json      # Frontend dependencies and scripts
│   ├── vite.config.ts    # Vite config and /api proxy for dev mode
│   └── tsconfig*.json    # TypeScript config
├── skills/code-graph/    # Claude Code skill for CLI-driven indexing/querying
├── tests/                # Backend/unit and endpoint tests
├── e2e/                  # End-to-end helpers and Playwright assets
├── Dockerfile            # Unified container image
├── docker-compose.yml    # Local FalkorDB + app stack
├── Makefile              # Common dev/build/test commands
├── start.sh              # Container entrypoint
├── pyproject.toml        # Python package and dependency config
└── .env.template         # Example environment variables

Running Locally

Prerequisites

Python >=3.12,<3.14
Node.js 20+
uv
A FalkorDB instance (local/cloud) or the optional FalkorDBLite backend

1. Start FalkorDB

Option A: Free cloud instance at app.falkordb.cloud

Option B: Run locally with Docker:

docker run -p 6379:6379 -it --rm falkordb/falkordb

Option C: Use embedded FalkorDBLite:

uv sync --extra light
export CODE_GRAPH_DB_BACKEND=lite
export FALKORDB_LITE_PATH=~/.cache/code-graph/falkordblite.rdb

FalkorDBLite runs a local embedded server over a private Unix socket by default. Set FALKORDB_LITE_PORT only when a host/port-only integration, such as GraphRAG chat, must connect to the embedded database.

2. Configure environment variables

Copy the template and adjust it for your setup:

cp .env.template .env

Variable	Description	Required	Default
`CODE_GRAPH_DB_BACKEND`	Database backend: `falkordb` or `lite`	No	`falkordb`
`FALKORDB_HOST`	FalkorDB hostname	No	`localhost`
`FALKORDB_PORT`	FalkorDB port	No	`6379`
`FALKORDB_USERNAME`	Optional FalkorDB username	No	empty
`FALKORDB_PASSWORD`	Optional FalkorDB password	No	empty
`FALKORDB_LITE_PATH`	FalkorDBLite database file path	No	`~/.cache/code-graph/falkordblite.rdb`
`FALKORDB_LITE_HOST`	Host used when exposing FalkorDBLite over TCP	No	`127.0.0.1`
`FALKORDB_LITE_PORT`	Optional TCP port for FalkorDBLite host/port clients	No	empty
`SECRET_TOKEN`	Token checked by protected endpoints	No	empty
`CODE_GRAPH_PUBLIC`	Set `1` to skip auth on read-only endpoints	No	`0`
`ALLOWED_ANALYSIS_DIR`	Root path allowed for `/api/analyze_folder`	No	repository root
`MODEL_NAME`	LiteLLM model used by `/api/chat`	No	`gemini/gemini-flash-lite-latest`
`HOST`	Optional Uvicorn bind host for `start.sh`/`make run-*`	No	`0.0.0.0` or `127.0.0.1` depending on command
`PORT`	Optional Uvicorn bind port for `start.sh`/`make run-*`	No	`5000`

The chat endpoint also needs the provider credential expected by your chosen MODEL_NAME. The default model is Gemini, so set GEMINI_API_KEY unless you switch to a different LiteLLM provider/model.

Authentication behavior

Send Authorization: Bearer <SECRET_TOKEN> (or the raw token string) when SECRET_TOKEN is configured.
Read endpoints use the public_or_auth dependency.
Mutating endpoints (/api/analyze_folder, /api/analyze_repo, /api/switch_commit) use the token_required dependency.
If SECRET_TOKEN is unset, the current implementation accepts requests without an Authorization header.
Setting CODE_GRAPH_PUBLIC=1 makes the read-only endpoints public even when SECRET_TOKEN is configured.

3. Install dependencies

# Install backend dependencies
uv sync --all-extras

# Install frontend dependencies
npm install --prefix ./app

# Optional: install Playwright dependencies from the repo root
npm install

If you do not use uv, pip install -e ".[test]" also installs the backend package and test dependencies.

4. Run the app

Backend API with auto-reload:

uv run uvicorn api.index:app --host 127.0.0.1 --port 5000 --reload

Frontend hot-reload with Vite:

# Terminal 1: backend API
uv run uvicorn api.index:app --host 127.0.0.1 --port 5000 --reload

# Terminal 2: Vite dev server
cd app && npm run dev

The Vite dev server runs on http://localhost:3000 and proxies /api/* requests to http://127.0.0.1:5000.

Single-process built frontend + backend:

npm --prefix ./app run build
uv run uvicorn api.index:app --host 0.0.0.0 --port 5000

In this mode, the FastAPI app serves the built React SPA from app/dist on http://localhost:5000.

Using Make

make install       # Install backend + frontend dependencies
make install-cli   # Install cgraph CLI entry point
make build-dev     # Build frontend in development mode
make build-prod    # Build frontend for production
make run-dev       # Build dev frontend + run Uvicorn with reload
make run-prod      # Build prod frontend + run Uvicorn
make test          # Run backend pytest suite
make lint          # Run Ruff + frontend type-check
make e2e           # Run Playwright tests from repo root
make clean         # Remove build/test artifacts

make test currently points at the right backend test entrypoint, but some legacy analyzer/git-history tests still need maintenance before the suite passes on a clean checkout.

CLI Tool (`cgraph`)

CodeGraph includes a CLI tool for indexing codebases and querying the knowledge graph directly from the terminal. All output is JSON (to stdout), with status messages on stderr.

Install

# Install from PyPI (recommended for end users)
pipx install falkordb-code-graph

# Or with pip
pip install falkordb-code-graph

For development (from a local clone):

make install-cli
# or
uv pip install -e .

Usage

# Ensure FalkorDB is running (auto-starts a Docker container if needed)
cgraph ensure-db

# Index the current project
cgraph index . --ignore node_modules --ignore .git --ignore venv --ignore __pycache__

# Index a remote repository
cgraph index-repo https://github.com/user/repo --ignore node_modules

# List indexed repos
cgraph list

# Search for entities by name prefix
cgraph search parse_config

# Explore relationships (what does node 42 call?)
cgraph neighbors 42 --rel CALLS

# Find call-chain paths between two nodes
cgraph paths 42 99

# Show repo statistics
cgraph info

The --repo flag defaults to the current directory name. Run cgraph --help for full details.

Claude Code Skill

A Claude Code skill is included in skills/code-graph/. Install it with:

npx skills add FalkorDB/code-graph

Then ask Claude things like "what functions call analyze_sources?" or "find the dependency chain between parse_config and send_request" — it will handle the indexing and querying automatically.

MCP server (`cgraph-mcp`)

For agents that speak the Model Context Protocol (Claude Code, Cursor, Cline, …), code-graph ships a stdio MCP server that exposes the knowledge graph as 7 first-class tools: index_repo, search_code, find_symbol, get_neighbors, get_file_neighbors, impact_analysis, and find_path.

Quickstart — Claude Code:

# 1. Install (in any venv with the cgraph package on PATH)
pip install falkordb-code-graph         # or: uv pip install falkordb-code-graph

# 2. Register with Claude Code
claude mcp add-json code-graph '{
  "command": "cgraph-mcp",
  "env": {
    "FALKORDB_HOST": "localhost",
    "FALKORDB_PORT": "6379",
    "CODE_GRAPH_AUTO_INDEX": "true"
  }
}'

# 3. Drop agent guidance into your repo
cd /path/to/your/repo
cgraph init-agent              # writes CLAUDE.md and .cursorrules

Quickstart — Docker Compose:

docker compose up -d falkordb                       # start the DB
docker compose --profile mcp run --rm -i code-graph-mcp   # attach via stdio

The MCP server auto-bootstraps FalkorDB if it's missing on localhost (via cgraph ensure-db). When CODE_GRAPH_AUTO_INDEX=true is set, the current working directory is indexed automatically on start.

Transport: Phase 1 is stdio only. HTTP/SSE is deferred.

Running with Docker

Using Docker Compose

docker compose up --build

This starts FalkorDB and the CodeGraph app together. The checked-in compose file sets CODE_GRAPH_PUBLIC=1 for the app service.

To run the MCP stdio server instead of the web app from the same image, set CGRAPH_MODE=mcp and use the mcp profile:

docker compose --profile mcp run --rm -i code-graph-mcp

Using Docker directly

docker build -t code-graph .

# Web mode (default)
docker run -p 5000:5000 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MODEL_NAME=gemini/gemini-flash-lite-latest \
  -e GEMINI_API_KEY=<YOUR_GEMINI_API_KEY> \
  -e SECRET_TOKEN=<YOUR_SECRET_TOKEN> \
  code-graph

# MCP stdio mode (same image)
docker run --rm -i \
  -e CGRAPH_MODE=mcp \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MODEL_NAME=gemini/gemini-flash-lite-latest \
  code-graph

Creating a Code Graph

Analyze a local folder

analyze_folder only accepts paths under ALLOWED_ANALYSIS_DIR (defaults to the repository root unless you override it).

curl -X POST http://127.0.0.1:5000/api/analyze_folder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \
  -d '{"path": "<FULL_PATH_TO_FOLDER>", "ignore": [".github", ".git"]}'

Analyze a Git repository

curl -X POST http://127.0.0.1:5000/api/analyze_repo \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \
  -d '{"repo_url": "https://github.com/user/repo", "ignore": [".github", ".git"]}'

List indexed repositories

curl http://127.0.0.1:5000/api/list_repos

Supported Languages

api/analyzers/source_analyzer.py currently enables these analyzers:

Python (.py)
Java (.java)
C# (.cs)

A C analyzer exists in the source tree, but it is commented out and is not currently registered.

API Endpoints

Read endpoints

Method	Endpoint	Description
GET	`/api/list_repos`	List all indexed repositories
GET	`/api/graph_entities?repo=<name>`	Fetch a subgraph for a repository
POST	`/api/get_neighbors`	Return neighboring nodes for the provided IDs
POST	`/api/auto_complete`	Prefix-search indexed entities
POST	`/api/repo_info`	Return repository stats and saved metadata
POST	`/api/find_paths`	Find paths between two graph nodes
POST	`/api/chat`	Ask questions over the code graph via GraphRAG
POST	`/api/list_commits`	List commits from the repository's git graph

Mutating endpoints

Method	Endpoint	Description
POST	`/api/analyze_folder`	Analyze a local source folder
POST	`/api/analyze_repo`	Clone and analyze a git repository
POST	`/api/switch_commit`	Switch the indexed repository to a specific commit

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright FalkorDB Ltd. 2025