Code-Graph - FalkorDB Docs

Visualize codebases as knowledge graphs to analyze dependencies, detect bottlenecks, and optimize projects. Code-Graph is a FalkorDB-powered tool that indexes source code repositories into a knowledge graph. It provides an interactive web UI and a CLI for exploring code structure, querying relationships between entities, and chatting with your codebase using GraphRAG. Live Demo · GitHub Repository Code-Graph — interactive code analysis visualization

Code-Graph — interactive code analysis visualization

Key Features

Feature	Description
Code knowledge graph	Indexes source code into a FalkorDB graph with entities (classes, functions, files) and relationships (calls, imports, inherits).
Interactive web UI	React-based frontend for visualizing and exploring the code graph with pan, zoom, and search.
GraphRAG chat	Ask natural-language questions about your codebase. Powered by LiteLLM and FalkorDB GraphRAG.
CLI tool (`cgraph`)	Index repositories, search entities, explore relationships, and find paths from the terminal. All output is JSON.
Git history analysis	Analyze git history to understand how code evolves.
Multi-language support	Analyzers for Python, Java, and C#.

Supported Languages

Code-Graph currently supports the following languages:

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

Running with Docker

Clone the Code-Graph repository and navigate into it:

git clone https://github.com/FalkorDB/Code-Graph.git
cd Code-Graph

Using Docker Compose

docker compose up --build

This starts FalkorDB and the Code-Graph app together.

Using Docker directly

Start a FalkorDB instance:

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

Build and run the Code-Graph container:

docker build -t code-graph .
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

Running Locally

Prerequisites

Python >=3.12,<3.14
Node.js 20+
uv
A FalkorDB instance (local or FalkorDB Cloud)

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

2. Configure environment variables

cp .env.template .env

Variable	Description	Required	Default
`FALKORDB_HOST`	FalkorDB hostname	No	`localhost`
`FALKORDB_PORT`	FalkorDB port	No	`6379`
`FALKORDB_USERNAME`	FalkorDB username	No
`FALKORDB_PASSWORD`	FalkorDB password	No
`SECRET_TOKEN`	Token for protected endpoints	No
`CODE_GRAPH_PUBLIC`	Set `1` to skip auth on read-only endpoints	No	`0`
`MODEL_NAME`	LiteLLM model used by `/api/chat`	No	`gemini/gemini-flash-lite-latest`
`HOST`	Uvicorn bind host	No	`0.0.0.0`
`PORT`	Uvicorn bind port	No	`5000`

The chat endpoint also requires the provider credential for your chosen MODEL_NAME. The default model is Gemini, so set GEMINI_API_KEY unless you use a different LiteLLM provider.

3. Install dependencies

# Backend
uv sync --all-extras

# Frontend
npm install --prefix ./app

4. Run the app

Backend + frontend (development):

# 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 production build:

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

CLI Tool (`cgraph`)

Code-Graph includes a CLI tool for indexing codebases and querying the knowledge graph from the terminal.

Install

# Install from PyPI
pip install falkordb-code-graph

# Or with pipx (recommended)
pipx install falkordb-code-graph

Usage

# Ensure FalkorDB is running
cgraph ensure-db

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

# 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

Run cgraph --help for full details.

Creating a Code Graph

Analyze a local folder

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

Note: If SECRET_TOKEN is set and CODE_GRAPH_PUBLIC is not enabled (1), add -H "Authorization: Bearer <YOUR_SECRET_TOKEN>" to the request.

GraphRAG Chat

Use the built-in chat interface to ask natural-language questions about your codebase. Code-Graph translates your questions into graph queries and returns contextual answers powered by LiteLLM and FalkorDB GraphRAG. Code-Graph — chat with your code graph

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

Authentication

Behavior	Description
Token auth	Send `Authorization: Bearer <SECRET_TOKEN>` when `SECRET_TOKEN` is configured.
Read endpoints	Use the `public_or_auth` dependency — accessible without auth if `CODE_GRAPH_PUBLIC=1`.
Mutating endpoints	Require the `token_required` dependency — always need a valid token.
No token configured	Requests are accepted without an `Authorization` header when `SECRET_TOKEN` is unset.

Resources

Frequently Asked Questions

What is Code-Graph?

Code-Graph is a FalkorDB-powered tool that indexes source code repositories into a knowledge graph. It provides an interactive web UI and CLI for exploring code structure, querying relationships between entities, and chatting with your codebase using GraphRAG.

Which programming languages does Code-Graph support?

Code-Graph currently supports Python (.py), Java (.java), and C# (.cs). It analyzes classes, functions, files, and their relationships (calls, imports, inherits).

Can I ask questions about my codebase in natural language?

Yes. Code-Graph includes a GraphRAG chat feature powered by LiteLLM that lets you ask natural-language questions about your code. It translates your questions into graph queries and returns contextual answers about dependencies, structure, and relationships.

How do I index a repository using the CLI?

Install with pip install falkordb-code-graph or pipx install falkordb-code-graph, then run cgraph index . --ignore node_modules --ignore .git for a local project, or cgraph index-repo https://github.com/user/repo for a remote repository.

Do I need authentication to use Code-Graph?

Authentication depends on your configuration. Set SECRET_TOKEN to require Bearer token auth on mutating endpoints. Set CODE_GRAPH_PUBLIC=1 to allow read-only access without auth. When no token is configured, requests are accepted without authorization.

​Key Features

​Supported Languages

​Running with Docker

​Using Docker Compose

​Using Docker directly

​Running Locally

​Prerequisites

​1. Start FalkorDB

​2. Configure environment variables

​3. Install dependencies

​4. Run the app

​CLI Tool (cgraph)

​Install

​Usage

​Creating a Code Graph

​Analyze a local folder

​Analyze a Git repository

​List indexed repositories

​GraphRAG Chat

​API Endpoints

​Read endpoints

​Mutating endpoints

​Authentication

​Resources

​Frequently Asked Questions