code-review-graph 1.7.0__tar.gz → 1.7.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/.claude-plugin/plugin.json +1 -1
  2. code_review_graph-1.7.2/PKG-INFO +204 -0
  3. code_review_graph-1.7.2/README.md +171 -0
  4. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/cli.py +10 -6
  5. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/graph.py +3 -1
  6. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/incremental.py +6 -0
  7. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/main.py +1 -1
  8. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/COMMANDS.md +7 -8
  9. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/FEATURES.md +12 -1
  10. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/LLM-OPTIMIZED-REFERENCE.md +4 -4
  11. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/ROADMAP.md +7 -7
  12. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/TROUBLESHOOTING.md +1 -1
  13. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/USAGE.md +5 -10
  14. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/architecture.md +1 -1
  15. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/pyproject.toml +1 -2
  16. code_review_graph-1.7.0/PKG-INFO +0 -266
  17. code_review_graph-1.7.0/README.md +0 -232
  18. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/.gitignore +0 -0
  19. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/LICENSE +0 -0
  20. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/__init__.py +0 -0
  21. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/__main__.py +0 -0
  22. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/embeddings.py +0 -0
  23. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/parser.py +0 -0
  24. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/tools.py +0 -0
  25. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/visualization.py +0 -0
  26. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/INDEX.md +0 -0
  27. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/LEGAL.md +0 -0
  28. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/assets/banner.jpg +0 -0
  29. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/schema.md +0 -0
  30. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/hooks/hooks.json +0 -0
  31. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/hooks/session-start.sh +0 -0
  32. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/skills/build-graph/SKILL.md +0 -0
  33. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/skills/review-delta/SKILL.md +0 -0
  34. {code_review_graph-1.7.0 → code_review_graph-1.7.2}/skills/review-pr/SKILL.md +0 -0
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/.claude-plugin/plugin.json RENAMED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "code-review-graph",
3
3
  "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
4
- "version": "1.7.0",
4
+ "version": "1.7.2",
5
5
  "author": {
6
6
  "name": "Tirth Kanani",
7
7
  "email": "tirthkanani18@gmail.com",
code_review_graph-1.7.2/PKG-INFO ADDED
@@ -0,0 +1,204 @@
1
+ Metadata-Version: 2.4
2
+ Name: code-review-graph
3
+ Version: 1.7.2
4
+ Summary: Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code
5
+ Author: Tirth
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: claude-code,code-review,knowledge-graph,mcp,tree-sitter
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Quality Assurance
18
+ Requires-Python: >=3.10
19
+ Requires-Dist: fastmcp>=0.1.0
20
+ Requires-Dist: mcp>=1.0.0
21
+ Requires-Dist: networkx>=3.2
22
+ Requires-Dist: tree-sitter-language-pack>=0.3.0
23
+ Requires-Dist: tree-sitter>=0.23.0
24
+ Requires-Dist: watchdog>=4.0.0
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
27
+ Requires-Dist: pytest>=8.0; extra == 'dev'
28
+ Requires-Dist: ruff>=0.3.0; extra == 'dev'
29
+ Provides-Extra: embeddings
30
+ Requires-Dist: numpy>=1.26; extra == 'embeddings'
31
+ Requires-Dist: sentence-transformers>=3.0.0; extra == 'embeddings'
32
+ Description-Content-Type: text/markdown
33
+
34
+ <p align="center">
35
+ <img src="docs/assets/banner.jpg" alt="code-review-graph" width="100%" />
36
+ </p>
37
+
38
+ <h1 align="center">code-review-graph</h1>
39
+
40
+ <p align="center">
41
+ <a href="https://github.com/tirth8205/code-review-graph/stargazers"><img src="https://img.shields.io/github/stars/tirth8205/code-review-graph?style=flat-square" alt="Stars"></a>
42
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT Licence"></a>
43
+ <a href="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml"><img src="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
44
+ <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python 3.10+"></a>
45
+ <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
46
+ <a href="#"><img src="https://img.shields.io/badge/version-1.7.2-purple.svg?style=flat-square" alt="v1.7.2"></a>
47
+ </p>
48
+
49
+ Claude Code re-reads your entire codebase on every task. `code-review-graph` fixes that. It builds a structural map of your code with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), tracks changes incrementally, and gives Claude precise context so it reads only what matters.
50
+
51
+ Benchmarked on three production open-source projects: **6.8x fewer tokens for code reviews, up to 49x fewer tokens for coding tasks.**
52
+
53
+ ## Installation
54
+
55
+ **Claude Code Plugin** (recommended)
56
+
57
+ ```bash
58
+ claude plugin add tirth8205/code-review-graph
59
+ ```
60
+
61
+ **pip**
62
+
63
+ ```bash
64
+ pip install code-review-graph
65
+ code-review-graph install
66
+ ```
67
+
68
+ Restart Claude Code after either method. Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
69
+
70
+ ## Getting Started
71
+
72
+ Open your project in Claude Code and run:
73
+
74
+ ```
75
+ Build the code review graph for this project
76
+ ```
77
+
78
+ The initial build takes roughly 10 seconds for a 500-file project. After that, the graph updates automatically on every file edit and git commit.
79
+
80
+ ## How It Works
81
+
82
+ The graph maps every function, class, import, call, inheritance relationship, and test in your codebase. When you ask Claude to review code or make changes, it queries the graph first to determine what changed and what depends on those changes, then reads only the relevant files along with their blast-radius information rather than scanning everything.
83
+
84
+ You continue using Claude Code exactly as before. The graph operates in the background, updating itself as you work.
85
+
86
+ ## Benchmarks
87
+
88
+ All figures come from real tests on three production open-source repositories.
89
+
90
+ ### Code Reviews: 6.8x Token Reduction
91
+
92
+ Tested across 6 real git commits. The graph replaces reading entire source files with a compact structural summary (156 to 207 tokens) covering blast radius, test coverage gaps, and dependency chains.
93
+
94
+ | Repo | Size | Standard Approach | With Graph | Reduction | Review Quality |
95
+ |------|-----:|------------------:|-----------:|----------:|:-:|
96
+ | [httpx](https://github.com/encode/httpx) | 125 files | 12,507 tokens | 458 tokens | 26.2x | 9.0 vs 7.0 |
97
+ | [FastAPI](https://github.com/fastapi/fastapi) | 2,915 files | 5,495 tokens | 871 tokens | 8.1x | 8.5 vs 7.5 |
98
+ | [Next.js](https://github.com/vercel/next.js) | 27,732 files | 21,614 tokens | 4,457 tokens | 6.0x | 9.0 vs 7.0 |
99
+ | **Average** | | **13,205** | **1,928** | **6.8x** | **8.8 vs 7.2** |
100
+
101
+ Standard approach: reading all changed files plus the diff. Quality scored on accuracy, completeness, bug-catching potential, and actionable insight (1 to 10 scale).
102
+
103
+ ### Live Coding Tasks: 14.1x Average, 49x Peak
104
+
105
+ An agent performed 6 real coding tasks (adding features, fixing bugs) across the same repositories. The graph directed it to the right files and away from everything else.
106
+
107
+ | Task | Repo | With Graph | Without Graph | Reduction | Files Skipped |
108
+ |------|------|--------:|-----------:|----------:|---:|
109
+ | Add rate limiter | httpx | 14,090 | 64,666 | 4.6x | 58 |
110
+ | Fix streaming bug | httpx | 14,090 | 64,666 | 4.6x | 59 |
111
+ | Add rate limiter | FastAPI | 37,217 | 138,585 | 3.7x | 1,120 |
112
+ | Fix streaming bug | FastAPI | 36,986 | 138,585 | 3.7x | 1,121 |
113
+ | Add rate limiter | Next.js | 15,049 | 739,352 | 49.1x | ~16,000 |
114
+ | Fix streaming bug | Next.js | 16,135 | 739,352 | 45.8x | ~16,000 |
115
+
116
+ The graph identified the correct files in every case. Savings scale with repository size: a 125-file project sees roughly 4.6x reduction, whilst a 27,000-file monorepo sees close to 49x.
117
+
118
+ ## Usage
119
+
120
+ ### Slash Commands
121
+
122
+ | Command | Description |
123
+ |---------|-------------|
124
+ | `/code-review-graph:build-graph` | Build or rebuild the code graph |
125
+ | `/code-review-graph:review-delta` | Review changes since last commit |
126
+ | `/code-review-graph:review-pr` | Full PR review with blast-radius analysis |
127
+
128
+ ### CLI
129
+
130
+ ```bash
131
+ code-review-graph install # Register MCP server with Claude Code
132
+ code-review-graph build # Parse entire codebase
133
+ code-review-graph update # Incremental update (changed files only)
134
+ code-review-graph status # Graph statistics
135
+ code-review-graph watch # Auto-update on file changes
136
+ code-review-graph visualize # Generate interactive HTML graph
137
+ code-review-graph serve # Start MCP server
138
+ ```
139
+
140
+ ### MCP Tools
141
+
142
+ Claude uses these automatically once the graph is built.
143
+
144
+ | Tool | Description |
145
+ |------|-------------|
146
+ | `build_or_update_graph_tool` | Build or incrementally update the graph |
147
+ | `get_impact_radius_tool` | Blast radius of changed files |
148
+ | `get_review_context_tool` | Token-optimised review context with structural summary |
149
+ | `query_graph_tool` | Callers, callees, tests, imports, inheritance queries |
150
+ | `semantic_search_nodes_tool` | Search code entities by name or meaning |
151
+ | `embed_graph_tool` | Compute vector embeddings for semantic search |
152
+ | `list_graph_stats_tool` | Graph size and health |
153
+ | `get_docs_section_tool` | Retrieve documentation sections |
154
+
155
+ ## Features
156
+
157
+ | Feature | Details |
158
+ |---------|---------|
159
+ | Incremental updates | Re-parses only changed files. Subsequent updates complete in under 2 seconds. |
160
+ | 12 languages | Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++ |
161
+ | Blast-radius analysis | Shows exactly which functions, classes, and files are affected by any change |
162
+ | Auto-update hooks | Graph updates on every file edit and git commit without manual intervention |
163
+ | Semantic search | Optional vector embeddings via sentence-transformers |
164
+ | Interactive visualisation | D3.js force-directed graph with edge-type toggles and search |
165
+ | Local storage | SQLite file in `.code-review-graph/`. No external database, no cloud dependency. |
166
+ | Watch mode | Continuous graph updates as you work |
167
+
168
+ ## Configuration
169
+
170
+ To exclude paths from indexing, create a `.code-review-graphignore` file in your repository root:
171
+
172
+ ```
173
+ generated/**
174
+ *.generated.ts
175
+ vendor/**
176
+ node_modules/**
177
+ ```
178
+
179
+ For semantic search, install the optional embeddings dependencies:
180
+
181
+ ```bash
182
+ pip install code-review-graph[embeddings]
183
+ ```
184
+
185
+ ## Contributing
186
+
187
+ ```bash
188
+ git clone https://github.com/tirth8205/code-review-graph.git
189
+ cd code-review-graph
190
+ python3 -m venv .venv && source .venv/bin/activate
191
+ pip install -e ".[dev]"
192
+ pytest
193
+ ```
194
+
195
+ To add a new language, edit `code_review_graph/parser.py` and add your extension to `EXTENSION_TO_LANGUAGE` along with node type mappings in `_CLASS_TYPES`, `_FUNCTION_TYPES`, `_IMPORT_TYPES`, and `_CALL_TYPES`. Include a test fixture and open a PR.
196
+
197
+ ## Licence
198
+
199
+ MIT. See [LICENSE](LICENSE).
200
+
201
+ <p align="center">
202
+ <br>
203
+ <code>pip install code-review-graph && code-review-graph install</code>
204
+ </p>
code_review_graph-1.7.2/README.md ADDED
@@ -0,0 +1,171 @@
1
+ <p align="center">
2
+ <img src="docs/assets/banner.jpg" alt="code-review-graph" width="100%" />
3
+ </p>
4
+
5
+ <h1 align="center">code-review-graph</h1>
6
+
7
+ <p align="center">
8
+ <a href="https://github.com/tirth8205/code-review-graph/stargazers"><img src="https://img.shields.io/github/stars/tirth8205/code-review-graph?style=flat-square" alt="Stars"></a>
9
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT Licence"></a>
10
+ <a href="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml"><img src="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
+ <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python 3.10+"></a>
12
+ <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
13
+ <a href="#"><img src="https://img.shields.io/badge/version-1.7.2-purple.svg?style=flat-square" alt="v1.7.2"></a>
14
+ </p>
15
+
16
+ Claude Code re-reads your entire codebase on every task. `code-review-graph` fixes that. It builds a structural map of your code with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), tracks changes incrementally, and gives Claude precise context so it reads only what matters.
17
+
18
+ Benchmarked on three production open-source projects: **6.8x fewer tokens for code reviews, up to 49x fewer tokens for coding tasks.**
19
+
20
+ ## Installation
21
+
22
+ **Claude Code Plugin** (recommended)
23
+
24
+ ```bash
25
+ claude plugin add tirth8205/code-review-graph
26
+ ```
27
+
28
+ **pip**
29
+
30
+ ```bash
31
+ pip install code-review-graph
32
+ code-review-graph install
33
+ ```
34
+
35
+ Restart Claude Code after either method. Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
36
+
37
+ ## Getting Started
38
+
39
+ Open your project in Claude Code and run:
40
+
41
+ ```
42
+ Build the code review graph for this project
43
+ ```
44
+
45
+ The initial build takes roughly 10 seconds for a 500-file project. After that, the graph updates automatically on every file edit and git commit.
46
+
47
+ ## How It Works
48
+
49
+ The graph maps every function, class, import, call, inheritance relationship, and test in your codebase. When you ask Claude to review code or make changes, it queries the graph first to determine what changed and what depends on those changes, then reads only the relevant files along with their blast-radius information rather than scanning everything.
50
+
51
+ You continue using Claude Code exactly as before. The graph operates in the background, updating itself as you work.
52
+
53
+ ## Benchmarks
54
+
55
+ All figures come from real tests on three production open-source repositories.
56
+
57
+ ### Code Reviews: 6.8x Token Reduction
58
+
59
+ Tested across 6 real git commits. The graph replaces reading entire source files with a compact structural summary (156 to 207 tokens) covering blast radius, test coverage gaps, and dependency chains.
60
+
61
+ | Repo | Size | Standard Approach | With Graph | Reduction | Review Quality |
62
+ |------|-----:|------------------:|-----------:|----------:|:-:|
63
+ | [httpx](https://github.com/encode/httpx) | 125 files | 12,507 tokens | 458 tokens | 26.2x | 9.0 vs 7.0 |
64
+ | [FastAPI](https://github.com/fastapi/fastapi) | 2,915 files | 5,495 tokens | 871 tokens | 8.1x | 8.5 vs 7.5 |
65
+ | [Next.js](https://github.com/vercel/next.js) | 27,732 files | 21,614 tokens | 4,457 tokens | 6.0x | 9.0 vs 7.0 |
66
+ | **Average** | | **13,205** | **1,928** | **6.8x** | **8.8 vs 7.2** |
67
+
68
+ Standard approach: reading all changed files plus the diff. Quality scored on accuracy, completeness, bug-catching potential, and actionable insight (1 to 10 scale).
69
+
70
+ ### Live Coding Tasks: 14.1x Average, 49x Peak
71
+
72
+ An agent performed 6 real coding tasks (adding features, fixing bugs) across the same repositories. The graph directed it to the right files and away from everything else.
73
+
74
+ | Task | Repo | With Graph | Without Graph | Reduction | Files Skipped |
75
+ |------|------|--------:|-----------:|----------:|---:|
76
+ | Add rate limiter | httpx | 14,090 | 64,666 | 4.6x | 58 |
77
+ | Fix streaming bug | httpx | 14,090 | 64,666 | 4.6x | 59 |
78
+ | Add rate limiter | FastAPI | 37,217 | 138,585 | 3.7x | 1,120 |
79
+ | Fix streaming bug | FastAPI | 36,986 | 138,585 | 3.7x | 1,121 |
80
+ | Add rate limiter | Next.js | 15,049 | 739,352 | 49.1x | ~16,000 |
81
+ | Fix streaming bug | Next.js | 16,135 | 739,352 | 45.8x | ~16,000 |
82
+
83
+ The graph identified the correct files in every case. Savings scale with repository size: a 125-file project sees roughly 4.6x reduction, whilst a 27,000-file monorepo sees close to 49x.
84
+
85
+ ## Usage
86
+
87
+ ### Slash Commands
88
+
89
+ | Command | Description |
90
+ |---------|-------------|
91
+ | `/code-review-graph:build-graph` | Build or rebuild the code graph |
92
+ | `/code-review-graph:review-delta` | Review changes since last commit |
93
+ | `/code-review-graph:review-pr` | Full PR review with blast-radius analysis |
94
+
95
+ ### CLI
96
+
97
+ ```bash
98
+ code-review-graph install # Register MCP server with Claude Code
99
+ code-review-graph build # Parse entire codebase
100
+ code-review-graph update # Incremental update (changed files only)
101
+ code-review-graph status # Graph statistics
102
+ code-review-graph watch # Auto-update on file changes
103
+ code-review-graph visualize # Generate interactive HTML graph
104
+ code-review-graph serve # Start MCP server
105
+ ```
106
+
107
+ ### MCP Tools
108
+
109
+ Claude uses these automatically once the graph is built.
110
+
111
+ | Tool | Description |
112
+ |------|-------------|
113
+ | `build_or_update_graph_tool` | Build or incrementally update the graph |
114
+ | `get_impact_radius_tool` | Blast radius of changed files |
115
+ | `get_review_context_tool` | Token-optimised review context with structural summary |
116
+ | `query_graph_tool` | Callers, callees, tests, imports, inheritance queries |
117
+ | `semantic_search_nodes_tool` | Search code entities by name or meaning |
118
+ | `embed_graph_tool` | Compute vector embeddings for semantic search |
119
+ | `list_graph_stats_tool` | Graph size and health |
120
+ | `get_docs_section_tool` | Retrieve documentation sections |
121
+
122
+ ## Features
123
+
124
+ | Feature | Details |
125
+ |---------|---------|
126
+ | Incremental updates | Re-parses only changed files. Subsequent updates complete in under 2 seconds. |
127
+ | 12 languages | Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++ |
128
+ | Blast-radius analysis | Shows exactly which functions, classes, and files are affected by any change |
129
+ | Auto-update hooks | Graph updates on every file edit and git commit without manual intervention |
130
+ | Semantic search | Optional vector embeddings via sentence-transformers |
131
+ | Interactive visualisation | D3.js force-directed graph with edge-type toggles and search |
132
+ | Local storage | SQLite file in `.code-review-graph/`. No external database, no cloud dependency. |
133
+ | Watch mode | Continuous graph updates as you work |
134
+
135
+ ## Configuration
136
+
137
+ To exclude paths from indexing, create a `.code-review-graphignore` file in your repository root:
138
+
139
+ ```
140
+ generated/**
141
+ *.generated.ts
142
+ vendor/**
143
+ node_modules/**
144
+ ```
145
+
146
+ For semantic search, install the optional embeddings dependencies:
147
+
148
+ ```bash
149
+ pip install code-review-graph[embeddings]
150
+ ```
151
+
152
+ ## Contributing
153
+
154
+ ```bash
155
+ git clone https://github.com/tirth8205/code-review-graph.git
156
+ cd code-review-graph
157
+ python3 -m venv .venv && source .venv/bin/activate
158
+ pip install -e ".[dev]"
159
+ pytest
160
+ ```
161
+
162
+ To add a new language, edit `code_review_graph/parser.py` and add your extension to `EXTENSION_TO_LANGUAGE` along with node type mappings in `_CLASS_TYPES`, `_FUNCTION_TYPES`, `_IMPORT_TYPES`, and `_CALL_TYPES`. Include a test fixture and open a PR.
163
+
164
+ ## Licence
165
+
166
+ MIT. See [LICENSE](LICENSE).
167
+
168
+ <p align="center">
169
+ <br>
170
+ <code>pip install code-review-graph && code-review-graph install</code>
171
+ </p>
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/cli.py RENAMED
@@ -20,9 +20,7 @@ if sys.version_info < (3, 10):
20
20
  print("code-review-graph requires Python 3.10 or higher.")
21
21
  print(f" You are running Python {sys.version}")
22
22
  print()
23
- print("Options:")
24
- print(" 1. Install Python 3.10+: https://www.python.org/downloads/")
25
- print(" 2. Use Docker: docker run -v $(pwd):/repo tirth8205/code-review-graph")
23
+ print("Install Python 3.10+: https://www.python.org/downloads/")
26
24
  sys.exit(1)
27
25
 
28
26
  import argparse
@@ -114,7 +112,7 @@ def _handle_init(args: argparse.Namespace) -> None:
114
112
  existing.setdefault("mcpServers", {}).update(mcp_config["mcpServers"])
115
113
  mcp_config = existing
116
114
  except (json.JSONDecodeError, KeyError):
117
- pass # Overwrite malformed file
115
+ print(f"Warning: existing {mcp_path} is malformed, overwriting.")
118
116
 
119
117
  if dry_run:
120
118
  print(f"[dry-run] Would write to {mcp_path}:")
@@ -147,13 +145,19 @@ def main() -> None:
147
145
  "install", help="Register MCP server with Claude Code (creates .mcp.json)"
148
146
  )
149
147
  install_cmd.add_argument("--repo", default=None, help="Repository root (auto-detected)")
150
- install_cmd.add_argument("--dry-run", action="store_true", help="Show what would be done without writing files")
148
+ install_cmd.add_argument(
149
+ "--dry-run", action="store_true",
150
+ help="Show what would be done without writing files",
151
+ )
151
152
 
152
153
  init_cmd = sub.add_parser(
153
154
  "init", help="Alias for install"
154
155
  )
155
156
  init_cmd.add_argument("--repo", default=None, help="Repository root (auto-detected)")
156
- init_cmd.add_argument("--dry-run", action="store_true", help="Show what would be done without writing files")
157
+ init_cmd.add_argument(
158
+ "--dry-run", action="store_true",
159
+ help="Show what would be done without writing files",
160
+ )
157
161
 
158
162
  # build
159
163
  build_cmd = sub.add_parser("build", help="Full graph build (re-parse all files)")
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/graph.py RENAMED
@@ -119,7 +119,9 @@ class GraphStore:
119
119
  def __init__(self, db_path: str | Path) -> None:
120
120
  self.db_path = Path(db_path)
121
121
  self.db_path.parent.mkdir(parents=True, exist_ok=True)
122
- self._conn = sqlite3.connect(str(self.db_path), timeout=30)
122
+ self._conn = sqlite3.connect(
123
+ str(self.db_path), timeout=30, check_same_thread=False
124
+ )
123
125
  self._conn.row_factory = sqlite3.Row
124
126
  self._conn.execute("PRAGMA journal_mode=WAL")
125
127
  self._conn.execute("PRAGMA busy_timeout=5000")
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/incremental.py RENAMED
@@ -250,6 +250,12 @@ def full_build(repo_root: Path, store: GraphStore) -> dict:
250
250
  parser = CodeParser()
251
251
  files = collect_all_files(repo_root)
252
252
 
253
+ # Purge stale data from files no longer on disk
254
+ existing_files = set(store.get_all_files())
255
+ current_abs = {str(repo_root / f) for f in files}
256
+ for stale in existing_files - current_abs:
257
+ store.remove_file_data(stale)
258
+
253
259
  total_nodes = 0
254
260
  total_edges = 0
255
261
  errors = []
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/code_review_graph/main.py RENAMED
@@ -1,6 +1,6 @@
1
1
  """MCP server entry point for Code Review Graph.
2
2
 
3
- Run as: python -m server.main
3
+ Run as: code-review-graph serve
4
4
  Communicates via stdio (standard MCP transport).
5
5
  """
6
6
 
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/COMMANDS.md RENAMED
@@ -81,11 +81,16 @@ section_name: str # usage, review-delta, review-pr, commands, legal, watch, e
81
81
  ## CLI Commands
82
82
 
83
83
  ```bash
84
+ # Register MCP server with Claude Code
85
+ code-review-graph install # also available as: code-review-graph init
86
+ code-review-graph install --dry-run # preview without writing files
87
+
84
88
  # Full build
85
- code-review-graph build --full
89
+ code-review-graph build
86
90
 
87
91
  # Incremental update
88
92
  code-review-graph update
93
+ code-review-graph update --base origin/main # custom base ref
89
94
 
90
95
  # Check status
91
96
  code-review-graph status
@@ -93,13 +98,7 @@ code-review-graph status
93
98
  # Watch mode
94
99
  code-review-graph watch
95
100
 
96
- # Custom base ref
97
- code-review-graph update --base origin/main
98
-
99
- # Set up Claude Code integration
100
- code-review-graph init
101
-
102
- # Generate graph visualization
101
+ # Generate graph visualisation
103
102
  code-review-graph visualize
104
103
 
105
104
  # Start MCP server
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/FEATURES.md RENAMED
@@ -1,6 +1,17 @@
1
1
  # Features
2
2
 
3
- ## v1.6.4 (Current)
3
+ ## v1.7.2 (Current)
4
+ - **Watch mode thread safety**: SQLite connections compatible with Python 3.10/3.11 watchdog threads.
5
+ - **Full rebuild cleanup**: Purges stale data from deleted files during full rebuild.
6
+ - **Dependency trim**: Removed unused `gitpython` dependency.
7
+
8
+ ## v1.7.0
9
+ - **`install` command**: New primary entry point for setup (`code-review-graph install`). `init` remains as an alias.
10
+ - **`--dry-run` flag**: Preview what `install`/`init` would write without modifying files.
11
+ - **PyPI auto-publish**: GitHub releases now automatically publish to PyPI.
12
+ - **README rewrite**: Professional documentation with real benchmark data from httpx, FastAPI, and Next.js.
13
+
14
+ ## v1.6.4
4
15
  - **Portable MCP config**: `init` now generates `uvx`-based `.mcp.json` — no absolute paths, works on any machine with `uv` installed
5
16
  - **Removed symlink workaround**: The `_safe_path` helper for spaces-in-paths is no longer needed with `uvx`
6
17
 
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/LLM-OPTIMIZED-REFERENCE.md RENAMED
@@ -1,11 +1,11 @@
1
- # LLM-OPTIMIZED REFERENCE — code-review-graph v1.6.4
1
+ # LLM-OPTIMIZED REFERENCE — code-review-graph v1.7.2
2
2
 
3
3
  Claude Code: Read ONLY the exact `<section>` you need. Never load the whole file.
4
4
 
5
5
  <section name="usage">
6
6
  Quick install: pip install code-review-graph
7
- Then: code-review-graph init && code-review-graph build
8
- First run: /code-review-graph:build-graph --full
7
+ Then: code-review-graph install && code-review-graph build
8
+ First run: /code-review-graph:build-graph
9
9
  After that use only delta/pr commands.
10
10
  </section>
11
11
 
@@ -24,7 +24,7 @@ Never include full files unless explicitly asked.
24
24
  <section name="commands">
25
25
  MCP tools: build_or_update_graph_tool, get_impact_radius_tool, query_graph_tool, get_review_context_tool, semantic_search_nodes_tool, embed_graph_tool, list_graph_stats_tool, get_docs_section_tool
26
26
  Skills: build-graph, review-delta, review-pr
27
- CLI: code-review-graph [init|build|update|status|watch|visualize|serve]
27
+ CLI: code-review-graph [install|init|build|update|status|watch|visualize|serve]
28
28
  </section>
29
29
 
30
30
  <section name="legal">
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/ROADMAP.md RENAMED
@@ -2,6 +2,12 @@
2
2
 
3
3
  ## Shipped
4
4
 
5
+ ### v1.7.0
6
+ - `install` command as primary entry point (`init` kept as alias)
7
+ - `--dry-run` flag for previewing install/init changes
8
+ - Automatic PyPI publishing via GitHub Actions on release
9
+ - README rewrite with real benchmark data from httpx, FastAPI, and Next.js
10
+
5
11
  ### v1.6.4
6
12
  - Portable `uvx`-based MCP config — no absolute paths, works on any machine with `uv`
7
13
  - Removed `_safe_path` symlink workaround (superseded by `uvx`)
@@ -47,13 +53,7 @@
47
53
  ### v1.1.0
48
54
  - Watch mode, vector embeddings, 12+ languages verified
49
55
 
50
- ## v1.6 (Planned)
51
- - Auto-generated Mermaid diagrams in review output
52
- - Public API change detection (breaking change warnings)
53
- - Configurable review depth per-project
54
- - Graph diff visualization (before/after a PR)
55
-
56
- ## v2.0 (Future)
56
+ ## v2.0 (Planned)
57
57
  - Surgical edit suggestions (auto-fix common patterns)
58
58
  - GitHub PR bot integration
59
59
  - Team sync (shared graph via git-tracked DB)
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/TROUBLESHOOTING.md RENAMED
@@ -35,4 +35,4 @@ The graph uses SQLite with WAL mode. If you see lock errors:
35
35
  - Verify `uv` is installed (`uv --version`; install with `pip install uv` or `brew install uv`)
36
36
  - Check that `uvx code-review-graph serve` runs without errors
37
37
  - If using a custom `.mcp.json`, ensure it uses `"command": "uvx"` with `"args": ["code-review-graph", "serve"]`
38
- - Re-run `code-review-graph init` to regenerate the config
38
+ - Re-run `code-review-graph install` to regenerate the config
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/USAGE.md RENAMED
@@ -1,22 +1,17 @@
1
1
  # Code Review Graph — User Guide
2
2
 
3
- **Version:** v1.6.4 (Mar 6, 2026)
3
+ **Version:** v1.7.2 (Mar 9, 2026)
4
4
 
5
- ## Quick Installation (30 seconds)
5
+ ## Installation
6
6
 
7
7
  ```bash
8
8
  pip install code-review-graph
9
- code-review-graph init # creates .mcp.json automatically
10
- code-review-graph build # parse your codebase
9
+ code-review-graph install # creates .mcp.json for Claude Code
10
+ code-review-graph build # parse your codebase
11
11
  ```
12
12
 
13
13
  Restart Claude Code to pick up the MCP server.
14
14
 
15
- Then build the graph once:
16
- ```
17
- /code-review-graph:build-graph
18
- ```
19
-
20
15
  ## Core Workflow
21
16
 
22
17
  ### 1. Build the graph (first time only)
@@ -52,7 +47,7 @@ Interactive D3.js force-directed graph. Starts collapsed (File nodes only) — c
52
47
 
53
48
  ### 6. Semantic search (optional)
54
49
  ```bash
55
- pip install -e ".[embeddings]"
50
+ pip install "code-review-graph[embeddings]"
56
51
  ```
57
52
  Then use `embed_graph_tool` to compute vectors. `semantic_search_nodes_tool` automatically uses vector similarity.
58
53
 
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/docs/architecture.md RENAMED
@@ -109,4 +109,4 @@ BFS from seed nodes (changed files' contents):
109
109
  3. Expand up to `max_depth` hops (default: 2)
110
110
  4. Collect all reached nodes as "impacted"
111
111
 
112
- This captures both downstream effects (things that call changed code) and upstream context (things that changed code depends on).
112
+ This captures both downstream effects (things that call changed code) and upstream context (things that the changed code depends on).
{code_review_graph-1.7.0 → code_review_graph-1.7.2}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "code-review-graph"
7
- version = "1.7.0"
7
+ version = "1.7.2"
8
8
  description = "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code"
9
9
  readme = {file = "README.md", content-type = "text/markdown"}
10
10
  license = "MIT"
@@ -29,7 +29,6 @@ dependencies = [
29
29
  "fastmcp>=0.1.0",
30
30
  "tree-sitter>=0.23.0",
31
31
  "tree-sitter-language-pack>=0.3.0",
32
- "gitpython>=3.1.0",
33
32
  "networkx>=3.2",
34
33
  "watchdog>=4.0.0",
35
34
  ]
code_review_graph-1.7.0/PKG-INFO DELETED
@@ -1,266 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: code-review-graph
3
- Version: 1.7.0
4
- Summary: Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code
5
- Author: Tirth
6
- License-Expression: MIT
7
- License-File: LICENSE
8
- Keywords: claude-code,code-review,knowledge-graph,mcp,tree-sitter
9
- Classifier: Development Status :: 4 - Beta
10
- Classifier: Intended Audience :: Developers
11
- Classifier: License :: OSI Approved :: MIT License
12
- Classifier: Programming Language :: Python :: 3
13
- Classifier: Programming Language :: Python :: 3.10
14
- Classifier: Programming Language :: Python :: 3.11
15
- Classifier: Programming Language :: Python :: 3.12
16
- Classifier: Programming Language :: Python :: 3.13
17
- Classifier: Topic :: Software Development :: Quality Assurance
18
- Requires-Python: >=3.10
19
- Requires-Dist: fastmcp>=0.1.0
20
- Requires-Dist: gitpython>=3.1.0
21
- Requires-Dist: mcp>=1.0.0
22
- Requires-Dist: networkx>=3.2
23
- Requires-Dist: tree-sitter-language-pack>=0.3.0
24
- Requires-Dist: tree-sitter>=0.23.0
25
- Requires-Dist: watchdog>=4.0.0
26
- Provides-Extra: dev
27
- Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
28
- Requires-Dist: pytest>=8.0; extra == 'dev'
29
- Requires-Dist: ruff>=0.3.0; extra == 'dev'
30
- Provides-Extra: embeddings
31
- Requires-Dist: numpy>=1.26; extra == 'embeddings'
32
- Requires-Dist: sentence-transformers>=3.0.0; extra == 'embeddings'
33
- Description-Content-Type: text/markdown
34
-
35
- <p align="center">
36
- <img src="docs/assets/banner.jpg" alt="code-review-graph" width="100%" />
37
- </p>
38
-
39
- <h1 align="center">code-review-graph</h1>
40
-
41
- <p align="center">
42
- <strong>Give Claude a map of your codebase so it stops reading every file.</strong>
43
- </p>
44
-
45
- <p align="center">
46
- <a href="https://github.com/tirth8205/code-review-graph/stargazers"><img src="https://img.shields.io/github/stars/tirth8205/code-review-graph?style=flat-square" alt="Stars"></a>
47
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License"></a>
48
- <a href="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml"><img src="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
49
- <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python 3.10+"></a>
50
- <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
51
- <a href="#"><img src="https://img.shields.io/badge/version-1.7.0-purple.svg?style=flat-square" alt="v1.7.0"></a>
52
- </p>
53
-
54
- ---
55
-
56
- Claude Code is powerful, but it wastes tokens re-reading your entire codebase on every review and every coding task. `code-review-graph` builds a structural map of your code using [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), tracks it incrementally, and tells Claude exactly which files matter — so it reads 5 files instead of 500.
57
-
58
- Benchmarked on real open-source repos: **6.8x fewer tokens for code reviews, up to 49x fewer tokens for coding tasks.**
59
-
60
- ---
61
-
62
- ## Install in 45 Seconds
63
-
64
- ### Option A: Claude Code Plugin (recommended)
65
-
66
- ```bash
67
- claude plugin add tirth8205/code-review-graph
68
- ```
69
-
70
- Restart Claude Code. Done.
71
-
72
- ### Option B: pip
73
-
74
- ```bash
75
- pip install git+https://github.com/tirth8205/code-review-graph.git
76
- code-review-graph install
77
- ```
78
-
79
- This creates a `.mcp.json` file in your project that tells Claude Code where to find the MCP server. Restart Claude Code to activate.
80
-
81
- > Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). Install uv with `pip install uv` or `brew install uv`.
82
-
83
- ---
84
-
85
- ## First Time in a Project
86
-
87
- After installing, open your project in Claude Code and say:
88
-
89
- ```
90
- Build the code review graph for this project
91
- ```
92
-
93
- That's it. Takes about 10 seconds for a 500-file project. After that, the graph updates automatically whenever you edit files or make commits — you never need to think about it again.
94
-
95
- ---
96
-
97
- ## How It Works (for Normal People)
98
-
99
- ```
100
- Your codebase has hundreds of files.
101
- Claude doesn't know which ones matter for what you're doing.
102
-
103
- Without this plugin:
104
- Claude reads everything → slow, expensive, shallow understanding
105
-
106
- With this plugin:
107
- 1. A graph maps every function, class, import, and dependency
108
- 2. When you ask Claude to review code or make changes,
109
- it checks the graph first: "What changed? What depends on it?"
110
- 3. Claude reads only those specific files
111
- 4. Result: faster, cheaper, and actually better reviews
112
- (because it sees the full blast radius, not just the diff)
113
- ```
114
-
115
- **You don't change how you work.** You still talk to Claude exactly the same way. It just has a map now, so it doesn't get lost.
116
-
117
- ---
118
-
119
- ## Benchmarks
120
-
121
- All numbers from real tests on 3 production open-source repos — not toy examples.
122
-
123
- ### Code Reviews: 6.8x Token Reduction
124
-
125
- Tested across 6 real git commits. The graph replaces reading entire files with a compact structural summary (156–207 tokens) that includes blast radius, test coverage gaps, and dependency chains.
126
-
127
- | Repo | Size | Standard Approach | With Graph | Savings | Review Quality |
128
- |------|-----:|------------------:|-----------:|--------:|:-:|
129
- | [httpx](https://github.com/encode/httpx) | 125 files | 12,507 tokens | 458 tokens | **26.2x** | 9.0 vs 7.0 |
130
- | [FastAPI](https://github.com/fastapi/fastapi) | 2,915 files | 5,495 tokens | 871 tokens | **8.1x** | 8.5 vs 7.5 |
131
- | [Next.js](https://github.com/vercel/next.js) | 27,732 files | 21,614 tokens | 4,457 tokens | **6.0x** | 9.0 vs 7.0 |
132
- | **Average** | | **13,205** | **1,928** | **6.8x** | **8.8 vs 7.2** |
133
-
134
- > "Standard approach" = reading all changed files + diff (what you'd do without the graph). Quality scored on accuracy, completeness, bug-catching, and actionable insight (1–10 scale).
135
-
136
- ### Live Coding Tasks: 14.1x Average, 49x Peak
137
-
138
- An AI agent performed 6 real coding tasks (adding features, fixing bugs) across the same repos. The graph told it which files to read and which to skip.
139
-
140
- | Task | Repo | With Graph | Without Graph | Savings | Files Skipped |
141
- |------|------|--------:|-----------:|--------:|---:|
142
- | Add rate limiter | httpx | 14,090 | 64,666 | 4.6x | 58 |
143
- | Fix streaming bug | httpx | 14,090 | 64,666 | 4.6x | 59 |
144
- | Add rate limiter | FastAPI | 37,217 | 138,585 | 3.7x | 1,120 |
145
- | Fix streaming bug | FastAPI | 36,986 | 138,585 | 3.7x | 1,121 |
146
- | Add rate limiter | Next.js | 15,049 | 739,352 | **49.1x** | ~16,000 |
147
- | Fix streaming bug | Next.js | 16,135 | 739,352 | **45.8x** | ~16,000 |
148
-
149
- The graph pointed to exactly the right files **100% of the time** — zero false leads across all tasks. The bigger your repo, the bigger the savings.
150
-
151
- ---
152
-
153
- ## Usage
154
-
155
- ### Slash Commands (inside Claude Code)
156
-
157
- | Command | What it does |
158
- |---------|-------------|
159
- | `/code-review-graph:build-graph` | Build or rebuild the code graph (~10s for 500 files) |
160
- | `/code-review-graph:review-delta` | Review only what changed since last commit |
161
- | `/code-review-graph:review-pr` | Full PR review with blast-radius analysis |
162
-
163
- ### CLI
164
-
165
- ```bash
166
- code-review-graph install # Register MCP server with Claude Code
167
- code-review-graph build # Parse your entire codebase
168
- code-review-graph update # Incremental update (only changed files)
169
- code-review-graph status # Show graph statistics
170
- code-review-graph watch # Real-time auto-updates as you code
171
- code-review-graph visualize # Interactive HTML graph visualization
172
- code-review-graph serve # Start MCP server manually
173
- ```
174
-
175
- ### MCP Tools (Claude uses these automatically)
176
-
177
- | Tool | What it does |
178
- |------|-------------|
179
- | `build_or_update_graph_tool` | Build or incrementally update the graph |
180
- | `get_impact_radius_tool` | Show blast radius of changed files |
181
- | `get_review_context_tool` | Token-optimized review context with structural summary |
182
- | `query_graph_tool` | Find callers, callees, tests, imports, inheritance |
183
- | `semantic_search_nodes_tool` | Search code entities by name or meaning |
184
- | `embed_graph_tool` | Compute vector embeddings for semantic search |
185
- | `list_graph_stats_tool` | Graph size and health check |
186
- | `get_docs_section_tool` | Retrieve docs sections with minimal tokens |
187
-
188
- ---
189
-
190
- ## Features
191
-
192
- | Feature | Details |
193
- |---------|---------|
194
- | **Incremental updates** | Only re-parses changed files. Updates take <2s after initial build. |
195
- | **12 languages** | Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++ |
196
- | **Blast-radius analysis** | See exactly which functions, classes, and files are impacted by any change |
197
- | **Auto-update hooks** | Graph stays current on every file edit and git commit — zero maintenance |
198
- | **Semantic search** | Optional vector embeddings with sentence-transformers |
199
- | **Interactive visualization** | D3.js graph with edge-type toggles and search |
200
- | **No external DB** | Everything in a local SQLite file — no Neo4j, no cloud, no config |
201
- | **Watch mode** | Real-time graph updates as you code |
202
-
203
- ---
204
-
205
- ## It Just Works
206
-
207
- After the initial `build`, you don't need to think about this plugin. Here's what happens automatically:
208
-
209
- - **You edit a file** → hook updates the graph in <2s
210
- - **You make a commit** → hook updates the graph
211
- - **You ask Claude to review code** → Claude checks the graph, reads only impacted files
212
- - **You ask Claude to add a feature** → Claude uses the graph to find exactly where to make changes
213
-
214
- No configuration. No maintenance. No commands to remember.
215
-
216
- ---
217
-
218
- ## Configuration
219
-
220
- Optionally create `.code-review-graphignore` in your repo root to exclude paths:
221
-
222
- ```
223
- generated/**
224
- *.generated.ts
225
- vendor/**
226
- node_modules/**
227
- ```
228
-
229
- For semantic search (optional, requires extra dependencies):
230
-
231
- ```bash
232
- pip install code-review-graph[embeddings]
233
- ```
234
-
235
- Then ask Claude to "embed the code graph" — this enables searching by meaning, not just name.
236
-
237
- ---
238
-
239
- ## Contributing
240
-
241
- ```bash
242
- git clone https://github.com/tirth8205/code-review-graph.git
243
- cd code-review-graph
244
- python3 -m venv .venv && source .venv/bin/activate
245
- pip install -e ".[dev]"
246
- pytest
247
- ```
248
-
249
- **Adding a new language?** Edit `code_review_graph/parser.py` — add your extension to `EXTENSION_TO_LANGUAGE` and node type mappings to `_CLASS_TYPES`, `_FUNCTION_TYPES`, `_IMPORT_TYPES`, `_CALL_TYPES`. Then add a test fixture and submit a PR.
250
-
251
- ---
252
-
253
- ## License
254
-
255
- MIT — see [LICENSE](LICENSE).
256
-
257
- ---
258
-
259
- <p align="center">
260
- <br>
261
- <strong>Try it now:</strong>
262
- <br><br>
263
- <code>pip install git+https://github.com/tirth8205/code-review-graph.git && code-review-graph install</code>
264
- <br><br>
265
- Build the graph once. Let Claude handle the rest.
266
- </p>
code_review_graph-1.7.0/README.md DELETED
@@ -1,232 +0,0 @@
1
- <p align="center">
2
- <img src="docs/assets/banner.jpg" alt="code-review-graph" width="100%" />
3
- </p>
4
-
5
- <h1 align="center">code-review-graph</h1>
6
-
7
- <p align="center">
8
- <strong>Give Claude a map of your codebase so it stops reading every file.</strong>
9
- </p>
10
-
11
- <p align="center">
12
- <a href="https://github.com/tirth8205/code-review-graph/stargazers"><img src="https://img.shields.io/github/stars/tirth8205/code-review-graph?style=flat-square" alt="Stars"></a>
13
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License"></a>
14
- <a href="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml"><img src="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
15
- <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python 3.10+"></a>
16
- <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
17
- <a href="#"><img src="https://img.shields.io/badge/version-1.7.0-purple.svg?style=flat-square" alt="v1.7.0"></a>
18
- </p>
19
-
20
- ---
21
-
22
- Claude Code is powerful, but it wastes tokens re-reading your entire codebase on every review and every coding task. `code-review-graph` builds a structural map of your code using [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), tracks it incrementally, and tells Claude exactly which files matter — so it reads 5 files instead of 500.
23
-
24
- Benchmarked on real open-source repos: **6.8x fewer tokens for code reviews, up to 49x fewer tokens for coding tasks.**
25
-
26
- ---
27
-
28
- ## Install in 45 Seconds
29
-
30
- ### Option A: Claude Code Plugin (recommended)
31
-
32
- ```bash
33
- claude plugin add tirth8205/code-review-graph
34
- ```
35
-
36
- Restart Claude Code. Done.
37
-
38
- ### Option B: pip
39
-
40
- ```bash
41
- pip install git+https://github.com/tirth8205/code-review-graph.git
42
- code-review-graph install
43
- ```
44
-
45
- This creates a `.mcp.json` file in your project that tells Claude Code where to find the MCP server. Restart Claude Code to activate.
46
-
47
- > Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). Install uv with `pip install uv` or `brew install uv`.
48
-
49
- ---
50
-
51
- ## First Time in a Project
52
-
53
- After installing, open your project in Claude Code and say:
54
-
55
- ```
56
- Build the code review graph for this project
57
- ```
58
-
59
- That's it. Takes about 10 seconds for a 500-file project. After that, the graph updates automatically whenever you edit files or make commits — you never need to think about it again.
60
-
61
- ---
62
-
63
- ## How It Works (for Normal People)
64
-
65
- ```
66
- Your codebase has hundreds of files.
67
- Claude doesn't know which ones matter for what you're doing.
68
-
69
- Without this plugin:
70
- Claude reads everything → slow, expensive, shallow understanding
71
-
72
- With this plugin:
73
- 1. A graph maps every function, class, import, and dependency
74
- 2. When you ask Claude to review code or make changes,
75
- it checks the graph first: "What changed? What depends on it?"
76
- 3. Claude reads only those specific files
77
- 4. Result: faster, cheaper, and actually better reviews
78
- (because it sees the full blast radius, not just the diff)
79
- ```
80
-
81
- **You don't change how you work.** You still talk to Claude exactly the same way. It just has a map now, so it doesn't get lost.
82
-
83
- ---
84
-
85
- ## Benchmarks
86
-
87
- All numbers from real tests on 3 production open-source repos — not toy examples.
88
-
89
- ### Code Reviews: 6.8x Token Reduction
90
-
91
- Tested across 6 real git commits. The graph replaces reading entire files with a compact structural summary (156–207 tokens) that includes blast radius, test coverage gaps, and dependency chains.
92
-
93
- | Repo | Size | Standard Approach | With Graph | Savings | Review Quality |
94
- |------|-----:|------------------:|-----------:|--------:|:-:|
95
- | [httpx](https://github.com/encode/httpx) | 125 files | 12,507 tokens | 458 tokens | **26.2x** | 9.0 vs 7.0 |
96
- | [FastAPI](https://github.com/fastapi/fastapi) | 2,915 files | 5,495 tokens | 871 tokens | **8.1x** | 8.5 vs 7.5 |
97
- | [Next.js](https://github.com/vercel/next.js) | 27,732 files | 21,614 tokens | 4,457 tokens | **6.0x** | 9.0 vs 7.0 |
98
- | **Average** | | **13,205** | **1,928** | **6.8x** | **8.8 vs 7.2** |
99
-
100
- > "Standard approach" = reading all changed files + diff (what you'd do without the graph). Quality scored on accuracy, completeness, bug-catching, and actionable insight (1–10 scale).
101
-
102
- ### Live Coding Tasks: 14.1x Average, 49x Peak
103
-
104
- An AI agent performed 6 real coding tasks (adding features, fixing bugs) across the same repos. The graph told it which files to read and which to skip.
105
-
106
- | Task | Repo | With Graph | Without Graph | Savings | Files Skipped |
107
- |------|------|--------:|-----------:|--------:|---:|
108
- | Add rate limiter | httpx | 14,090 | 64,666 | 4.6x | 58 |
109
- | Fix streaming bug | httpx | 14,090 | 64,666 | 4.6x | 59 |
110
- | Add rate limiter | FastAPI | 37,217 | 138,585 | 3.7x | 1,120 |
111
- | Fix streaming bug | FastAPI | 36,986 | 138,585 | 3.7x | 1,121 |
112
- | Add rate limiter | Next.js | 15,049 | 739,352 | **49.1x** | ~16,000 |
113
- | Fix streaming bug | Next.js | 16,135 | 739,352 | **45.8x** | ~16,000 |
114
-
115
- The graph pointed to exactly the right files **100% of the time** — zero false leads across all tasks. The bigger your repo, the bigger the savings.
116
-
117
- ---
118
-
119
- ## Usage
120
-
121
- ### Slash Commands (inside Claude Code)
122
-
123
- | Command | What it does |
124
- |---------|-------------|
125
- | `/code-review-graph:build-graph` | Build or rebuild the code graph (~10s for 500 files) |
126
- | `/code-review-graph:review-delta` | Review only what changed since last commit |
127
- | `/code-review-graph:review-pr` | Full PR review with blast-radius analysis |
128
-
129
- ### CLI
130
-
131
- ```bash
132
- code-review-graph install # Register MCP server with Claude Code
133
- code-review-graph build # Parse your entire codebase
134
- code-review-graph update # Incremental update (only changed files)
135
- code-review-graph status # Show graph statistics
136
- code-review-graph watch # Real-time auto-updates as you code
137
- code-review-graph visualize # Interactive HTML graph visualization
138
- code-review-graph serve # Start MCP server manually
139
- ```
140
-
141
- ### MCP Tools (Claude uses these automatically)
142
-
143
- | Tool | What it does |
144
- |------|-------------|
145
- | `build_or_update_graph_tool` | Build or incrementally update the graph |
146
- | `get_impact_radius_tool` | Show blast radius of changed files |
147
- | `get_review_context_tool` | Token-optimized review context with structural summary |
148
- | `query_graph_tool` | Find callers, callees, tests, imports, inheritance |
149
- | `semantic_search_nodes_tool` | Search code entities by name or meaning |
150
- | `embed_graph_tool` | Compute vector embeddings for semantic search |
151
- | `list_graph_stats_tool` | Graph size and health check |
152
- | `get_docs_section_tool` | Retrieve docs sections with minimal tokens |
153
-
154
- ---
155
-
156
- ## Features
157
-
158
- | Feature | Details |
159
- |---------|---------|
160
- | **Incremental updates** | Only re-parses changed files. Updates take <2s after initial build. |
161
- | **12 languages** | Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++ |
162
- | **Blast-radius analysis** | See exactly which functions, classes, and files are impacted by any change |
163
- | **Auto-update hooks** | Graph stays current on every file edit and git commit — zero maintenance |
164
- | **Semantic search** | Optional vector embeddings with sentence-transformers |
165
- | **Interactive visualization** | D3.js graph with edge-type toggles and search |
166
- | **No external DB** | Everything in a local SQLite file — no Neo4j, no cloud, no config |
167
- | **Watch mode** | Real-time graph updates as you code |
168
-
169
- ---
170
-
171
- ## It Just Works
172
-
173
- After the initial `build`, you don't need to think about this plugin. Here's what happens automatically:
174
-
175
- - **You edit a file** → hook updates the graph in <2s
176
- - **You make a commit** → hook updates the graph
177
- - **You ask Claude to review code** → Claude checks the graph, reads only impacted files
178
- - **You ask Claude to add a feature** → Claude uses the graph to find exactly where to make changes
179
-
180
- No configuration. No maintenance. No commands to remember.
181
-
182
- ---
183
-
184
- ## Configuration
185
-
186
- Optionally create `.code-review-graphignore` in your repo root to exclude paths:
187
-
188
- ```
189
- generated/**
190
- *.generated.ts
191
- vendor/**
192
- node_modules/**
193
- ```
194
-
195
- For semantic search (optional, requires extra dependencies):
196
-
197
- ```bash
198
- pip install code-review-graph[embeddings]
199
- ```
200
-
201
- Then ask Claude to "embed the code graph" — this enables searching by meaning, not just name.
202
-
203
- ---
204
-
205
- ## Contributing
206
-
207
- ```bash
208
- git clone https://github.com/tirth8205/code-review-graph.git
209
- cd code-review-graph
210
- python3 -m venv .venv && source .venv/bin/activate
211
- pip install -e ".[dev]"
212
- pytest
213
- ```
214
-
215
- **Adding a new language?** Edit `code_review_graph/parser.py` — add your extension to `EXTENSION_TO_LANGUAGE` and node type mappings to `_CLASS_TYPES`, `_FUNCTION_TYPES`, `_IMPORT_TYPES`, `_CALL_TYPES`. Then add a test fixture and submit a PR.
216
-
217
- ---
218
-
219
- ## License
220
-
221
- MIT — see [LICENSE](LICENSE).
222
-
223
- ---
224
-
225
- <p align="center">
226
- <br>
227
- <strong>Try it now:</strong>
228
- <br><br>
229
- <code>pip install git+https://github.com/tirth8205/code-review-graph.git && code-review-graph install</code>
230
- <br><br>
231
- Build the graph once. Let Claude handle the rest.
232
- </p>