SpecVector

Context-aware AI code review using Model Context Protocol (MCP)

What is SpecVector?

SpecVector is an open-source AI code review tool that explores your codebase to provide context-aware feedback on pull requests.

Unlike generic AI review tools that only see the diff, SpecVector:

• Reads related files to understand context
• Searches for patterns to find usages
• Explores project structure to understand architecture
• Fetches Linear tickets for requirements context

Quick Start

1. Install

# Via npm/bun (recommended)
bunx specvector review 123 --dry-run

# Or clone for development
git clone https://github.com/Not-Diamond/specvector.git
cd specvector && bun install

2. Set up API Key

# Add your OpenRouter API key
export OPENROUTER_API_KEY=your-key-here

Get a key at openrouter.ai

3. Run a Review

# Review a PR (dry run - no posting)
bunx specvector review 123 --dry-run

# Or with mock review (no LLM calls)
bunx specvector review 123 --mock --dry-run

CLI Usage

SpecVector CLI v0.1.0
Context-aware AI code review

USAGE:
  bunx specvector review <pr-number>              Review a pull request
  bunx specvector review <pr-number> --dry-run    Preview review without posting
  bunx specvector review <pr-number> --mock       Use mock review (no LLM)
  bunx specvector --help                          Show this help
  bunx specvector --version                       Show version

ENVIRONMENT:
  OPENROUTER_API_KEY       API key for OpenRouter
  LINEAR_API_TOKEN         API key for Linear (optional)
  SPECVECTOR_PROVIDER      LLM provider (openrouter or ollama)
  SPECVECTOR_MODEL         Model to use

GitHub Action

Add to your repository:

name: SpecVector Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: oven-sh/setup-bun@v2

      - name: Review PR
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          LINEAR_API_TOKEN: ${{ secrets.LINEAR_API_TOKEN }} # Optional
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: bunx specvector review ${{ github.event.pull_request.number }}

Configuration

Create .specvector/config.yaml in your repo:

provider: openrouter
model: anthropic/claude-sonnet-4.5
strictness: normal # strict | normal | lenient

LLM Providers

| Provider | Use Case | Setup | | ---------- | -------------------------------------- | -------------------- | | OpenRouter | Cloud access to Claude, GPT-4, Llama | OPENROUTER_API_KEY | | Ollama | Self-hosted, air-gapped, privacy-first | ollama serve |

# Use Ollama instead of OpenRouter
SPECVECTOR_PROVIDER=ollama SPECVECTOR_MODEL=llama3.2 bunx specvector review 123 --dry-run

Architecture

PR Diff ───→ Agent Loop ───→ LLM ───→ Review Comment
                 ↓  ↑
               Tools         Linear MCP
            (read_file,  →  (ticket context)
             grep,
             list_dir)

Local Development

# Run tests (158 passing)
bun test

# Type check
bun run check

License

MIT

Contributing

PRs welcome! Run bun test before submitting.