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

npm install -g arch-aware-review

Or run directly from the repo:

git clone https://github.com/sayamgandhak/arch-aware-review
cd arch-aware-review
npm install
npm run build
npm link

Quick Start (5 steps)

# 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.

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.

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.

arch-review rules

arch-review status [path]

Show index stats: file count, module structure, DB size.

arch-review status

arch-review impact --file <file> [path]

Trace the blast radius of changing a file.

arch-review impact --file src/utils/crypto.ts

Config File (.arch-review.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 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:

{
  "mcpServers": {
    "arch-aware-review": {
      "command": "arch-aware-review"
    }
  }
}

index_codebase

{ "rootPath": "/absolute/path/to/project" }

Returns: { filesIndexed, symbolsFound, edgesCreated }

review_pr

{
  "branch": "feat/my-feature",
  "rootPath": "/absolute/path/to/project",
  "noGithub": false
}

Returns: Full architectural review from Claude + risk level.

get_architecture

{ "rootPath": "/absolute/path/to/project" }

Returns: Module list with file counts and inter-module dependencies.

check_rules

{ "rootPath": "/absolute/path/to/project" }

Returns: All configured rules + auto-detected boundary patterns.

trace_impact

{
  "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