github.com/FalkorDB/FalkorDB (link)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

FalkorDB-rs is a Rust implementation of FalkorDB, a graph database that runs as a Redis module. It implements the Cypher query language using GraphBLAS sparse matrices for efficient graph storage and traversal.

## Reference implementation and performance bar

The C implementation is the reference. It lives on the `master` branch of this
same repository; the easiest way t

---
name: fuzz
description: Run and manage FalkorDB's cargo-fuzz pipeline for the query runtime (fuzz_target_runtime) - build the fuzz target, run/minimize the corpus, generate coverage, and reproduce a crash artifact. Use when asked to fuzz test the runtime, investigate a fuzzing crash/artifact, or update the fuzz corpus.
allowed-tools: Bash
---

# Fuzz

The fuzz target lives in `fuzz/` (crate `graph-fuzz`, binary
`fuzz_target_runtime`, fuzzing `graph`'s query runtime). `fuzz.sh` runs the
full local sequen

---
name: lint
description: Run FalkorDB's stricter opt-in Clippy pass (pedantic/nursery/cargo lints) beyond the basic CI gate, optionally auto-fixing. Use when asked for a deep/strict lint pass or to auto-fix clippy warnings; for the standard fmt+clippy CI gate use the build skill.
allowed-tools: Bash
---

# Lint (advanced)

The `build` skill runs the CI gate (`cargo fmt --all -- --check` +
`CXX=clang++ cargo clippy --all-targets`). This skill is the stricter,
opt-in pass: pedantic + nursery + cargo lints,

---
name: test
description: Run FalkorDB's test suites - Rust unit tests, Python e2e/function/MVCC/concurrency tests, openCypher TCK compliance tests, and flow tests. Use when asked to run, narrow down, or debug a failing test, or to decide which suite covers a change.
allowed-tools: Bash
---

# Test

All Python suites require the virtualenv. Locally it's `./venv` (create once
with `python3 -m venv venv && pip install -r tests/requirements.txt`); inside
the devcontainer/CI it lives at `/data/venv`. The acti

---
name: coverage
description: Measure FalkorDB code coverage with LLVM source-based instrumentation across Rust unit tests, Python e2e/MVCC/concurrency tests, flow tests, and TCK - producing an lcov report. Use when asked to measure/report test coverage or reproduce the CI coverage job locally.
allowed-tools: Bash
---

# Coverage

LLVM source-based coverage (`-C instrument-coverage`) over the same suites CI
runs. `llvm-profdata`/`llvm-cov` must match the LLVM that built the binary —
the devcontainer shi

---
name: profile
description: Profile FalkorDB performance - generate samply flamegraphs and run the benchmark suite. Use when investigating a performance regression/bottleneck or comparing benchmark results. For code-coverage reports use the coverage skill.
allowed-tools: Bash
---

# Profile

## 1. Flamegraphs with samply

For finding performance bottlenecks in query execution (full reference:
`docs/profiling.md`):

```bash
cargo install samply                              # one-time
# [profile.release] h

---
name: build
description: Build FalkorDB (Rust code plus its native GraphBLAS/RediSearch dependencies), and run formatting/lint checks. Use when asked to build or compile the project, set up native dependencies for the first time, fix a build/compile/lint error, or run cargo fmt/clippy.
allowed-tools: Bash
---

# Build

FalkorDB-rs is a Redis module: the Rust crates link against two native C
libraries (GraphBLAS and RediSearch) that must be compiled and installed
*before* `cargo build` will succeed.

## 

---
name: debug
description: Debug FalkorDB crashes, hangs, panics, and incorrect query results - attach lldb/gdb to redis-server with the module loaded, understand panic/crash behavior, step through query execution, and triage failing CI runs. Use when investigating a crash, hang, wrong query result, or a red CI job.
allowed-tools: Bash
---

# Debug

## 1. Attach a debugger to the module

Build a debug binary first (`cargo build`), then launch `redis-server` with
the module loaded under a debugger (mirrors

# Bench loop

Repeatable per-query performance + regression + coverage loop. The harness is a
uv project under `bench/` — see `bench/README.md` for details.

## Full loop (run in this order)

```bash
# 0. once: install the harness's dependencies
uv sync --project bench

# 1. build the release module
cargo build --release

# 2. measure all 317 queries -> bench/results/current.csv (~2 min)
uv run --project bench bench measure

# 3. regression gate vs your baseline; exits 1 on a breach
uv run --project bench