Two files, one repository
tirth8205/code-review-graph ships 4 formats across 4 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 8 | 4 | 11 | 35% |
| Commands | 3 | 0 | 12 | 20% |
| Section tags | 5 | 0 | 6 | 45% |
What each file covers
Sections
8 shared · 4 only in A · 11 only in B- − Agent Instructions
- − Non-Interactive Shell Commands
- − Force overwrite without prompting
- − For recursive operations
- + CLAUDE.md - Project Context for Claude Code
- + Project Overview
- + Graph Tool Usage (Token-Efficient)
- + Architecture
- + Key Commands
- + Development
- + Build & test
- + Code Conventions
- + Security Invariants
- + Test Structure
- + CI Pipeline
- Quick Reference
- Beads Issue Tracker
- Rules
- Session Completion
- MCP Tools: code-review-graph
- When to use graph tools FIRST
- Key Tools
- Workflow
Commands
3 shared · 0 only in A · 12 only in B- + uv run pytest tests/ --tb=short -q
- + uv run ruff check code_review_graph/
- + uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
- + uv run code-review-graph build
- + uv run code-review-graph update
- + uv run code-review-graph status
- + uv run code-review-graph serve
- + uv run code-review-graph wiki
- + uv run code-review-graph detect-changes
- + uv run code-review-graph register <path>
- + uv run code-review-graph repos
- + uv run code-review-graph eval
- git pull --rebase
- git push
- git status
Section tags
5 shared · 0 only in A · 6 only in B- + build
- + test
- + lint-format
- + architecture
- + security
- + deployment
- code-style
- testing-strategy
- git-pr
- do-not
- agent-behaviour
Line diff
tirth8205/code-review-graph · AGENTS.md
@@ −1 @@
1# Agent Instructions
2
3This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
4
5## Quick Reference
6
7```bash
8bd ready # Find available work
9bd show <id> # View issue details
10bd update <id> --claim # Claim work atomically
11bd close <id> # Complete work
12bd dolt push # Push beads data to remote
13```
14
15## Non-Interactive Shell Commands
16
17**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
18
19Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
20
21**Use these forms instead:**
22```bash
23# Force overwrite without prompting
24cp -f source dest # NOT: cp source dest
25mv -f source dest # NOT: mv source dest
26rm -f file # NOT: rm file
27
28# For recursive operations
29rm -rf directory # NOT: rm -r directory
30cp -rf source dest # NOT: cp -r source dest
31```
32
33**Other commands that may prompt:**
34- `scp` - use `-o BatchMode=yes` for non-interactive
35- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
36- `apt-get` - use `-y` flag
37- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
38
39<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
40## Beads Issue Tracker
tirth8205/code-review-graph · CLAUDE.md
@@ +1 @@
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 <path> # 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
@@ −1 +1 @@
1−# Agent Instructions
1+# CLAUDE.md - Project Context for Claude Code
22
3−This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
3+## Project Overview
44
5−## Quick Reference
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.
66
7−```bash
8−bd ready # Find available work
9−bd show <id> # View issue details
10−bd update <id> --claim # Claim work atomically
11−bd close <id> # Complete work
12−bd dolt push # Push beads data to remote
13−```
7+## Graph Tool Usage (Token-Efficient)
8+When using code-review-graph MCP tools, follow these rules:
9+1. First call: `get_minimal_context(task="<description>")` — costs ~100 tokens, gives you the full picture.
10+2. All subsequent calls: use `detail_level="minimal"` unless you need more.
11+3. Prefer `query_graph_tool` with a specific target over broad `list_*` calls.
12+4. The `next_tool_suggestions` field in every response tells you the optimal next step.
13+5. Target: ≤5 tool calls per task, ≤800 total tokens of graph context.
1414
15−## Non-Interactive Shell Commands
15+## Architecture
1616
17−**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
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
1839
19−Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
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
2043
21−**Use these forms instead:**
44+- **Database**: `.code-review-graph/graph.db` (SQLite, WAL mode)
45+
46+## Key Commands
47+
2248 ```bash
23−# Force overwrite without prompting
24−cp -f source dest # NOT: cp source dest
25−mv -f source dest # NOT: mv source dest
26−rm -f file # NOT: rm file
49+# Development
50+uv run pytest tests/ --tb=short -q # Run tests
51+uv run ruff check code_review_graph/ # Lint
52+uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
2753
28−# For recursive operations
29−rm -rf directory # NOT: rm -r directory
30−cp -rf source dest # NOT: cp -r source dest
54+# Build & test
55+uv run code-review-graph build # Full graph build
56+uv run code-review-graph update # Incremental update
57+uv run code-review-graph status # Show stats
58+uv run code-review-graph serve # Start MCP server
59+uv run code-review-graph wiki # Generate markdown wiki
60+uv run code-review-graph detect-changes # Risk-scored change analysis
61+uv run code-review-graph register <path> # Register repo in multi-repo registry
62+uv run code-review-graph repos # List registered repos
63+uv run code-review-graph eval # Run evaluation benchmarks
3164 ```
3265
33−**Other commands that may prompt:**
34−- `scp` - use `-o BatchMode=yes` for non-interactive
35−- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
36−- `apt-get` - use `-y` flag
37−- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
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+
38121
39122 <!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
40123 ## Beads Issue Tracker
