SpecVector

Context-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
`

Why SpecVector

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.

Quick Start

$3

`bash
bunx specvector init
`

This creates .github/workflows/specvector.yml and .specvector/config.yaml.

$3

Go to Settings > Secrets and variables > Actions in your GitHub repo and add:

- OPENROUTER_API_KEY — get one at openrouter.ai
- LINEAR_API_TOKEN — optional, for ticket context

$3

SpecVector reviews automatically on every pull request.

Want a review on demand? Comment @specvector review on any PR.

CLI Usage

`
specvector init Scaffold workflow and config files
specvector review Review a pull request
specvector review --dry-run Preview review without posting
specvector review --mock Use mock review (no LLM)
specvector --help Show this help
`

$3

`bash


Preview a review (no posting)

bunx specvector review 123 --dry-run

Mock mode (no LLM calls)

bunx specvector review 123 --mock --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 Review

on:
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.