CodeGraph - Knowledge Graph Visualization Tool

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

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

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

uv run ./start.sh 

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

cgraph gen-spec queries the knowledge graph for a named capability (class, file, or API route), assembles a structured context packet from docstrings, call edges, auth decorators and filesystem operations, then calls a configurable OpenAI-compatible LLM to draft an OpenSpec spec.md.

# Basic usage — prints the draft spec to stdout
cgraph gen-spec SourceAnalyzer

# Write the spec to a file
cgraph gen-spec SourceAnalyzer -o openspec/specs/source-analyzer/spec.md

# Inspect the assembled context without calling the LLM
cgraph gen-spec SourceAnalyzer --dry-run

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 12 first-class tools across two groups:

Structural tools (navigate and understand code structure): index_repo, search_code, find_symbol, get_neighbors, get_file_neighbors, impact_analysis, find_path

Security tools (discover and fix vulnerabilities): security_scan, get_template_vars, get_decorators, get_fs_ops, mark_vulnerability

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.

All security findings include SourceFile and SourceLine so the agent can call read_file directly without a separate find_symbol round-trip. Every tainted file-system op and CVE caller result includes a caller_symbol_id / CallerSymbolId ready for impact_analysis.

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:

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

Repositories containing an openspec/ directory (with an openspec/specs/ subdirectory) are automatically recognized and indexed by the OpenSpecAnalyzer. The analyzer extracts the full structured specification tree into the graph:

OpenSpecRequirement and OpenSpecScenario carry the :Searchable multi-label so they appear in auto-complete and GraphRAG chat without any extra configuration.

See docs/OPENSPEC_SCHEMA.md for the full node property and relationship reference.

When a repository is indexed, code-graph automatically extracts security-relevant entities across Python, HTML/Jinja2, and Markdown files and stores them as first-class graph nodes alongside the regular code structure.

Run the four built-in security rules against any indexed repo:

curl -X POST http://localhost:5000/api/security_scan \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-flask-app", "rules": ["xss", "auth_drift", "path_traversal"]}'

Available rules:

Response format:

{
  "repo": "my-flask-app",
  "findings": [
    {
      "rule": "xss",
      "name": "XSS: Unsanitized Template Variables",
      "severity": "high",
      "results": [
        {"UnsafeVariable": "user_comment", "TargetElement": "div", "SourceFile": "app/views.py", "SourceLine": 42}
      ]
    }
  ]
}

You can also run the queries directly against FalkorDB. The graph name for a repo my-app on branch main is code:my-app:main.

-- XSS: find template variables not passed through a sanitizer
MATCH (v:Variable)-[:INJECTED_INTO]->(e:HtmlElement)
WHERE NOT EXISTS {
    MATCH (v)-[:PROCESSED_BY]->(:Function)
}
RETURN v.name AS UnsafeVariable, e.name AS TargetElement,
       v.path AS SourceFile, v.src_line AS SourceLine

-- Auth-drift: routes documented in Markdown but missing @login_required
MATCH (m:MarkdownSection)-[:DEFINES_ROUTE]->(r:Route)
OPTIONAL MATCH (f:Function {route: r.path})
WHERE f IS NULL OR NOT (f)-[:HAS_DECORATOR]->(:Decorator {name: 'login_required'})
RETURN m.title AS DocumentedSection, r.path AS UnsecuredRoute

-- Path-traversal: tainted file-system operations
MATCH (fs:FileSystemOp)
WHERE fs.tainted = true
OPTIONAL MATCH (caller:Function)-[:HAS_FS_OP]->(fs)
RETURN fs.op AS Operation, fs.src_file, fs.src_line, caller.name AS CallerFunction

-- CVE blast-radius: who calls into a vulnerable package?
MATCH (f:Function)-[:CALLS]->(ef:ExternalFunction)-[:BELONGS_TO]->(p:Package {name: 'requests'})
RETURN f.name AS CallerFunction, f.path AS CallerFile,
       ef.name AS VulnerableFunction, ef.module AS Module

See docs/SECURITY_ENTITY_TRACKING.md for the full reference, including all node/edge schemas and the architectural overview.

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

Copyright FalkorDB Ltd. 2025