CLAUDE.md

1# CLAUDE.md - Project Context for Claude Code
2 
3## Project Overview
4 
5**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.
6 
7## Graph Tool Usage (Token-Efficient)
8When using code-review-graph MCP tools, follow these rules:
91. First call: `get_minimal_context(task="<description>")` — costs ~100 tokens, gives you the full picture.
102. All subsequent calls: use `detail_level="minimal"` unless you need more.
113. Prefer `query_graph_tool` with a specific target over broad `list_*` calls.
124. The `next_tool_suggestions` field in every response tells you the optimal next step.
135. Target: ≤5 tool calls per task, ≤800 total tokens of graph context.
14 
15## Architecture
16 
17- **Core Package**: `code_review_graph/` (Python 3.10+)
18  - `parser.py` — Tree-sitter multi-language AST parser plus targeted fallbacks for broad source-language and notebook support
19  - `custom_languages.py` — Config-driven custom language support (`.code-review-graph/languages.toml`, see docs/CUSTOM_LANGUAGES.md)
20  - `graph.py` — SQLite-backed graph store (nodes, edges, weighted-score impact analysis)
21  - `tools/` — 30 MCP tool implementations split by domain
22  - `main.py` — FastMCP server entry point, registers 30 tools + 5 prompts
23  - `incremental.py` — Git-based change detection, file watching
24  - `embeddings.py` — Optional vector embeddings (local sentence-transformers, OpenAI-compatible endpoints, Google Gemini, MiniMax)
25  - `visualization.py` — D3.js interactive HTML graph generator
26  - `cli.py` — CLI entry point (install/init, build, update, postprocess, embed, watch, status, visualize, serve/mcp, wiki, detect-changes, register, unregister, repos, eval, daemon)
27  - `flows.py` — Execution flow detection and criticality scoring
28  - `communities.py` — Community detection (Leiden algorithm or file-based grouping) and architecture overview
29  - `search.py` — FTS5 hybrid search (keyword + vector)
30  - `changes.py` — Risk-scored change impact analysis (detect-changes)
31  - `refactor.py` — Rename preview, dead code detection, refactoring suggestions
32  - `hints.py` — Review hint generation
33  - `prompts.py` — 5 MCP prompt templates (review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check)
34  - `wiki.py` — Markdown wiki generation from community structure
35  - `skills.py` — Multi-platform install/config generation and shipped skill metadata
36  - `registry.py` — Multi-repo registry helpers
37  - `migrations.py` — Database schema migrations (v1-v9)
38  - `tsconfig_resolver.py` — TypeScript path alias resolution
39 
40- **VS Code Extension**: `code-review-graph-vscode/` (TypeScript)
41  - Separate subproject with its own `package.json`, `tsconfig.json`
42  - Reads from `.code-review-graph/graph.db` via SQLite
43 
44- **Database**: `.code-review-graph/graph.db` (SQLite, WAL mode)
45 
46## Key Commands
47 
48```bash
49# Development
50uv run pytest tests/ --tb=short -q          # Run tests
51uv run ruff check code_review_graph/        # Lint
52uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
53 
54# Build & test
55uv run code-review-graph build              # Full graph build
56uv run code-review-graph update             # Incremental update
57uv run code-review-graph status             # Show stats
58uv run code-review-graph serve              # Start MCP server
59uv run code-review-graph wiki               # Generate markdown wiki
60uv run code-review-graph detect-changes     # Risk-scored change analysis
61uv run code-review-graph register &lt;path&gt;    # Register repo in multi-repo registry
62uv run code-review-graph repos              # List registered repos
63uv run code-review-graph eval               # Run evaluation benchmarks
64```
65 
66## Code Conventions
67 
68- **Line length**: 100 chars (ruff)
69- **Python target**: 3.10+
70- **SQL**: Always use parameterized queries (`?` placeholders), never f-string values
71- **Error handling**: Catch specific exceptions, log with `logger.warning/error`
72- **Thread safety**: `threading.Lock` for shared caches, `check_same_thread=False` for SQLite
73- **Node names**: Always sanitize via `_sanitize_name()` before returning to MCP clients
74- **File reads**: Read bytes once, hash, then parse (TOCTOU-safe pattern)
75 
76## Security Invariants
77 
78- No `eval()`, `exec()`, `pickle`, or `yaml.unsafe_load()`
79- No `shell=True` in subprocess calls
80- `_validate_repo_root()` prevents path traversal via repo_root parameter
81- `_sanitize_name()` strips control characters, caps at 256 chars (prompt injection defense)
82- `escH()` in visualization escapes HTML entities including quotes and backticks
83- SRI hash on D3.js CDN script tag
84- API keys only from environment variables, never hardcoded
85 
86## Test Structure
87 
88- `tests/test_parser.py` — Parser correctness, cross-file resolution
89- `tests/test_graph.py` — Graph CRUD, stats, impact radius
90- `tests/test_tools.py` — MCP tool integration tests
91- `tests/test_visualization.py` — Export, HTML generation, C++ resolution
92- `tests/test_incremental.py` — Build, update, migration, git ops
93- `tests/test_multilang.py` — Broad language parsing tests, including SFCs, notebooks, SQL, Perl XS, and modern systems/web languages
94- `tests/test_custom_languages.py` — Config-driven custom languages (languages.toml loader + end-to-end Erlang parse)
95- `tests/test_embeddings.py` — Vector encode/decode, similarity, store
96- `tests/test_flows.py` — Execution flow detection and criticality
97- `tests/test_communities.py` — Community detection, architecture overview
98- `tests/test_changes.py` — Risk-scored change analysis
99- `tests/test_refactor.py` — Rename preview, dead code, suggestions
100- `tests/test_search.py` — FTS5 hybrid search
101- `tests/test_hints.py` — Review hint generation
102- `tests/test_prompts.py` — MCP prompt template tests
103- `tests/test_wiki.py` — Wiki generation
104- `tests/test_context_savings.py` — Estimated context-savings metadata
105- `tests/test_skills.py` — Install/config generation and shipped skill metadata
106- `tests/test_registry.py` — Multi-repo registry
107- `tests/test_migrations.py` — Database migrations
108- `tests/test_eval.py` — Evaluation framework
109- `tests/test_tsconfig_resolver.py` — TypeScript path resolution
110- `tests/test_integration_v2.py` — v2 pipeline integration test
111- `tests/test_action_render.py` — GitHub Action PR comment renderer (`scripts/render_pr_comment.py`)
112- `tests/fixtures/` — Sample files for each supported language
113 
114## CI Pipeline
115 
116- **lint**: ruff on Python 3.10
117- **type-check**: mypy
118- **security**: bandit scan
119- **test**: pytest matrix (3.10, 3.11, 3.12, 3.13) with 65% coverage minimum
120 
121 
122<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
123## Beads Issue Tracker
124 
125This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
126 
127### Quick Reference
128 
129```bash
130bd ready              # Find available work
131bd show &lt;id&gt;          # View issue details
132bd update &lt;id&gt; --claim  # Claim work
133bd close &lt;id&gt;         # Complete work
134```
135 
136### Rules
137 
138- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
139- Run `bd prime` for detailed command reference and session close protocol
140- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
141 
142## Session Completion
143 
144**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
145 
146**MANDATORY WORKFLOW:**
147 
1481. **File issues for remaining work** - Create issues for anything that needs follow-up
1492. **Run quality gates** (if code changed) - Tests, linters, builds
1503. **Update issue status** - Close finished work, update in-progress items
1514. **PUSH TO REMOTE** - This is MANDATORY:
152```bash
153   git pull --rebase
154   bd dolt push
155   git push
156   git status  # MUST show "up to date with origin"
157```
1585. **Clean up** - Clear stashes, prune remote branches
1596. **Verify** - All changes committed AND pushed
1607. **Hand off** - Provide context for next session
161 
162**CRITICAL RULES:**
163- Work is NOT complete until `git push` succeeds
164- NEVER stop before pushing - that leaves work stranded locally
165- NEVER say "ready to push when you are" - YOU must push
166- If push fails, resolve and retry until it succeeds
167<!-- END BEADS INTEGRATION -->
168 
169<!-- code-review-graph MCP tools -->
170## MCP Tools: code-review-graph
171 
172**IMPORTANT: This project has a knowledge graph. ALWAYS use the
173code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
174the codebase.** The graph is faster, cheaper (fewer tokens), and gives
175you structural context (callers, dependents, test coverage) that file
176scanning cannot.
177 
178### When to use graph tools FIRST
179 
180- **Exploring code**: `semantic_search_nodes_tool` or `query_graph_tool` instead of Grep
181- **Understanding impact**: `get_impact_radius_tool` instead of manually tracing imports
182- **Code review**: `detect_changes_tool` + `get_review_context_tool` instead of reading entire files
183- **Finding relationships**: `query_graph_tool` with callers_of/callees_of/imports_of/tests_for
184- **Architecture questions**: `get_architecture_overview_tool` + `list_communities_tool`
185 
186Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
187 
188### Key Tools
189 
190| Tool | Use when |
191|------|----------|
192| `detect_changes_tool` | Reviewing code changes — gives risk-scored analysis |
193| `get_review_context_tool` | Need source snippets for review — token-efficient |
194| `get_impact_radius_tool` | Understanding blast radius of a change |
195| `get_affected_flows_tool` | Finding which execution paths are impacted |
196| `query_graph_tool` | Tracing callers, callees, imports, tests, dependencies |
197| `semantic_search_nodes_tool` | Finding functions/classes by name or keyword |
198| `get_architecture_overview_tool` | Understanding high-level codebase structure |
199| `refactor_tool` | Planning renames, finding dead code |
200 
201### Workflow
202 
2031. The graph auto-updates on file changes (via hooks).
2042. Use `detect_changes_tool` for code review.
2053. Use `get_affected_flows_tool` to understand impact.
2064. Use `query_graph_tool` pattern="tests_for" to check coverage.
207