Visualize codebases as knowledge graphs to analyze dependencies, detect bottlenecks, and optimize projects.
Connect and ask questions:
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
- Python
>=3.12,<3.14 - Node.js 20+
uv- A FalkorDB instance (local/cloud) or the optional FalkorDBLite backend
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.
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.
- Send
Authorization: Bearer <SECRET_TOKEN>(or the raw token string) whenSECRET_TOKENis configured. - Read endpoints use the
public_or_authdependency. - Mutating endpoints (
/api/analyze_folder,/api/analyze_repo,/api/switch_commit) use thetoken_requireddependency. - If
SECRET_TOKENis unset, the current implementation accepts requests without anAuthorizationheader. - Setting
CODE_GRAPH_PUBLIC=1makes the read-only endpoints public even whenSECRET_TOKENis configured.
# 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.
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.
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.
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 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 .
# 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.
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.
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.
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
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
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"]}'
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"]}'
curl http://127.0.0.1:5000/api/list_repos
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.
| 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 |
| 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 |
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright FalkorDB Ltd. 2025