### MCP Server Quickstart: Docker Compose

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Instructions to start the FalkorDB service and attach to the `cgraph-mcp` server via stdio using Docker Compose. The server auto-boots FalkorDB if needed.

```bash
docker compose up -d falkordb                       # start the DB
```

```bash
docker compose --profile mcp run --rm -i code-graph-mcp   # attach via stdio
```

--------------------------------

### Install Backend and Frontend Dependencies

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Installs all required backend dependencies using 'uv sync' with all extras, and frontend dependencies using 'npm install' in the './app' directory. Optionally installs Playwright dependencies.

```bash
# Install backend dependencies
uv sync --all-extras

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

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

--------------------------------

### Install cgraph CLI

Source: https://github.com/falkordb/code-graph/blob/staging/skills/code-graph/references/management.md

Install the command-line interface for interacting with the Code Graph. Use `pipx` for global installation or `pip` for project-specific installation.

```bash
pipx install falkordb-code-graph
```

```bash
pip install falkordb-code-graph
```

--------------------------------

### MCP Server Quickstart: Claude Code

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Steps to install the `cgraph` package and register the `cgraph-mcp` server with Claude Code. Configure environment variables for database connection and auto-indexing.

```bash
pip install falkordb-code-graph         # or: uv pip install falkordb-code-graph
```

```bash
claude mcp add-json code-graph '{ 
  "command": "cgraph-mcp",
  "env": {
    "FALKORDB_HOST": "localhost",
    "FALKORDB_PORT": "6379",
    "CODE_GRAPH_AUTO_INDEX": "true"
  }
}'
```

```bash
cd /path/to/your/repo
cgraph init-agent              # writes CLAUDE.md and .cursorrules
```

--------------------------------

### Install Dependencies with Make

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Use `make install` to install all project dependencies, including Python and Node.js packages. `make install-cli` installs only the CLI entry point.

```bash
make install         # Install all deps (uv sync + npm install)
make install-cli     # Install cgraph CLI entry point
```

--------------------------------

### Install Dependencies

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Install all project dependencies, including the command-line interface (CLI) and frontend build assets. Use the dev build for active development.

```bash
make install
```

```bash
make install-cli
```

```bash
make build-dev
```

--------------------------------

### Install and Run Code Graph CLI

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Install the Code Graph CLI using pipx or pip. For development, use make install-cli or uv pip install -e .

```bash
pipx install falkordb-code-graph
```

```bash
pip install falkordb-code-graph
```

```bash
make install-cli
```

```bash
uv pip install -e .
```

--------------------------------

### Install CLI Tool from Local Clone

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Install the `cgraph` CLI tool from a local source code clone using `make` or `uv`.

```bash
make install-cli
```

```bash
uv pip install -e .
```

--------------------------------

### Install Backend Dependencies with Pip

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Alternative method to install backend dependencies using pip if 'uv' is not used. Includes test dependencies.

```bash
pip install -e ".[test]"
```

--------------------------------

### Example Python Configuration for Development

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Shows a sample configuration for a development environment. Assumes Linux/macOS shell syntax.

```python
export DB_BACKEND=falkordb
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=user
export DB_PASSWORD=password
export DB_NAME=graphdb
export GRAPH_DB_PATH=/data/graph.db
export PROJECT_DB_PATH=/data/project.db
export ANALYZER_DB_PATH=/data/analyzer.db
export CACHE_SIZE=1024
export LOG_LEVEL=DEBUG
export LOG_FILE=/var/log/codegraph.log
export MAX_THREADS=4
export MAX_ITERATIONS=1000
export ENABLE_PROFILING=false
export ENABLE_METRICS=false
export METRICS_PORT=9090
export AUTH_MODE=bearer
export JWT_SECRET=mysecretkey
```

--------------------------------

### Example Docker Configuration

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Provides an example configuration for running CodeGraph within a Docker environment. Assumes Linux/macOS shell syntax.

```shell
docker run -d \
  -p 8080:8080 \
  -e DB_BACKEND=falkordb \
  -e DB_HOST=falkordb-db \
  -e DB_PORT=5432 \
  -e DB_USER=user \
  -e DB_PASSWORD=password \
  -e DB_NAME=graphdb \
  -e GRAPH_DB_PATH=/data/graph.db \
  -e PROJECT_DB_PATH=/data/project.db \
  -e ANALYZER_DB_PATH=/data/analyzer.db \
  -e CACHE_SIZE=1024 \
  -e LOG_LEVEL=INFO \
  -e LOG_FILE=/var/log/codegraph.log \
  -e MAX_THREADS=4 \
  -e MAX_ITERATIONS=1000 \
  -e ENABLE_PROFILING=false \
  -e ENABLE_METRICS=false \
  -e METRICS_PORT=9090 \
  -e AUTH_MODE=bearer \
  -e JWT_SECRET=mysecretkey \
  falkordb/codegraph:latest
```

--------------------------------

### Install CLI Tool from PyPI

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Install the `cgraph` CLI tool using pipx or pip. Recommended for end users.

```bash
pipx install falkordb-code-graph
```

```bash
pip install falkordb-code-graph
```

--------------------------------

### Install cgraph CLI for Development (Troubleshooting)

Source: https://github.com/falkordb/code-graph/blob/staging/skills/code-graph/references/management.md

If the `cgraph` command is not found, ensure the package is installed correctly. This command is for development installations from a local clone.

```bash
uv pip install -e .   # from the code-graph repo
```

--------------------------------

### HTTP Request/Response Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Provides an example of an HTTP POST request to the `/api/get_neighbors` endpoint and its expected JSON response.

```APIDOC
## HTTP Request/Response

This section details an example HTTP request and its response for retrieving neighbors.

### Endpoint

`POST /api/get_neighbors`

### Request Example

```bash
curl -X POST http://localhost:5000/api/get_neighbors \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ 
    "repo": "my-project",
    "node_ids": [1, 2],
    "branch": "main"
  }'
```

### Request Body Parameters

- **repo** (string) - Required - The repository name.
- **node_ids** (array of integers) - Required - The list of node IDs.
- **branch** (string) - Optional - The branch name.

### Response Example (Success)

```json
{
  "status": "success",
  "branch": "main",
  "neighbors": {
    "nodes": [...],
    "edges": [...] 
  }
}
```

### Response Body Fields (Success)

- **status** (string) - The status of the request.
- **branch** (string) - The branch name.
- **neighbors** (object) - Contains nodes and edges related to the query.
```

--------------------------------

### Install cgraph CLI for Development

Source: https://github.com/falkordb/code-graph/blob/staging/skills/code-graph/references/management.md

Install the cgraph CLI from a local clone of the repository for development purposes. This ensures you are using the latest code.

```bash
cd /path/to/code-graph
uv sync --all-extras
uv pip install -e .
```

--------------------------------

### Verify cgraph CLI Installation

Source: https://github.com/falkordb/code-graph/blob/staging/skills/code-graph/references/management.md

Run this command after installation to confirm that the cgraph CLI is accessible and working correctly.

```bash
cgraph --help
```

--------------------------------

### Python Client Example for Sync and Async Usage

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Demonstrates how to use the Python client for both synchronous and asynchronous operations. Requires Python 3.12+ syntax and FalkorDB/Cypher knowledge.

```python
from falkordb import FalkorDB

# Sync example
db_sync = FalkorDB(host='localhost', port=5432, database='graphdb', user='user', password='password')
result_sync = db_sync.query('MATCH (n) RETURN n LIMIT 1')
print(result_sync)

# Async example
async def run_async():
    db_async = FalkorDB(host='localhost', port=5432, database='graphdb', user='user', password='password')
    result_async = await db_async.query_async('MATCH (n) RETURN n LIMIT 1')
    print(result_async)

import asyncio
asyncio.run(run_async())
```

--------------------------------

### Install cgraph CLI

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/cli-reference.md

Install the cgraph CLI tool using pipx for end users or via make install-cli/uv pip install for local development.

```bash
pipx install falkordb-code-graph
```

```bash
make install-cli
```

```bash
uv pip install -e .
```

--------------------------------

### CLI Command Example with JSON Output

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Demonstrates a command-line interface command and its expected JSON output format. Useful for CLI users.

```shell
# Example CLI command
cgraph analyze --project /path/to/project --language python

# Example JSON output
{
  "status": "success",
  "message": "Analysis complete.",
  "data": {
    "nodes": 150,
    "edges": 300
  }
}
```

--------------------------------

### Run Development Servers

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Start the backend API with auto-reloading and the frontend development server. Access the application via the specified browser URL.

```bash
# Terminal 1: Backend with auto-reload
uv run uvicorn api.index:app --host 127.0.0.1 --port 5000 --reload
```

```bash
# Terminal 2: Frontend dev server (Vite)
npm --prefix ./app run dev
```

```bash
# Browser: http://localhost:3000
```

--------------------------------

### Troubleshoot FalkorDB Lite Installation

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

Command to install FalkorDB Lite, which may be required if encountering issues related to its absence.

```bash
uv sync --extra light
```

--------------------------------

### List Repositories cURL Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/endpoints.md

Example cURL command to list all indexed repositories. This endpoint is accessible without authentication if `CODE_GRAPH_PUBLIC` is set to 1.

```bash
curl http://localhost:5000/api/list_repos
```

--------------------------------

### Start FalkorDB and CodeGraph with Docker Compose

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Use this command to start both FalkorDB and the CodeGraph application using the provided Docker Compose file. The compose file is pre-configured with `CODE_GRAPH_PUBLIC=1` for the app service.

```bash
docker compose up --build
```

--------------------------------

### Project Build and Management Commands

Source: https://github.com/falkordb/code-graph/blob/staging/AGENTS.md

Use these make commands for common project tasks like installation, building, running development servers, testing, and linting.

```bash
make install         # Install all deps (uv sync + npm install)
make install-cli     # Install cgraph CLI entry point
make build-dev       # Build frontend (dev mode)
make build-prod      # Build frontend (production)
make run-dev         # Build dev frontend + run API with reload
make run-prod        # Build prod frontend + run API
make test            # Run pytest suite
make lint            # Ruff + TypeScript type-check
make lint-py         # Ruff only
make lint-fe         # TypeScript type-check only
make e2e             # Run Playwright tests
make clean           # Remove build artifacts
make docker-falkordb # Start FalkorDB container for testing
make docker-stop     # Stop test containers
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Illustrates common commands for interacting with the Code Graph via its command-line interface.

```APIDOC
## CLI Usage

This section provides examples of using the `cgraph` command-line tool.

### Commands

- `cgraph ensure-db`: Ensures the database is set up.
- `cgraph index . --branch main --ignore .git --ignore node_modules`: Indexes the current directory.
- `cgraph search "parse_"`: Searches for entities containing "parse_".
- `cgraph neighbors 42 --rel CALLS`: Retrieves neighbors of node 42 with the relationship CALLS.
- `cgraph paths 42 99`: Finds paths between node 42 and node 99.
- `cgraph info`: Displays information about the code graph.
```

--------------------------------

### Loading Configuration with python-dotenv

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/configuration.md

Example of an .env file used with python-dotenv for loading configuration variables. Ensure this file is kept secure.

```bash
# Database
CODE_GRAPH_DB_BACKEND=lite
FALKORDB_LITE_PATH=~/.cache/code-graph/falkordblite.rdb

# Auth
CODE_GRAPH_PUBLIC=1

# LLM
MODEL_NAME=gemini/gemini-flash-lite-latest
GEMINI_API_KEY=your-api-key

# Server
HOST=127.0.0.1
PORT=5000
```

--------------------------------

### Auto Complete cURL Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/endpoints.md

Example cURL command for prefix-based entity search within a repository. Requires `Content-Type` header and a JSON request body.

```bash
curl -X POST http://localhost:5000/api/auto_complete \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-project", "prefix": "parse"}'
```

--------------------------------

### Run Application with Make

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Run the application in development mode with hot-reloading using `make run-dev`, which builds the dev frontend and starts the API. For production, use `make run-prod` after building the production frontend.

```bash
make run-dev         # Build dev frontend + run API with reload
make run-prod        # Build prod frontend + run API
```

--------------------------------

### Fetch Graph Entities cURL Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/endpoints.md

Example cURL command to fetch a sub-graph for a specific repository and branch. The `repo` parameter is required.

```bash
curl "http://localhost:5000/api/graph_entities?repo=my-project&branch=main"
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Start the Vite development server for the frontend. This command proxies API requests to port 5000 and provides hot-reloading for rapid development.

```bash
npm --prefix ./app run dev          # Vite dev server (port 3000, proxies /api to 5000)
```

--------------------------------

### Manage Docker Containers with Make

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Start the FalkorDB container for testing with `make docker-falkordb` and stop test containers with `make docker-stop`.

```bash
make docker-falkordb # Start FalkorDB container for testing
make docker-stop     # Stop test containers
```

--------------------------------

### Run FalkorDB with Docker

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Starts a local FalkorDB instance using Docker. Ensure port 6379 is available.

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

--------------------------------

### Install FalkorDB Lite Dependency

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Provides commands to install the FalkorDB Lite dependency using either uv or pip, enabling the use of FalkorDB Lite.

```bash
# Install with lite extra
pip install 'falkordb-code-graph[light]'
# or
uv sync --extra light
```

--------------------------------

### Troubleshoot Module Not Found

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

Command to install necessary dependencies, including test extras, to resolve 'MODULE_NOT_FOUND' errors.

```bash
pip install falkordb-code-graph[test]
```

--------------------------------

### Example Go Language Analyzer Implementation

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-analyzers.md

This pseudo-code demonstrates how to implement a new language analyzer for Go by subclassing AbstractAnalyzer. It shows the required methods for dependency checking, path resolution, and entity labeling.

```python
from api.analyzers.analyzer import AbstractAnalyzer
from tree_sitter import Language, Parser

class GoAnalyzer(AbstractAnalyzer):
    def __init__(self):
        lang = Language("path/to/tree-sitter-go.so", "go")
        super().__init__(lang)
    
    def is_dependency(self, file_path: str) -> bool:
        return "vendor/" in file_path or "/go/src/" in file_path
    
    def resolve_path(self, file_path: str, path: Path) -> str:
        return str(Path(file_path).resolve())
    
    def get_entity_label(self, node: Node) -> str:
        if node.type == "function_declaration":
            return "Function"
        elif node.type == "type_declaration":
            return "Class"
        return "Unknown"
    
    def get_entity_name(self, node: Node) -> str:
        # Extract name from node
        pass
    
    def add_dependencies(self, path: Path, files: list[Path]):
        # Add Go stdlib functions
        pass
```

--------------------------------

### Configure FalkorDBLite Backend

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Sets up FalkorDBLite for local embedded use. Installs extra dependencies with 'uv' and exports environment variables to specify the backend and database path.

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

--------------------------------

### Run Backend Development Server

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Manually start the Uvicorn development server for the backend API. Ensure you are in the correct directory and have the necessary environment variables set.

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

--------------------------------

### Example of AbstractAnalyzer Base Class Implementation

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Provides a template for language implementation by extending the AbstractAnalyzer base class. This is for extension authors.

```python
from falkordb.analyzers import AbstractAnalyzer

class PythonAnalyzer(AbstractAnalyzer):
    def analyze(self, code: str, file_path: str) -> Dict[str, Any]:
        # Implement Python code analysis logic here
        # Parse code, extract AST, identify nodes and edges
        nodes = []
        edges = []
        # ...
        return {"nodes": nodes, "edges": edges}

    def get_language(self) -> str:
        return "python"
```

--------------------------------

### Run Backend API and Frontend Dev Server

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Starts the backend API with auto-reload in one terminal and the Vite development server for the frontend in another. The frontend proxies API requests to the backend.

```bash
# 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
```

--------------------------------

### Install FalkorDB Code Graph Skill

Source: https://github.com/falkordb/code-graph/blob/staging/skills/code-graph/references/management.md

Use this command to add the FalkorDB Code Graph skill to your project.

```bash
npx skills add FalkorDB/code-graph
```

--------------------------------

### Python Class Hierarchy Example

Source: https://github.com/falkordb/code-graph/blob/staging/tests/mcp/fixtures/sample_project/README.md

Shows a simple Python class hierarchy. This is a textual representation and not executable code.

```text
BaseRepo
  ├── UserRepo
  └── OrderRepo
```

--------------------------------

### Get Neighbors cURL Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/endpoints.md

Example cURL command to get neighboring nodes for a list of node IDs. Requires setting the `Content-Type` header and providing a JSON request body.

```bash
curl -X POST http://localhost:5000/api/get_neighbors \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-project", "node_ids": [1, 2]}'
```

--------------------------------

### Copy Environment Template

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Copies the template file for environment variables. Adjust the '.env' file to match your local setup.

```bash
cp .env.template .env
```

--------------------------------

### Production (Remote FalkorDB, Public Read)

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/configuration.md

Production setup with a remote FalkorDB, enabling public read access. Ensure sensitive credentials are managed securely.

```bash
CODE_GRAPH_DB_BACKEND=falkordb
FALKORDB_HOST=graph-db.example.com
FALKORDB_PORT=6379
FALKORDB_USERNAME=production
FALKORDB_PASSWORD=secure-password
CODE_GRAPH_PUBLIC=1
SECRET_TOKEN=production-token-xyz
MODEL_NAME=openai/gpt-4-turbo
OPENAI_API_KEY=sk-...
HOST=0.0.0.0
PORT=5000
ALLOWED_ANALYSIS_DIR=/var/code-projects
```

--------------------------------

### Python Call Graph Example

Source: https://github.com/falkordb/code-graph/blob/staging/tests/mcp/fixtures/sample_project/README.md

Illustrates a typical Python call graph structure. This is a textual representation and not executable code.

```text
entrypoint() -> service() -> {UserRepo,OrderRepo}.repo() -> db()
```

--------------------------------

### Example cURL Request for an Endpoint

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Illustrates how to make an HTTP request to an endpoint using cURL. This is useful for API integrators.

```shell
curl -X POST \
  http://localhost:8080/api/v1/graph/project/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d @request.json
```

--------------------------------

### Fetch Repository Metadata Asynchronously

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-utilities.md

Example of how to use async_get_repo_info to fetch metadata in an async function. Ensure the async_get_repo_info function is imported.

```python
from api.info import async_get_repo_info

async def fetch_metadata(repo_name: str):
    info = await async_get_repo_info(repo_name)
    return info
```

--------------------------------

### Index Repository

Source: https://github.com/falkordb/code-graph/blob/staging/api/mcp/templates/claude_mcp_section.md

Call this first when starting with a new repository or after significant changes. The project name is derived from the folder or URL.

```python
index_repo(path_or_url=".")
```

--------------------------------

### create_async_falkordb

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Creates an asynchronous database client for non-blocking queries. It can return either a `falkordb.asyncio.FalkorDB` instance or a `redislite.async_falkordb_client.AsyncFalkorDB` instance if FalkorDBLite is selected and installed.

```APIDOC
## Function: `create_async_falkordb`

### Description
Creates an asynchronous database client. Used by API endpoints for non-blocking queries.

- **falkordb**: Uses `falkordb.asyncio.FalkorDB` (async client)
- **lite**: Uses `redislite.async_falkordb_client.AsyncFalkorDB` with compatibility shim

### Returns
Async FalkorDB or FalkorDBLite instance

### Throws
RuntimeError if FalkorDBLite is selected but not installed

### Example
```python
from api.db import create_async_falkordb

async def query_graph():
    db = create_async_falkordb()
    try:
        graphs = await db.list_graphs()
        g = db.select_graph("code:my-project:main")
        result = await g.query("MATCH (n:Function) RETURN count(n)")
        print(f"Functions: {result.result_set[0][0]}")
    finally:
        await db.aclose()

# In async context:
# await query_graph()
```
```

--------------------------------

### Query the Code Graph

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Examples of querying the code graph for relationships and paths. Includes finding neighbors, pathfinding, and prefix searches.

```python
# Get all outgoing edges from a function
neighbors = g.get_neighbors([42], rel="CALLS", lbl="Function")

# Find call chains
paths = g.find_paths(src=42, dest=99, limit=10)

# Prefix search
results = g.prefix_search("parse_", limit=20)
```

--------------------------------

### Project Initialization and Analysis

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-project.md

Demonstrates how to initialize a Project object for a local folder or clone a Git repository, and then analyze its source code and Git history.

```APIDOC
## Project Initialization and Analysis

### Description
This section shows how to create a `Project` instance, either from a local directory or by cloning a Git repository, and subsequently analyze its source code and Git history.

### Usage

**Option 1: Analyze local folder**
```python
from api.project import Project
from pathlib import Path

project = Project(
    name="my-project",
    path=Path("/home/user/my-project"),
    url="https://github.com/user/my-project"
)
graph = project.analyze_sources(ignore=[".git", "node_modules"])
git_graph = project.process_git_history()
```

**Option 2: Clone and analyze GitHub repo**
```python
project = Project.from_git_repository(
    "https://github.com/user/my-project",
    branch="main"
)
graph = project.analyze_sources()
git_graph = project.process_git_history()
```

### Methods

- **`Project(name: str, path: Path, url: Optional[str] = None)`**: Constructor for initializing a Project from a local path.
- **`Project.from_git_repository(url: str, branch: str = "main")`**: Class method to clone a Git repository and initialize a Project.
- **`project.analyze_sources(ignore: Optional[List[str]] = None)`**: Analyzes the source code of the project. Returns a `Graph` object.
- **`project.process_git_history()`**: Processes the Git commit history of the project. Returns a `GitGraph` object.
```

--------------------------------

### CLI Usage for Database and Indexing

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

These bash commands show how to ensure the database is set up and how to index a local project using the CLI, specifying branches and directories to ignore.

```bash
cgraph ensure-db
cgraph index . --branch main --ignore .git --ignore node_modules
```

--------------------------------

### Initialize Agent Guidance

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Use `cgraph init-agent` to write CLAUDE.md and .cursorrules into a repository. Use the `--force` flag to overwrite existing files.

```bash
cgraph init-agent             # writes CLAUDE.md + .cursorrules
```

```bash
cgraph init-agent --force     # overwrite existing files
```

--------------------------------

### Clone and Index a GitHub Repository with cgraph

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/cli-reference.md

Ensures the database is ready, then clones and indexes a GitHub repository. Ignores specified directories and performs a search for functions starting with 'parse_'.

```bash
cgraph ensure-db
cgraph index-repo https://github.com/user/my-project \
  --ignore .git \
  --ignore node_modules
cgraph search "parse_"
```

--------------------------------

### Create Async FalkorDB Client

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Creates an asynchronous FalkorDB or FalkorDBLite client. Use this for non-blocking graph queries. It may throw a RuntimeError if FalkorDBLite is selected but not installed.

```python
from api.db import create_async_falkordb

async def query_graph():
    db = create_async_falkordb()
    try:
        graphs = await db.list_graphs()
        g = db.select_graph("code:my-project:main")
        result = await g.query("MATCH (n:Function) RETURN count(n)")
        print(f"Functions: {result.result_set[0][0]}")
    finally:
        await db.aclose()

# In async context:
# await query_graph()
```

--------------------------------

### Build Frontend with Make

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Build the frontend application for development or production using `make build-dev` or `make build-prod` respectively. These commands compile frontend assets.

```bash
make build-dev       # Build frontend (dev mode)
make build-prod      # Build frontend (production)
```

--------------------------------

### Create and List Graphs (Sync)

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Demonstrates how to explicitly create a FalkorDB connection and list existing graphs. Typically, the Graph class handles connection management internally.

```python
from api.graph import Graph
from api.db import create_falkordb

# Explicitly create/manage database connection
db = create_falkordb()
graphs = db.list_graphs()

# But typically, Graph() handles this internally
g = Graph("my-project", branch="main")
stats = g.stats()
```

--------------------------------

### Initialize Project Instance

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-project.md

Initializes a Project instance with project details. Automatically detects the current branch if not provided. Creates or opens the associated Graph.

```python
from api.project import Project
from pathlib import Path

project = Project(
    name="my-project",
    path=Path("/home/user/my-project"),
    url="https://github.com/user/my-project",
    branch="main"
)
```

--------------------------------

### Code Graph CLI Commands

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Common commands for managing and interacting with the Code Graph database, including starting the DB, indexing files and repositories, searching, and retrieving information.

```bash
cgraph ensure-db
```

```bash
cgraph index . --ignore node_modules
```

```bash
cgraph index-repo <url>
```

```bash
cgraph list
```

```bash
cgraph search <prefix> [--repo <name>]
```

```bash
cgraph neighbors <id>... [--repo <name>] [--rel <type>] [--label <label>]
```

```bash
cgraph paths <src-id> <dest-id> [--repo <name>]
```

```bash
cgraph info [--repo <name>]
```

--------------------------------

### HTTP API Response Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Example JSON response structure for a successful API request, detailing the status, branch, and retrieved neighbors.

```json
{
  "status": "success",
  "branch": "main",
  "neighbors": {
    "nodes": [...],
    "edges": [...] 
  }
}
```

--------------------------------

### Python Type Definitions Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Shows example type annotations in Python, following standard conventions. These are derived from actual source code.

```python
from typing import List, Dict, Any, Optional

class Node:
    id: str
    label: str
    properties: Dict[str, Any]

class Edge:
    id: str
    source: str
    target: str
    type: str
    properties: Dict[str, Any]

def analyze_code(file_path: str, language: str) -> Dict[str, Any]:
    # ... implementation details ...
    pass
```

--------------------------------

### Run Built Frontend with Backend

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Builds the frontend for production and then runs the backend API using Uvicorn. The FastAPI app serves the built React SPA.

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

--------------------------------

### Pydantic Model Schema Example

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/SUMMARY.txt

Illustrates a Pydantic model schema, often used for request and response validation. This example shows a typical structure.

```python
from pydantic import BaseModel, Field
from typing import List, Dict, Any

class RequestSchema(BaseModel):
    project_path: str
    language: str
    dependencies: Optional[List[str]] = None

class ResponseSchema(BaseModel):
    status: str
    message: str
    data: Dict[str, Any]
```

--------------------------------

### Typical Repository Analysis Workflow

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-utilities.md

Demonstrates analyzing a local repository, triggering metadata saving, and retrieving the project's URL and last indexed commit.

```python
from api.project import Project
from api.info import get_repo_info, set_repo_commit
from pathlib import Path

# Analyze a repository
project = Project(
    name="my-project",
    path=Path("/home/user/my-project"),
    url="https://github.com/user/my-project"  # Triggers save_repo_info
)

# After analysis, commit is saved
# get_repo_info("my-project") now returns:
# {
#     "repo_url": "https://github.com/user/my-project",
#     "commit": "abc1234def5678"
# }

# Retrieve metadata
info = get_repo_info("my-project")
print(f"Project URL: {info['repo_url']}")
print(f"Last indexed: {info['commit']}")
```

--------------------------------

### Get Repository Info

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/endpoints.md

Retrieve statistics and metadata for a specified repository and branch. Use this to get an overview of your code graph's size and analysis status.

```bash
curl -X POST http://localhost:5000/api/repo_info \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-project"}'
```

--------------------------------

### Analyze Local Project with Python

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

Use this Python snippet to initialize a project, analyze its sources while ignoring specified directories, and retrieve basic statistics.

```python
from api.project import Project
from pathlib import Path

project = Project(
    name="my-project",
    path=Path("/home/user/my-project"),
    url="https://github.com/user/my-project"
)
graph = project.analyze_sources(ignore=[".git", "node_modules"])
stats = graph.stats()
print(f"Nodes: {stats['node_count']}, Edges: {stats['edge_count']}")
```

--------------------------------

### Handle Missing FalkorDB Lite Dependency

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Demonstrates how to catch and handle a RuntimeError when FalkorDB Lite is used without its optional dependency installed. Provides guidance on installing the necessary package.

```python
from api.db import create_falkordb

try:
    db = create_falkordb()  # CODE_GRAPH_DB_BACKEND=lite
except RuntimeError as e:
    print(e)
    # RuntimeError: CODE_GRAPH_DB_BACKEND=lite requires the optional
    # `falkordblite` dependency. Install with
    # `uv sync --extra light` or `pip install 'falkordb-code-graph[light]'`.
```

--------------------------------

### Run Development Commands with Make

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

A suite of Make commands for managing dependencies, building the frontend, running the application in development or production modes, testing, linting, and cleaning artifacts.

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

--------------------------------

### AbstractAnalyzer.resolve Example Usage

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-analyzers.md

Example demonstrating how to use the `resolve` method to find where a specific symbol, like 'my_function', is defined within the analyzed codebase. It iterates through the returned definitions and prints their file paths.

```python
# Resolve where "my_function" is defined
definitions = analyzer.resolve(files, lsp, Path("main.py"), root, symbol_node)
for def_file, def_node in definitions:
    print(f"Defined in {def_file.path}")
```

--------------------------------

### Run Tests and Linting with Make

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Execute the test suite with `make test` and run linters with `make lint`. Specific linting commands are available for Python (`make lint-py`) and frontend (`make lint-fe`).

```bash
make test            # Run pytest suite
make lint            # Ruff + TypeScript type-check
make lint-py         # Ruff only
make lint-fe         # TypeScript type-check only
```

--------------------------------

### Get Repository Commit Hash

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-utilities.md

Retrieves the recorded commit hash for a repository. Use this function to get the commit hash that was last saved for a specific repository and branch. It returns None if no commit has been recorded yet, which may indicate the graph was not yet analyzed or created before a migration.

```python
from api.info import get_repo_commit

commit = get_repo_commit("my-project", branch="main")
if commit:
    print(f"Last indexed at commit: {commit}")
```

--------------------------------

### Success Response JSON

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/cli-reference.md

Example of a successful JSON response from the Code Graph CLI.

```json
{
  "status": "ok",
  "...": "command-specific data"
}
```

--------------------------------

### Get Neighboring Nodes

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Finds nodes that are directly connected to the specified nodes in the graph.

```APIDOC
## POST /api/get_neighbors

### Description
Neighboring nodes

### Method
POST

### Endpoint
/api/get_neighbors
```

--------------------------------

### Get Neighbors of Nodes

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

Retrieves the neighboring nodes for a given set of nodes within the graph.

```APIDOC
## POST /api/get_neighbors

### Description
Get neighbors of nodes.

### Method
POST

### Endpoint
/api/get_neighbors
```

--------------------------------

### Get Neighbors

Source: https://github.com/falkordb/code-graph/blob/staging/AGENTS.md

Retrieves neighboring nodes for a given set of nodes. This is a mutating operation that requires authentication.

```APIDOC
## POST /api/get_neighbors

### Description
Neighboring nodes.

### Method
POST

### Endpoint
/api/get_neighbors
```

--------------------------------

### AsyncGraphQuery.prefix_search

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-graph.md

Asynchronously performs a prefix search to find nodes whose names start with a given prefix.

```APIDOC
## AsyncGraphQuery.prefix_search

### Description
Async version of Graph.prefix_search.

### Method
`async def prefix_search(self, prefix: str, limit: int = 10) -> list`

### Parameters
#### Query Parameters
- **prefix** (str) - Required - The prefix to search for.
- **limit** (int) - Optional - The maximum number of results to return. Defaults to 10.

### Returns
- list - List of encoded node dicts.
```

--------------------------------

### Configure FalkorDB Server Backend

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

Set environment variables to use FalkorDB Server as the database backend. Requires a running FalkorDB instance. Suitable for production environments.

```bash
export CODE_GRAPH_DB_BACKEND=falkordb
export FALKORDB_HOST=localhost
export FALKORDB_PORT=6379
```

--------------------------------

### GET /*

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/endpoints.md

Serves the React SPA (Single Page Application) built frontend. This endpoint handles requests for static files like CSS, JS, and images. If a requested path does not exist or is a directory, it defaults to serving index.html. If index.html is also not found, a 404 error is returned.

```APIDOC
## GET /*

### Description
Serves the React SPA (Single Page Application) built frontend.

### Behavior:

- If `{path}` is a static file (CSS, JS, images), returns the file
- If `{path}` does not exist or is a directory, returns `index.html`
- If `index.html` does not exist, returns 404

### Request Example:
```bash
curl http://localhost:5000/
curl http://localhost:5000/assets/main.js
```
```

--------------------------------

### AsyncGraphQuery.__init__

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-graph.md

Initializes an async graph query context. Accepts bare project names or pre-composed graph names.

```APIDOC
## AsyncGraphQuery.__init__

### Description
Initializes an async graph query context. Accepts bare project names or pre-composed graph names.

### Method
`AsyncGraphQuery.__init__(name: str, branch: Optional[str] = None)`

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the project or graph.
- **branch** (Optional[str]) - Optional - The specific branch to query. Defaults to None.

### Example
```python
from api.graph import AsyncGraphQuery

async def query_graph():
    g = AsyncGraphQuery("my-project", branch="main")
    try:
        subgraph = await g.get_sub_graph(500)
        return subgraph
    finally:
        await g.close()
```
```

--------------------------------

### Get Neighboring Nodes

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Returns the neighboring nodes for a given set of node IDs within the code graph.

```APIDOC
## POST /api/get_neighbors

### Description
Return neighboring nodes for the provided IDs.

### Method
POST

### Endpoint
/api/get_neighbors
```

--------------------------------

### Retrieve Repository Information

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-utilities.md

Use this function to get repository metadata. It returns `None` if the repository information is not found.

```python
info = get_repo_info("my-project")
# Returns None if not found
```

--------------------------------

### Get repository statistics

Source: https://github.com/falkordb/code-graph/blob/staging/skills/code-graph/references/querying.md

Use 'cgraph info' with the '--repo' flag to retrieve statistics for a specific repository.

```bash
cgraph info --repo my-project
```

--------------------------------

### Development (FalkorDBLite)

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/configuration.md

Configuration for local development using FalkorDB Lite, suitable for testing without a full FalkorDB instance.

```bash
CODE_GRAPH_DB_BACKEND=lite
FALKORDB_LITE_PATH=~/.cache/code-graph/falkordblite.rdb
CODE_GRAPH_PUBLIC=1
MODEL_NAME=gemini/gemini-flash-lite-latest
GEMINI_API_KEY=your-key
HOST=127.0.0.1
PORT=5000
```

--------------------------------

### Error Response JSON

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/cli-reference.md

Example of an error JSON response from the Code Graph CLI, including a status and error message.

```json
{
  "status": "error",
  "message": "Error description"
}
```

--------------------------------

### Project Constructor

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-project.md

Initializes a Project instance, representing a software project with source analysis and git history processing capabilities. It can automatically detect the current git branch if not explicitly provided.

```APIDOC
## Project.__init__

### Description
Initializes a Project instance. Automatically detects the current branch using `git rev-parse --abbrev-ref HEAD` if not provided. Creates or opens the associated Graph.

### Parameters
#### Path Parameters
- **name** (str) - Required - Project/repository name
- **path** (Path) - Required - Local filesystem path to the project
- **url** (str) - Optional - Remote repository URL (for metadata tracking)
- **branch** (str) - Optional - Git branch name (auto-detected if omitted)

### Returns
None

### Example
```python
from api.project import Project
from pathlib import Path

project = Project(
    name="my-project",
    path=Path("/home/user/my-project"),
    url="https://github.com/user/my-project",
    branch="main"
)
```
```

--------------------------------

### Configure FalkorDB Lite Backend

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/README.md

Set environment variables to use FalkorDB Lite for an embedded, zero-setup database. Ideal for development and testing.

```bash
export CODE_GRAPH_DB_BACKEND=lite
export FALKORDB_LITE_PATH=~/.cache/code-graph/falkordblite.rdb
```

--------------------------------

### RuntimeError Example for FalkorDBLite

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Illustrates the RuntimeError when FalkorDBLite is used without setting FALKORDB_LITE_PORT, which is required for GraphRAG host/port access.

```text
RuntimeError: GraphRAG requires host/port access. When using 
CODE_GRAPH_DB_BACKEND=lite, set FALKORDB_LITE_PORT to expose 
the embedded FalkorDBLite instance on localhost.
```

--------------------------------

### Get Class Node by Name

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-graph.md

Find a Class node by its name. This method returns the first matching class found.

```python
cls = graph.get_class_by_name("MyClass")
if cls:
    print(f"Found class: {cls.id}")
```

--------------------------------

### Async Get Redis Connection

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-utilities.md

Creates an async Redis connection for non-blocking metadata operations. Use this for asynchronous tasks.

```python
async def async_get_redis_connection() -> redis.asyncio.Redis
```

--------------------------------

### Build Frontend Production Artifacts

Source: https://github.com/falkordb/code-graph/blob/staging/CLAUDE.md

Create a production build of the frontend application using npm. This command optimizes assets for deployment.

```bash
npm --prefix ./app run build        # Production build
```

--------------------------------

### Create Project from Git Repository

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-project.md

Clones a git repository and creates a Project instance. Validates the URL and extracts the project name. Clones to a default local directory.

```python
project = Project.from_git_repository(
    url="https://github.com/user/my-project",
    branch="main"
)
# Clones to ./repositories/my-project
```

--------------------------------

### Development (Local FalkorDB)

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/configuration.md

Use these environment variables for local development with a FalkorDB instance.

```bash
CODE_GRAPH_DB_BACKEND=falkordb
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
CODE_GRAPH_PUBLIC=0
SECRET_TOKEN=dev-token
MODEL_NAME=gemini/gemini-flash-lite-latest
GEMINI_API_KEY=your-key
HOST=127.0.0.1
PORT=5000
```

--------------------------------

### CLI Usage: Querying and Information

Source: https://github.com/falkordb/code-graph/blob/staging/README.md

Commands for listing indexed repositories, searching for entities, exploring relationships, finding paths, and viewing repository statistics.

```bash
cgraph list
```

```bash
cgraph search parse_config
```

```bash
cgraph neighbors 42 --rel CALLS
```

```bash
cgraph paths 42 99
```

```bash
cgraph info
```

--------------------------------

### Select FalkorDB Backend

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/configuration.md

Choose the database backend for Code Graph. Use 'falkordb' for a standard server, or 'lite'/'falkordblite' for an embedded in-process database.

```bash
CODE_GRAPH_DB_BACKEND=lite
```

--------------------------------

### Synchronous Graph Operations

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/INDEX.md

Demonstrates how to perform synchronous graph operations using the Python SDK, such as getting neighbors and finding paths.

```APIDOC
## Synchronous Graph Operations

This section details how to use the `Graph` class for synchronous operations.

### Usage

```python
from api.graph import Graph

g = Graph("my-project", branch="main")
neighbors = g.get_neighbors([42])
paths = g.find_paths(src=42, dest=99)
g.connect_entities("CALLS", src_id=42, dest_id=50)
```

### Methods

- `Graph(project_name, branch)`: Initializes a graph instance.
- `get_neighbors(node_ids)`: Retrieves neighbors for the given node IDs.
- `find_paths(src, dest)`: Finds paths between source and destination nodes.
- `connect_entities(relationship, src_id, dest_id)`: Connects two entities with a specified relationship.
```

--------------------------------

### Index a Local Project with cgraph

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/cli-reference.md

Ensures the database is ready and then indexes a local project directory. Ignores specified directories like `.git` and `node_modules`. Finally, displays project information.

```bash
cgraph ensure-db
cgraph index /path/to/project \
  --branch main \
  --ignore .git \
  --ignore node_modules
cgraph info
```

--------------------------------

### Get GraphRAG Connection Arguments

Source: https://github.com/falkordb/code-graph/blob/staging/_autodocs/api-reference-db.md

Returns host/port arguments for GraphRAG SDK constructors. Requires FALKORDB_LITE_PORT to be set when using FalkorDBLite.

```python
from api.db import graphrag_connection_kwargs
from graphrag_sdk import KnowledgeGraph

kwargs = graphrag_connection_kwargs()
kg = KnowledgeGraph(**kwargs)
```