Content
# arch-aware-review
An MCP server and CLI tool that performs **code reviews with architectural awareness** — it understands your dependency graph, not just the diff.
Unlike standard linters or diff-based review tools, `arch-review-mcp` builds a live dependency graph of your codebase and evaluates every PR against it — detecting boundary violations, tracing downstream impact, and feeding that structural context to Claude for a senior-architect-quality review.
---
## Why it's different
| Tool | What it sees |
|------|-------------|
| ESLint / Biome | Syntax and style in one file |
| Danger.js | PR metadata (size, files changed) |
| CodeClimate | Code smells, duplication |
| **arch-review-mcp** | Who imports whom, what breaks if X changes, what the module boundaries _actually are_ in your codebase |
---
## How it works
1. **Index** — tree-sitter parses every `.ts/.tsx/.js/.jsx` file and stores symbols + import edges in a local SQLite database.
2. **Diff** — `git diff origin/main...{branch}` identifies what changed.
3. **Rules** — violations are checked against your `.arch-review.json` config *and* auto-detected boundaries.
4. **Context** — a structured prompt is built: changed files, their import graphs, downstream impact, and violations.
5. **Review** — Claude (via Anthropic API) gives a structured architectural review.
6. **Comment** — the review is posted as a GitHub PR comment (optional).
---
## Installation
```bash
npm install -g arch-aware-review
```
Or run directly from the repo:
```bash
git clone https://github.com/sayamgandhak/arch-aware-review
cd arch-aware-review
npm install
npm run build
npm link
```
---
## Quick Start (5 steps)
```bash
# 1. Go to your project
cd ~/my-project
# 2. Index the codebase (takes ~5s for most projects)
arch-review index
# 3. (Optional) Create your rules config
cp node_modules/arch-review-mcp/.arch-review.json.example .arch-review.json
# Edit .arch-review.json to define your architecture rules
# 4. Set your API keys
export ANTHROPIC_API_KEY=sk-ant-...
export GITHUB_TOKEN=ghp_... # optional, for posting comments
# 5. Review a PR branch
arch-review review-pr --branch feat/my-feature
```
---
## CLI Commands
### `arch-review index [path]`
Scan and index the codebase. Creates `.arch-review/index.db` in the project root.
```bash
arch-review index
arch-review index ~/my-project
```
### `arch-review review-pr`
Review a branch vs `origin/main`. Runs incremental indexing, evaluates rules, calls Claude, and posts to GitHub.
```bash
arch-review review-pr --branch feat/auth-refactor
arch-review review-pr --branch feat/auth-refactor --no-github # print to stdout
arch-review review-pr --branch feat/auth-refactor --path ~/my-project
```
Options:
- `-b, --branch <branch>` — **required** — branch to review
- `-p, --path <path>` — project root (defaults to cwd)
- `--no-github` — skip posting GitHub comment, print to stdout
### `arch-review rules [path]`
List all active rules: configured ones from `.arch-review.json` plus auto-detected patterns.
```bash
arch-review rules
```
### `arch-review status [path]`
Show index stats: file count, module structure, DB size.
```bash
arch-review status
```
### `arch-review impact --file <file> [path]`
Trace the blast radius of changing a file.
```bash
arch-review impact --file src/utils/crypto.ts
```
---
## Config File (`.arch-review.json`)
```json
{
"rules": [
{
"name": "Auth isolation",
"description": "Auth must not access DB directly",
"from": "src/auth/**",
"forbidden": ["src/models/**", "src/database/**"],
"message": "Auth should use services, not models directly. See ADR-003."
}
],
"ignore": ["src/generated/**"],
"github": {
"owner": "myorg",
"repo": "myrepo"
}
}
```
See [`.arch-review.json.example`](.arch-review.json.example) for a fully annotated example.
---
## MCP Tools
Use `arch-review-mcp` as an MCP server inside Claude Code or any MCP-compatible client.
Add to your MCP config:
```json
{
"mcpServers": {
"arch-aware-review": {
"command": "arch-aware-review"
}
}
}
```
### `index_codebase`
```json
{ "rootPath": "/absolute/path/to/project" }
```
Returns: `{ filesIndexed, symbolsFound, edgesCreated }`
### `review_pr`
```json
{
"branch": "feat/my-feature",
"rootPath": "/absolute/path/to/project",
"noGithub": false
}
```
Returns: Full architectural review from Claude + risk level.
### `get_architecture`
```json
{ "rootPath": "/absolute/path/to/project" }
```
Returns: Module list with file counts and inter-module dependencies.
### `check_rules`
```json
{ "rootPath": "/absolute/path/to/project" }
```
Returns: All configured rules + auto-detected boundary patterns.
### `trace_impact`
```json
{
"filePath": "src/utils/crypto.ts",
"rootPath": "/absolute/path/to/project"
}
```
Returns: `{ directDependents, allDependents, depth }`
---
## Example Review Output
```
# 🏛️ Architectural Review
## Summary
This PR refactors the authentication flow by moving token validation from
the controller layer into a new `auth/validator.ts` module. The changes
introduce a direct dependency from `src/auth` to `src/models/User`, which
violates the established service-layer boundary.
## Risk Level: 🔴 HIGH
## ❌ Architectural Violations
❌ **Auth isolation** in `src/auth/validator.ts`
> Auth module should use services, not access models directly. See ADR-003.
> Imports: `src/models/User.ts`
## ⚠️ Warnings
- `src/auth/validator.ts` is now imported by 3 files — changes here will
affect `src/middleware/auth.ts`, `src/routes/login.ts`, and `src/routes/signup.ts`
## ✅ Suggestions
- Extract the User lookup into `src/services/userService.ts` and inject it
into the validator instead of importing the model directly
- Consider making `AuthValidator` an interface to enable easier testing
```
---
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Yes (for review) | Claude API key |
| `GITHUB_TOKEN` | No | GitHub token for posting PR comments |
| `ARCH_REVIEW_DB` | No | Override the default DB path |
---
## How Auto-Detection Works
Even without a `.arch-review.json`, the tool infers architectural rules from the existing codebase:
- **Module boundaries**: Folder pairs that have never imported each other in existing code are flagged as implicit boundaries. New imports that cross them become warnings.
- **Leaf modules**: Folders that are only ever imported (never import others) are flagged as "pure" utilities. If they start importing upward, it's a warning.
- **Hub files**: Files imported by 5+ other files are flagged as critical — any change to them gets elevated attention in the review.
Detected rules have a confidence score (0–1). Only high-confidence patterns (>0.7) produce warnings by default.
---
## License
MIT
