Features

Vectorscope code review

Vectorscope is Vector's code review bot. It reads the repository around a change, not just the diff, and says what is wrong with it — on a pull request, on your branch before you push, or on the work sitting in your editor right now.

Where Vectorscope runs

On every pull request: Say yes to automatic review during vector github install. Vectorscope reviews each pull request when it opens and again on every push, and answers /vectorscope in a comment.
Before you push: vector vectorscope in your terminal runs the same review on your branch against its merge base, or on your uncommitted work with --uncommitted. Nothing is posted anywhere.
In the workspace: The desktop app's Pull Requests panel reviews a pull request in place and lets you post the result, or keep it to yourself.

On a pull request

Vectorscope leaves one summary comment with the risk, what changed and the files that matter, and comments on the exact lines, each with a severity and, where it is safe, a fix you can commit from GitHub. It reads the repository, not just the diff: it opens the changed files, follows their callers and checks the tests. On the next push it reviews only what changed and says what got fixed instead of repeating itself.

What you get: A summary that is edited in place, and one review per push that contains only new comments. Severities are Blocking, Concern and Nit. Nits and style points are left out unless you set nits to true; anything outside the changed lines stays in the summary. Vectorscope only ever comments. It never approves or blocks a pull request, unless you set failOn to make its check fail on blocking issues.
Commands: /vectorscope review reviews again, /vectorscope review full starts over, and /vectorscope pause or /vectorscope resume turns automatic reviews off or on for one pull request (or add the vector:paused label). Reply /vectorscope fix on a comment and Vectorscope applies that fix. /vs is the short form; /vector and /vx still work, so workflows installed before the name existed keep running. General coding tasks on issues continue to use /vector or /vx. A person with write access, or the pull request's author, can resolve a comment or react to it with a thumbs-down, and Vectorscope won't raise it again. Commands need write access.
Your rules: Write plain-English rules in .vector/review.md. A ## path: src/billing/** heading scopes the rules under it. Tune limits in .vector/review.json: maxComments (10), minSeverity (concern), minConfidence (0.7), nits (false), ignore, security, maxCostUsd, triageModel. Both are read from the base branch, so a pull request can't change the rules it is reviewed under, except by editing the workflow file, which needs write access.
Low noise: Lockfiles, build output, generated and vendored files, snapshots and binaries are skipped and listed. Drafts, dependency bots and pull requests labelled vector:skip are skipped. To review drafts too, delete the draft == false line from .github/workflows/vector.yml. Very large pull requests get a note with a cost estimate instead of a review.
Cost: Your model provider bills usage under your own credentials. Every review ends with the model, the tokens, what it cost and the total for that pull request. Each review stops at maxCostUsd ($2.00), automatic reviews of one pull request stop at maxCostUsdPerPr ($10.00), and REVIEW_MAX_COST_USD_PER_MONTH in the workflow caps a month. Set REVIEW_AUTO_MODEL to use a cheaper model for automatic reviews, or triageModel in .vector/review.json to run the first pass on a cheaper model and double-check its findings on your review model.

Choose a model

After upgrading to 1.99.99, repositories using Vector's GitHub workflow should run vector github install again. The regenerated workflow uses VECTOR_* configuration variables.

From 1.99.99, reviews and GitHub runs need your own provider credentials. The VECTOR_CLI_TOKEN secret authenticates your Vector account; it does not provide model access. Add the provider key as a repository secret and pass it into each job that calls Vector, using the provider's environment variable, such as ANTHROPIC_API_KEY or OPENAI_API_KEY. Set MODEL in the job's environment to a model that provider offers, in provider/model format.

New workflows connect the selected provider's secret automatically. Check older workflows too: provider-key lines that are commented out do not pass the secret into the run. If no model is configured or available, Vector stops with setup instructions instead of selecting an unavailable model. Set REVIEW_AUTO_MODEL to choose a different model for automatic reviews, or set model in .vector/review.json.

For a local review, connect a provider with vector auth login and choose a model with --model provider/model, your review configuration, or Vector's configured default.

From 1.99.99, the former third-party hosted model providers are no longer available, even with your own API key for them. Connect another provider for reviews and GitHub runs.

Task in, pull request out

Run vector github install once inside a repository: it writes a workflow that installs the CLI from npm on every /vector comment, then add the VECTOR_CLI_TOKEN secret from your account page. From then on, commenting /vector fix the flaky auth test on an issue opens a branch and a pull request; commenting on an existing pull request replies on that branch.

Every pull request carries its evidence, not just a diff: a Changes table with line counts per file, the output of any test, typecheck, lint, or build command the agent ran with its exit code, the measured token cost of the run, the judge's PASS or FAIL verdict when a judge pass ran, and a link back to the workflow run. Reviewers see what was checked before they read a line.

One repository setting is required: under Settings → Actions → General → Workflow permissions, tick "Allow GitHub Actions to create and approve pull requests" (GitHub leaves it off by default; without it the branch is pushed and Vector comments a compare link instead). Pull requests opened with the built-in GitHub token do not trigger the repository's other workflows; use a personal access token if you need CI to run on them.

Before you push

vector vectorscope (or vector review) runs the same review on your branch against its merge-base with the default branch. Use --uncommitted for work in progress, --json for scripts, and --fail-on blocking in a pre-push hook.

vector vectorscope vector vectorscope --uncommitted vector vectorscope --pr 482 --json

GitHub from the terminal

vector pr <number> fetches a pull request's branch, checks it out and starts Vector in that working tree — the shortcut for picking a review conversation up on your own machine.

vector pr 482 vector github review --pr 482 --dry-run

The generated workflow calls two commands you can also run yourself. vector github run executes the agent for a GitHub event, with --event for a payload and --token for a personal access token. vector github review reviews a pull request and posts the result; --dry-run prints every write it would make as JSON instead of posting, which is how you test a configuration change without commenting on a real pull request.

How a review runs

Vectorscope is one engine behind three doors: the GitHub Action, vector vectorscope in your terminal, and the Pull Requests panel in the desktop app. They share the same prompts, the same output schema, the same filters and the same summary. This is what happens between a trigger and a comment.

A trigger arrives
A pull request opens or takes a push, or someone comments a command. Vectorscope answers to /vectorscope, /vs, /vector and /vx, longest name first.
The skip ladder decides whether to run
Ten rules in order, first match wins. Most of them only apply to automatic runs.
The run is planned
Which specialists run, how much diff fits the model's context, and what the run is allowed to spend.
Each specialist reads the code
A read-only session per specialist, with the changed files, their callers, their history and your rules — not just the diff.
A verify pass checks the candidates
A second pass re-reads the code at each cited location and confirms or rejects the finding.
Selection decides what is worth saying
Confidence, severity and caps decide what goes on a line, what goes in the summary, and what is dropped.
The review is posted
One summary comment, edited in place, and only the comments that are new since the last push.

Reading the command

The parser strips HTML comments, code fences and quoted lines before it looks for anything, so showing or quoting a command never runs it. Only the first line that starts with a mention is read. A known verb runs that verb; anything else is treated as a task for the agent rather than ignored.

The skip ladder

Rules apply in this order and the first match wins:

month-budgetThe monthly cap is spent. This one has no command exception.
labelA vector:paused, vector:skip or no-review label. Automatic runs only.
draftDraft pull requests. Automatic runs only.
authorDependabot and Renovate by default. Automatic runs only.
branchBranches matching a glob you set. Automatic runs only.
forkAutomatic runs only — a command on a fork does run, in untrusted mode.
already-reviewedThis head is already reviewed. Not overridable by /vectorscope review; only review full clears it.
pr-budgetThis pull request has spent its dollar cap. Automatic runs only.
nothing-to-reviewEvery changed file was ignored — lockfiles, generated, vendored, binary.
too-largeMore than 300 files or 5,000 changed lines. Automatic runs only; the summary carries a cost estimate instead.

Planning the run

Which specialists: The code reviewer always runs. A second, security-only reviewer joins it when security is auto (the default) and the change touches a sensitive path — authentication, crypto, SQL, payments, CI workflows, Dockerfiles — or whenever you set always. Each reports only its own kind of defect, so one problem is not posted twice.
How much diff: The budget is taken from the model's context: about 30% of what is left after a reserve, which is roughly 16,800 characters at 32k of context and 79,800 at 128k, capped by maxDiffChars (120,000). Files that do not fit inline are still reachable with the read tool.
Which models: Any model with at least 32k tokens of context. Below that the review refuses rather than truncating, and says which model and what size it has.

What the reviewer sees

A review is not a diff in a prompt. Each specialist gets a read-only session and, with it:

The changed files at headThe diff, and the reviewer opens the changed files in full. On an untrusted pull request the working tree is the base branch, so the prompt carries each changed file's head version, once: a numbered view with the added and removed lines marked replaces its diff where that is no longer than both together. A file over 200 lines keeps 20 lines around each change and folds the rest; a file too large to include is shown by its hunks with context. A re-review shows files with nothing new by their changed lines only.
Their callersDeclarations found in the added lines, then grep hits for where those symbols are used elsewhere.
Their historygit log and blame for the changed ranges, so a line that was deliberately written that way reads as such.
The conversationHuman review comments already on the pull request.
Your rulesPlain English from .vector/review.md, scoped by ## path: headings, read from the base branch.
What is still openFindings from earlier runs, and what your team has dismissed elsewhere in the repository.

The tools are read, grep, glob and list. The reviewer cannot edit files, run commands or browse the web. Vector's own code gathers the git history and posts the result.

The verify pass

Candidate findings go to a second pass that re-reads the code at each cited location and answers confirmed only when the defect is real and triggers as described, otherwise rejected with a one-sentence reason. Each candidate is handed over as untrusted text — a claim to check, never an instruction — because the first pass wrote it after reading code the pull request's author controls. On an untrusted pull request a committable fix is offered only after the verify pass confirms the finding.

With triageModel set in .vector/review.json, the review and security passes run on that model, and every finding above a nit is then checked on your review model, even with verify set to off. Only the findings your review model confirmed are posted. An earlier finding the cheaper pass calls fixed is marked fixed, and its thread resolved, only when your review model confirms that too. If that check doesn't finish, the cheaper pass's findings are left out, earlier findings stay open, and the summary says so. Nits, when you turn them on, are listed in the summary without that check. vector review and the desktop panel list what each pass spent when a review has more than one pass.

Noise control

Selection is where a review stops being a wall of text. A finding below minConfidence (0.7) or below minSeverity (concern) does not go on a line, and anything outside the changed lines is listed in the summary instead. Nits and style points are dropped unless nits is true or minSeverity is nit. The same defect reported at several places in one file, with the same code or the same fix at each, becomes one finding that names the other lines, and a later review doesn't post a place again while the comment that names it is open.

The cap for a run is the smaller of maxComments (10) and what is left of maxCommentsPerPr (25) across the whole pull request; 50 is the ceiling either can be raised to. Findings over the cap move to the summary rather than disappearing.

One finding ignores the caps entirely: instructions in the pull request aimed at an AI reviewer. That is the finding a maintainer most needs to see, so it is always posted.

What carries between runs

Finding identity: A finding's id is a fingerprint of its file, its category, the meaningful words of its title and the code it points at — never the line number. A force-push or a rebase moves the line without creating a duplicate comment.
Status: Hidden markers in the comment bodies carry open, fixed, dismissed and outdated forward. The author or anyone with write access can resolve a comment or react with a thumbs-down, and that finding is not raised again.
Team memory: Dismissals are read across the repository, not just this pull request: up to thirty patterns of category, directory and title words. It is how the reviewer stops repeating a kind of comment your team has already said it does not want.

Posting

Vectorscope posts one review per run with the event comment. It never approves a pull request and never requests changes; the only way it can block a merge is the check you opt into with failOn. The summary comment is edited in place rather than repeated, and each push adds only comments that are new.

If GitHub refuses a batch of inline comments, the batch is split and each half posted on its own; a single comment GitHub will not take moves to the summary with its file and line, so no finding is silently lost.

Limits

Every run is bounded. Before each step Vectorscope prices the next one and stops if it would cross a line.

maxSteps: 30 model steps per specialist.
maxCostUsd: $2.00 for one review.
maxCostUsdPerPr: $10.00 across the automatic reviews of one pull request.
maxCostUsdPerMonth: Off by default; vector github install writes $50 into the workflow for paid models.
timeoutMinutes: 12 minutes.
maxFiles / maxChangedLines: 300 files, 5,000 lines, after the ignores.

A run that stops early is asked to finalize — return what it has confirmed rather than nothing — so a budget or a timeout still produces a review. A review can go past its budget by at most one model step, and it says so when it stops early. The monthly cap is best-effort on very busy repositories.

Security

Read-only by constructionPermission rules, not a prompt: no edit, no write, no patch, no shell. The local --checks option allows a short list of bare test and typecheck commands, never with flags, because flags on those commands can run any program.
Untrusted text is fencedEverything the pull request controls — code, titles, comments — is wrapped in untrusted tags, and any tag-like text inside it is escaped, so it cannot close its own block or open a trusted one.
Forks never runA fork's review resolves the checkout to the merge base. Its code is read as text and never executed, and automatic reviews of forks are off because GitHub gives those runs no secrets.
Settings come from the base.vector/review.md and .vector/review.json are read from the base branch, so a pull request cannot change the rules it is reviewed under.
Secrets are strippedSecret-looking values are redacted from everything posted, and the security reviewer is told to write the same placeholder rather than a value.
Least privilegeReviews post as github-actions[bot] and need only contents: read and pull-requests: write.