tirth8205/code-review-graph

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/tirth8205/code-review-graph.svg?style=card)](https://bestofgithub.dev/repo/tirth8205/code-review-graph)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/tirth8205/code-review-graph.svg)](https://bestofgithub.dev/repo/tirth8205/code-review-graph)

Loading README…

Repo	Snapshot SHA	naive_corpus_tokens	avg graph_tokens	Reduction
fastapi	`22381558`	948,793	2,653	357.6x
flask	`a29f88ce`	143,594	2,196	65.4x
code-review-graph	`84bde354`	208,821	3,190	65.5x
gin	`5c00df8a`	166,868	2,766	60.3x
httpx	`b55d4635`	142,356	2,661	53.5x
express	`b4ab7d65`	136,052	3,936	34.6x

Repo	Commits	Avg F1	Avg Precision	Recall (graph-derived upper bound)
httpx	2	0.863	0.785	1.0
code-review-graph	2	0.734	0.584	1.0
fastapi	2	0.697	0.539	1.0
express	2	0.667	0.500	1.0
flask	2	0.633	0.485	1.0
gin	3	0.609	0.439	1.0
Average	13	0.693	0.546	1.000

Repo	Nodes	Edges	Embeddings
fastapi	6,287	32,036	5,159
express	1,990	19,492	1,849
gin	1,589	17,237	1,491
code-review-graph	1,446	9,094	1,354
flask	1,415	8,259	1,329
httpx	1,263	8,236	1,193

Feature	Details
Incremental updates	Re-parses only files whose hash changed. On a ~3,000-file repo a two-file edit takes ~2.5 s on the hook path (measured).
Language and notebook support	See Language coverage above.
Framework-aware PHP parsing	Repository-bounded Composer PSR-4 imports, Blade template references, evidence-gated Laravel Route-to-controller and Eloquent relationship edges
Framework-aware Java parsing	Spring dependency-injection call resolution, request endpoints and WebFlux routes, scheduled triggers, application-event publisher-to-listener edges, Temporal workflow and activity edges, and Spring Boot config keys indexed without their values
Blast-radius analysis	Which functions, classes and files are likely affected by a change
Auto-update hooks	Editor hooks, a git pre-commit hook and watch mode update the graph as you work
Semantic search	Optional vector embeddings via sentence-transformers, Google Gemini, MiniMax, Voyage AI, or any OpenAI-compatible endpoint (OpenAI, Azure, new-api, LiteLLM, vLLM, LocalAI)
Interactive visualisation	D3.js force-directed graph with search, community legend toggles and degree-scaled nodes
Hub and bridge detection	Most-connected nodes and chokepoints (betweenness centrality)
Surprise scoring	Unexpected coupling: cross-community, cross-language, peripheral-to-hub edges
Knowledge gap analysis	Isolated nodes, untested hotspots, thin communities
Suggested questions	Review questions generated from bridges, hubs and surprises
Edge confidence	Two-tier confidence (EXTRACTED/INFERRED) with float scores on edges
Graph traversal	BFS/DFS from any node with configurable depth and token budget
Export formats	GraphML (Gephi/yEd), Neo4j Cypher, Obsidian vault, JSON, and SVG (SVG needs matplotlib from the `eval` extra)
Token benchmarking	`code_review_graph/token_benchmark.py` measures whole-corpus tokens against graph query tokens per question
Estimated context savings	`context_savings` metadata (`estimated`, `saved_tokens`, `saved_percent`) on review, impact, detect-changes and architecture responses
Community auto-split	Communities above 25% of the graph are split recursively with Leiden
Execution flows	Call chains from entry points, sorted by weighted criticality
Community detection	Leiden clustering with resolution scaled to graph size
Architecture overview	Community-based architecture map with coupling warnings
Risk-scored reviews	`detect_changes` maps diffs to affected functions, flows and test gaps
Custom languages	New languages via `.code-review-graph/languages.toml`, no fork needed
GitHub Action	Sticky risk-scored PR review comments in CI, with an optional `fail-on-risk` merge gate
Refactoring tools	Rename preview, framework-aware dead code detection, community-driven suggestions
Wiki generation	Markdown wiki from community structure
Multi-repo registry	Register several repos and search across them
Multi-repo daemon	`crg-daemon` watches several repos as child processes, with health checks and restart
MCP prompts	5 workflow templates: review, architecture, debug, onboard, pre-merge
Full-text search	FTS5 hybrid search combining keyword and vector similarity
Local storage	One SQLite file in `.code-review-graph/`; no external database or cloud service

Skill	Description
`explore-codebase`	Navigate and understand codebase structure using the knowledge graph
`review-changes`	Perform a structured code review using change detection and impact
`debug-issue`	Systematically debug issues using graph-powered code navigation
`refactor-safely`	Plan and execute safe refactoring using dependency analysis

tirth8205/code-review-graph

code-review-graph

Quick Start

How It Works

Blast-radius analysis

Incremental updates

Whole codebase or targeted answer?

Language coverage and notebooks

Add your own language

Risk-scored PR reviews in CI (GitHub Action)

Benchmarks

Limitations

Features

Usage

Environment Variables

Tool Filtering

FAQ and comparisons

Troubleshooting

`pip` / `pipx` cannot download `hatchling` (or `Errno 9` / `Bad file descriptor` to PyPI)

Windows: `Invalid JSON: EOF while parsing` or `MCP error -32000: Connection closed`

Contributing

Licence

Command	What it does	When to use
`detect-changes --brief`	Read-only. Queries the existing graph for the current changes and prints the panel.	Most of the time; hooks or `crg-daemon` keep the graph fresh.
`update --brief`	Re-parses the changed files into the graph first, then prints the same panel.	After a rebase, a large change set, or whenever the graph may be stale.

Tool	Description
`build_or_update_graph_tool`	Build or incrementally update the graph
`run_postprocess_tool`	Re-run flow detection, community detection and FTS indexing
`get_minimal_context_tool`	Compact context (~100 tokens); call this first
`get_impact_radius_tool`	Blast radius of changed files
`get_review_context_tool`	Review context with structural summary
`query_graph_tool`	Callers, callees, tests, imports, inheritance queries
`traverse_graph_tool`	BFS/DFS traversal from any node with a token budget
`semantic_search_nodes_tool`	Search code entities by name or meaning
`embed_graph_tool`	Compute vector embeddings for semantic search
`list_graph_stats_tool`	Graph size and health
`get_docs_section_tool`	Retrieve documentation sections
`find_large_functions_tool`	Functions, classes or files above a line-count threshold
`list_flows_tool`	Execution flows sorted by criticality
`get_flow_tool`	One execution flow
`get_affected_flows_tool`	Flows affected by changed files
`list_communities_tool`	Detected code communities
`get_community_tool`	One community
`get_architecture_overview_tool`	Architecture overview from community structure
`detect_changes_tool`	Risk-scored change impact analysis
`get_hub_nodes_tool`	Most-connected nodes
`get_bridge_nodes_tool`	Chokepoints by betweenness centrality
`get_knowledge_gaps_tool`	Structural weaknesses and untested hotspots
`get_surprising_connections_tool`	Unexpected cross-community coupling
`get_suggested_questions_tool`	Review questions generated from the analysis
`refactor_tool`	Rename preview, dead code detection, suggestions
`apply_refactor_tool`	Apply a previously previewed refactoring
`generate_wiki_tool`	Markdown wiki from communities
`get_wiki_page_tool`	One wiki page
`list_repos_tool`	Registered repositories
`cross_repo_search_tool`	Search registered repositories; `repos` limits the search to a subset

Variable	Description	Default
`CRG_GIT_TIMEOUT`	Timeout in seconds for Git operations (build, update, watch)	`30`
`CRG_DISCOVERY_TIMEOUT`	Timeout in seconds for each Git command that discovers what changed, when a review tool or command was not given an explicit file list. Running out reports an error, never "no changes"	`5`, or `CRG_GIT_TIMEOUT` when you set that explicitly
`CRG_DATA_DIR`	Directory for graph databases and generated artefacts	-
`CRG_HOOK_WORKTREES`	Set to `1` to let the pre-commit hook run in linked git worktrees	-
`CRG_EMBEDDING_MODEL`	Default model for local vector embeddings	`all-MiniLM-L6-v2`
`CRG_ACCEPT_CLOUD_EMBEDDINGS`	Set to `1` to suppress the cloud embedding egress warning	-
`CRG_ALLOW_REMOTE_CODE`	Allow HuggingFace models that require `trust_remote_code=True`	`0`
`CRG_MAX_IMPACT_NODES`	Maximum nodes in impact analysis	`500`
`CRG_MAX_IMPACT_DEPTH`	Search depth for blast-radius analysis	`2`
`CRG_MAX_BFS_DEPTH`	Maximum depth for graph traversal	`15`
`CRG_MAX_CHANGED_FUNCS`	Maximum changed functions analysed in one change report	`500`
`CRG_MAX_TRANSITIVE_FRONTIER`	Maximum frontier size for transitive caller/callee expansion	`50`
`CRG_CALLER_TEST_ROUTE_DEPTH`	Hops to walk up incoming `CALLS` when looking for a tested caller of an untested changed symbol. Reported as a note, never as coverage	`2`
`CRG_CALLER_TEST_ROUTE_MAX_CALLERS`	Maximum callers examined while looking for that tested caller	`500`
`CRG_TOOL_TIMEOUT`	Timeout in seconds for read-only MCP tools (`0` disables). Does not bound the tools that write: build, postprocess, embed, wiki and apply-refactor	`0`
`CRG_CHURN_WINDOW_DAYS`	Window for `detect-changes --churn` commit counts	`90`
`CRG_LEIDEN_SEED`	Seed for Leiden community detection	`42`
`CRG_RECURSE_SUBMODULES`	Include git submodules when set to `1`, `true` or `yes`	-
`CRG_TOOLS`	Comma-separated allowlist of MCP tools to expose when serving	-
`GOOGLE_API_KEY`	API key for Google Gemini embeddings	-
`MINIMAX_API_KEY`	API key for MiniMax embeddings	-
`VOYAGE_API_KEY`	API key for Voyage embeddings	-
`CRG_VOYAGE_MODEL`	Model for Voyage embeddings	`voyage-code-3`
`CRG_VOYAGE_OUTPUT_DIMENSION`	Output dimension for Voyage embeddings	`1024`
`CRG_VOYAGE_OUTPUT_DTYPE`	Output dtype for Voyage embeddings	`float`
`CRG_VOYAGE_BASE_URL`	Voyage embeddings endpoint	`https://api.voyageai.com/v1`
`CRG_VOYAGE_BATCH_SIZE`	Batch size for Voyage requests	`100`
`CRG_VOYAGE_MIN_INTERVAL_SEC`	Minimum delay between Voyage requests	`0`
`CRG_OPENAI_BASE_URL`	OpenAI-compatible embeddings endpoint	-
`CRG_OPENAI_API_KEY`	API key for OpenAI-compatible embeddings	-
`CRG_OPENAI_MODEL`	Model for OpenAI-compatible embeddings	-
`CRG_OPENAI_DIMENSION`	Pin the embedding dimension (v3 models support reduction)	-
`CRG_OPENAI_BATCH_SIZE`	Batch size for OpenAI-compatible requests	`100`
`NO_COLOR`	Disable ANSI colours in the terminal	-
`CRG_SERIAL_PARSE`	Set to `1` to disable parallel parsing (for debugging)	-

code-review-graph

Quick Start

How It Works

Blast-radius analysis

Incremental updates

Whole codebase or targeted answer?

Language coverage and notebooks

Add your own language

Risk-scored PR reviews in CI (GitHub Action)

Benchmarks

Limitations

Features

Usage

Environment Variables

Tool Filtering

FAQ and comparisons

Troubleshooting

pip / pipx cannot download hatchling (or Errno 9 / Bad file descriptor to PyPI)

Windows: Invalid JSON: EOF while parsing or MCP error -32000: Connection closed

Contributing

Licence

`pip` / `pipx` cannot download `hatchling` (or `Errno 9` / `Bad file descriptor` to PyPI)

Windows: `Invalid JSON: EOF while parsing` or `MCP error -32000: Connection closed`