Context-aware AI code review using Model Context Protocol (MCP)
npm install specvectorContext-aware code review. Powered by agents, not just diffs.
SpecVector is an open-source AI code reviewer that actively explores your codebase. It reads related files, searches for patterns, checks Linear tickets, and understands your architecture — the way a senior engineer would.
``bash`
bunx specvector init
Most AI review tools read the diff. SpecVector reads the architecture.
- Agentic exploration — Greps for usages, reads imports, follows references. Active investigation, not passive text matching.
- Requirements verification — Fetches your Linear ticket via MCP and checks if the code satisfies the acceptance criteria.
- Smart pipeline — Classifies files by risk (SKIP / FAST_PASS / DEEP_DIVE). Docs get a fast pass. Auth code gets a deep dive.
- Privacy-first — Run locally with Ollama. Your code never leaves your machine.
`bash`
bunx specvector init
This creates .github/workflows/specvector.yml and .specvector/config.yaml.
Go to Settings > Secrets and variables > Actions in your GitHub repo and add:
- OPENROUTER_API_KEY — get one at openrouter.aiLINEAR_API_TOKEN
- — optional, for ticket context
SpecVector reviews automatically on every pull request.
Want a review on demand? Comment @specvector review on any PR.
``
specvector init Scaffold workflow and config files
specvector review
specvector review
specvector review
specvector --help Show this help
`bashPreview a review (no posting)
bunx specvector review 123 --dry-run
Configuration
.specvector/config.yaml:`yaml
provider: openrouter # or ollama
model: anthropic/claude-sonnet-4.5 # any OpenRouter model
strictness: normal # strict | normal | lenient
skipBots: true # skip dependabot/renovate PRs
maxPrSize: 500 # warn when PR exceeds N lines (0 = off)
selfReviewCheck: true # warn when no human reviewer assigned
`All settings can be overridden via environment variables:
SPECVECTOR_PROVIDER, SPECVECTOR_MODEL, SPECVECTOR_STRICTNESS, etc.LLM Providers
| Provider | Use Case | Setup |
|----------|----------|-------|
| OpenRouter | Cloud — Claude, GPT-4, Llama, Mistral |
OPENROUTER_API_KEY |
| Ollama | Local — air-gapped, privacy-first | ollama serve |`bash
Use a local model
SPECVECTOR_PROVIDER=ollama SPECVECTOR_MODEL=llama3.2 bunx specvector review 123 --dry-run
`GitHub Action
$3
`yaml
- uses: Not-Diamond/specvector@v0
with:
pr-number: ${{ github.event.pull_request.number || github.event.issue.number }}
openrouter-api-key: ${{ secrets.OPENROUTER_API_KEY }}
`$3
The
init command scaffolds this for you, or add manually:`yaml
name: SpecVector Code Reviewon:
pull_request:
types: [opened, synchronize, reopened]
issue_comment:
types: [created]
permissions:
contents: read
pull-requests: write
jobs:
review:
runs-on: ubuntu-latest
if: >-
github.event_name == 'pull_request' ||
(
github.event_name == 'issue_comment' &&
github.event.issue.pull_request &&
contains(github.event.comment.body, '@specvector review')
)
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 }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
run: bunx specvector review "$PR_NUMBER"
`How It Works
`
PR Diff --> Smart Pipeline --> Agent Loop --> LLM --> Review
| ^
Tools Linear MCP
(read_file, (ticket context)
grep,
list_dir)
`1. Classify — Files are triaged by risk level
2. Explore — The agent reads related code, searches for patterns, checks tickets
3. Review — Findings are posted as inline comments on the exact lines
Development
`bash
git clone https://github.com/Not-Diamond/specvector.git
cd specvector && bun install
bun test # run tests
bun run check # type check
`License
MIT
Contributing
PRs welcome. Run
bun test` before submitting.