# CLAUDE.md - Project Context for Claude Code ## Project Overview **code-review-graph** is a persistent, incrementally updated, local-first knowledge graph for token-efficient code review through MCP and the CLI. It parses codebases using Tree-sitter and targeted fallbacks, builds a structural graph in SQLite, and exposes compact context to AI coding tools including Claude Code, Codex, Cursor, Windsurf, Zed, Continue, OpenCode, Gemini CLI, Qwen, Kiro, Qoder, and GitHub Copilot. ## Graph Tool Usage (Token-Efficient) When using code-review-graph MCP tools, follow these rules: 1. First call: `get_minimal_context(task="")` — costs ~100 tokens, gives you the full picture. 2. All subsequent calls: use `detail_level="minimal"` unless you need more. 3. Prefer `query_graph_tool` with a specific target over broad `list_*` calls. 4. The `next_tool_suggestions` field in every response tells you the optimal next step. 5. Target: ≤5 tool calls per task, ≤800 total tokens of graph context. ## Architecture - **Core Package**: `code_review_graph/` (Python 3.10+) - `parser.py` — Tree-sitter multi-language AST parser plus targeted fallbacks for broad source-language and notebook support - `custom_languages.py` — Config-driven custom language support (`.code-review-graph/languages.toml`, see docs/CUSTOM_LANGUAGES.md) - `graph.py` — SQLite-backed graph store (nodes, edges, weighted-score impact analysis) - `tools/` — 30 MCP tool implementations split by domain - `main.py` — FastMCP server entry point, registers 30 tools + 5 prompts - `incremental.py` — Git-based change detection, file watching - `embeddings.py` — Optional vector embeddings (local sentence-transformers, OpenAI-compatible endpoints, Google Gemini, MiniMax) - `visualization.py` — D3.js interactive HTML graph generator - `cli.py` — CLI entry point (install/init, build, update, postprocess, embed, watch, status, visualize, serve/mcp, wiki, detect-changes, register, unregister, repos, eval, daemon) - `flows.py` — Execution flow detection and criticality scoring - `communities.py` — Community detection (Leiden algorithm or file-based grouping) and architecture overview - `search.py` — FTS5 hybrid search (keyword + vector) - `changes.py` — Risk-scored change impact analysis (detect-changes) - `refactor.py` — Rename preview, dead code detection, refactoring suggestions - `hints.py` — Review hint generation - `prompts.py` — 5 MCP prompt templates (review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check) - `wiki.py` — Markdown wiki generation from community structure - `skills.py` — Multi-platform install/config generation and shipped skill metadata - `registry.py` — Multi-repo registry helpers - `migrations.py` — Database schema migrations (v1-v9) - `tsconfig_resolver.py` — TypeScript path alias resolution - **VS Code Extension**: `code-review-graph-vscode/` (TypeScript) - Separate subproject with its own `package.json`, `tsconfig.json` - Reads from `.code-review-graph/graph.db` via SQLite - **Database**: `.code-review-graph/graph.db` (SQLite, WAL mode) ## Key Commands ```bash # Development uv run pytest tests/ --tb=short -q # Run tests uv run ruff check code_review_graph/ # Lint uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional # Build & test uv run code-review-graph build # Full graph build uv run code-review-graph update # Incremental update uv run code-review-graph status # Show stats uv run code-review-graph serve # Start MCP server uv run code-review-graph wiki # Generate markdown wiki uv run code-review-graph detect-changes # Risk-scored change analysis uv run code-review-graph register # Register repo in multi-repo registry uv run code-review-graph repos # List registered repos uv run code-review-graph eval # Run evaluation benchmarks ``` ## Code Conventions - **Line length**: 100 chars (ruff) - **Python target**: 3.10+ - **SQL**: Always use parameterized queries (`?` placeholders), never f-string values - **Error handling**: Catch specific exceptions, log with `logger.warning/error` - **Thread safety**: `threading.Lock` for shared caches, `check_same_thread=False` for SQLite - **Node names**: Always sanitize via `_sanitize_name()` before returning to MCP clients - **File reads**: Read bytes once, hash, then parse (TOCTOU-safe pattern) ## Security Invariants - No `eval()`, `exec()`, `pickle`, or `yaml.unsafe_load()` - No `shell=True` in subprocess calls - `_validate_repo_root()` prevents path traversal via repo_root parameter - `_sanitize_name()` strips control characters, caps at 256 chars (prompt injection defense) - `escH()` in visualization escapes HTML entities including quotes and backticks - SRI hash on D3.js CDN script tag - API keys only from environment variables, never hardcoded ## Test Structure - `tests/test_parser.py` — Parser correctness, cross-file resolution - `tests/test_graph.py` — Graph CRUD, stats, impact radius - `tests/test_tools.py` — MCP tool integration tests - `tests/test_visualization.py` — Export, HTML generation, C++ resolution - `tests/test_incremental.py` — Build, update, migration, git ops - `tests/test_multilang.py` — Broad language parsing tests, including SFCs, notebooks, SQL, Perl XS, and modern systems/web languages - `tests/test_custom_languages.py` — Config-driven custom languages (languages.toml loader + end-to-end Erlang parse) - `tests/test_embeddings.py` — Vector encode/decode, similarity, store - `tests/test_flows.py` — Execution flow detection and criticality - `tests/test_communities.py` — Community detection, architecture overview - `tests/test_changes.py` — Risk-scored change analysis - `tests/test_refactor.py` — Rename preview, dead code, suggestions - `tests/test_search.py` — FTS5 hybrid search - `tests/test_hints.py` — Review hint generation - `tests/test_prompts.py` — MCP prompt template tests - `tests/test_wiki.py` — Wiki generation - `tests/test_context_savings.py` — Estimated context-savings metadata - `tests/test_skills.py` — Install/config generation and shipped skill metadata - `tests/test_registry.py` — Multi-repo registry - `tests/test_migrations.py` — Database migrations - `tests/test_eval.py` — Evaluation framework - `tests/test_tsconfig_resolver.py` — TypeScript path resolution - `tests/test_integration_v2.py` — v2 pipeline integration test - `tests/test_action_render.py` — GitHub Action PR comment renderer (`scripts/render_pr_comment.py`) - `tests/fixtures/` — Sample files for each supported language ## CI Pipeline - **lint**: ruff on Python 3.10 - **type-check**: mypy - **security**: bandit scan - **test**: pytest matrix (3.10, 3.11, 3.12, 3.13) with 65% coverage minimum ## Beads Issue Tracker This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. ### Quick Reference ```bash bd ready # Find available work bd show # View issue details bd update --claim # Claim work bd close # Complete work ``` ### Rules - Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists - Run `bd prime` for detailed command reference and session close protocol - Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files ## Session Completion **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. **MANDATORY WORKFLOW:** 1. **File issues for remaining work** - Create issues for anything that needs follow-up 2. **Run quality gates** (if code changed) - Tests, linters, builds 3. **Update issue status** - Close finished work, update in-progress items 4. **PUSH TO REMOTE** - This is MANDATORY: ```bash git pull --rebase bd dolt push git push git status # MUST show "up to date with origin" ``` 5. **Clean up** - Clear stashes, prune remote branches 6. **Verify** - All changes committed AND pushed 7. **Hand off** - Provide context for next session **CRITICAL RULES:** - Work is NOT complete until `git push` succeeds - NEVER stop before pushing - that leaves work stranded locally - NEVER say "ready to push when you are" - YOU must push - If push fails, resolve and retry until it succeeds ## MCP Tools: code-review-graph **IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase.** The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot. ### When to use graph tools FIRST - **Exploring code**: `semantic_search_nodes_tool` or `query_graph_tool` instead of Grep - **Understanding impact**: `get_impact_radius_tool` instead of manually tracing imports - **Code review**: `detect_changes_tool` + `get_review_context_tool` instead of reading entire files - **Finding relationships**: `query_graph_tool` with callers_of/callees_of/imports_of/tests_for - **Architecture questions**: `get_architecture_overview_tool` + `list_communities_tool` Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need. ### Key Tools | Tool | Use when | |------|----------| | `detect_changes_tool` | Reviewing code changes — gives risk-scored analysis | | `get_review_context_tool` | Need source snippets for review — token-efficient | | `get_impact_radius_tool` | Understanding blast radius of a change | | `get_affected_flows_tool` | Finding which execution paths are impacted | | `query_graph_tool` | Tracing callers, callees, imports, tests, dependencies | | `semantic_search_nodes_tool` | Finding functions/classes by name or keyword | | `get_architecture_overview_tool` | Understanding high-level codebase structure | | `refactor_tool` | Planning renames, finding dead code | ### Workflow 1. The graph auto-updates on file changes (via hooks). 2. Use `detect_changes_tool` for code review. 3. Use `get_affected_flows_tool` to understand impact. 4. Use `query_graph_tool` pattern="tests_for" to check coverage.