Documentation

Reference for the three Mergestorm agents — Vortex (reviews), Cyclone (auto-patch), and Tempest (deep systemic review) — plus dashboard settings, credits, the Review Jobs API/CLI, stacked PRs via mg, and troubleshooting. New here? Start with How it works for the full setup walkthrough, or /cli for install + stacks quickstart.

New to pull requests? Take the 5-minute crash course — from pushing to main to your first reviewed PR.

Quick start

Mergestorm reviews pull requests with three agents, each its own GitHub App you connect only if you want it:

Vortex — inline comments and a check run on every PR and push.
Cyclone — optionally commits fixes from review findings (auto-patch).
Tempest — mention-triggered deep systemic review; never patches.

Connect agents on Agents, enable repos and auto-review in Settings, then open a PR. Add Cyclone and Tempest later only if you want them.

Vortex — reviews

When Automatically review new PRs and commits is on, Vortex reviews on every PR open and new push — no command needed. Each review posts inline comments and a GitHub check run named vortex-v1.

Trigger a manual review by commenting on a pull request (not a standalone issue):

@mergestorm-vortex review

Variants such as @mergestorm-vortex[bot] review or @mergestorm-vortex please review work as long as the comment mentions the bot and includes the word review.

Must be a human comment (bot comments are ignored).
Only fires on newly created comments — editing an old comment does not re-trigger.
Draft PRs are skipped.
Vortex reacts with 👀 while the review runs.
History badges: Auto (automatic), Mention (manual @mergestorm-vortex review), or Manual (triggered from the dashboard).

Linked issue context

Use proper GitHub Issue workflows and Vortex reviews against the ticket — not just the diff. Open an Issue for the work, then link it from the PR with Closes #N, Fixes #N, Resolves #N, or the Development sidebar. Vortex pulls up to three linked issues into the review as background for intent and acceptance criteria (opening description, plus short discussion when the thread is small).

Cyclone — auto-patch

Cyclone has no @mention command. It runs automatically when auto-patch is enabled and Cyclone is connected (a separate GitHub App, mergestorm-cyclone). It reacts to:

Submitted PR reviews with actionable findings (including Vortex reviews).
Inline review comments (batched when the review is submitted).
Bot issue comments on PRs from allowed reviewers (Vortex, CodeRabbit, Greptile by default).
Human fix-request comments, for example: "please fix these comments", "apply the suggested fixes", "please address the review findings".

After a batch completes, Cyclone may post an informational outcome comment such as @mergestorm-vortex cyclone-outcome: fixed or cyclone-outcome: dismiss. Check runs appear as cyclone-v1 when enabled. Include stopreview in a finding body to stop Cyclone from processing that batch.

Tempest — deep review

Tempest is a deep systemic review for higher-stakes PRs. It traces cross-file risks (input handling, state drift, fallbacks, contract mismatches) and posts error-severity inline comments plus a single report comment. It runs as its own GitHub App (mergestorm-tempest) that you connect separately, and it never commits patches — it only reports.

Tempest is mention-only — it never runs automatically. Comment on a pull request with any of:

@mergestorm tempest
@mergestorm-tempest review
@mergestorm-tempest deep-review

Runs once per commit (head SHA) — mentioning again on the same commit is a no-op until you push a new commit.
Force a re-run on the current commit by including /force or --force in the mention comment.
Choose the model on Agents. Default is Opus 5. Tempest spends from the same monthly credit pool as every agent: DeepSeek V4 Pro = 6, Kimi K3 = 15, Opus 5 = 25, Sol 5.6 = 40, Fable 5 = 50 credits per review. Tempest is available on paid plans (Free is Vortex and Cyclone only).
Posts a GitHub check run named Tempest that reports progress and completion.

Dashboard settings

Open Settings to control review scope and automation:

Review all repositories — when on, every repo in your GitHub App installation is eligible; when off, pick repos on the Repositories tab.
Automatically review new PRs and commits — when off, Vortex skips reviews until you turn this back on (or use @mergestorm-vortex review). Its Advanced disclosure holds Review Integration Unit land PRs — off by default, Vortex auto-review skips land PRs (mg-stack-* → trunk); turn it on to auto-review the accumulated unit land PR too. Mentions and dashboard triggers review land PRs either way.
Automatically apply fixes from MergeStorm reviews — when on, Cyclone commits fixes from review comments to the PR branch. Off by default; requires Cyclone connected on Agents.

Work chat

The agent chat rail on Dashboard → Work supports three kinds of input:

Quote a PR, layer, or stack — the quote icon on any Work row (or typing # in the composer) attaches it as a chip. Chat then dispatches the right agent: re-review or explain via Vortex, fixes and restacks via Cyclone (with a confirm card), deep review via Tempest.
Paste a GitHub PR URL (https://github.com/owner/repo/pull/N) — it is quoted as a chip automatically, same as quoting the row.
General questions — setup and product help; agent dispatch needs Vortex connected on Agents. Chat takes no file uploads and does not write code — it acts on connected Work objects only.

The recommended workflow is the GitHub loop: open an Issue, open a PR that closes it, let Vortex review on pushes with that issue as context; add Cyclone later for optional auto-patch. Chat is supplementary.

Credits & billing

Billing uses one monthly credit pool (UTC calendar month) shared by every agent. Free tier: 30 credits / month.

Vortex completed review = 1 credit · Cyclone patch applied = 1 credit.
Tempest deep reviews (paid plans) by model: DeepSeek V4 Pro = 6, Kimi K3 = 15, Opus 5 = 25, Sol 5.6 = 40, Fable 5 = 50 credits per review.

Every agent debits the same monthly pool — Vortex 1 · Cyclone 1 · Tempest 6–50 by model. There is no separate premium balance.

See Usage & Billing for paid tiers, credit meters, and Stripe subscription management.

Review Jobs API & CLI

Get code reviews on a diff without opening a GitHub PR — for local loops and CI. Reviews run on the same engine as PR reviews and debit 1 credit each.

Fastest path — install the CLI and sign in via your browser (it mints and stores a key for you, no copy/paste):

curl -fsSL https://mergestorm.ai/install.sh | bash
mergestorm login
mergestorm          # interactive shell
mergestorm review

Get a key — mergestorm login mints one automatically after browser approval. For raw HTTP, create one on Dashboard → Settings → API — the full key (msk_live_…) is shown once, so copy it then.
Submit a review — POST /api/v1/reviews with a diff and optional file contents, using header Authorization: Bearer msk_live_…. Returns a job_id.
Poll — GET /api/v1/reviews/<job_id> until status is completed, or receive results via an optional webhook.
Thread chains — reuse the same thread slug on follow-up submissions so prior findings carry over. View chains under Work.
History — see your recent API/CLI reviews (status, time, thread, credits) on Dashboard → Settings → API.
CLI — bare mergestorm opens an interactive shell (credits, jobs, review). One-shot commands: login (browser device flow), logout, review, status, credits, jobs. Use login --key for headless/CI. For stacked PRs, see CLI — stacked PRs below.

CLI — stacked PRs

The same mergestorm / mg binary opens chained GitHub PRs from your terminal. Happy path: create → commit → submit → restack → land. Install and a short quickstart live on /cli; narrative + demo video on the stacks tutorial.

Requires Node.js 22+, mg login (Mergestorm API key), and local git + gh auth for push/PR open. Stack authoring state is managed under ~/.mergestorm/ — do not edit it by hand.

npm i -g mergestorm   # or: curl -fsSL https://mergestorm.ai/install.sh | bash
mg login
mg stack create feat/layer-one
# edit, then commit as usual
git commit -am "feat: layer one"
mg stack create feat/layer-two
git commit -am "feat: layer two"
mg stack submit

Command	What it does
mg stack create [name]	New local layer (optional `--onto` / `--trunk`). Onto trunk with an active stack starts a new stack.
mg stack submit	Push layers, open chained PRs with `gh`, register the stack in Mergestorm.
mg stack restack <stack-id>	Restack descendant layers after a base changes.
mg stack land <stack-id>	Promote into the review unit when one exists; otherwise land the bottom open PR.
mg stack auto-promote on\|off <stack-id>	Land-when-green for a registered stack.
mg stack list	List stacks registered with Mergestorm (via `submit`/ `adopt`).
mg stack adopt <owner/repo>#<pr>	Import an existing GitHub PR chain (also used internally by `submit`).
mg stack reset --force	Clear local pre-submit authoring state only — never deletes branches or PRs.

Source (MIT): github.com/marginsystems/mergestorm-cli. npm: mergestorm. Confirm flags with mg stack --help.

Troubleshooting

Review did not run — check auto-review is on, the repo is enabled, the PR is not a draft, and you have credits remaining.
Mention ignored — confirm the PR is open (not draft), the comment is new (not an edit), and you used @mergestorm-vortex review on the PR itself.
Tempest did not run — connect Tempest on Agents, mention it on the PR (@mergestorm-tempest review), and note it runs once per commit — add /force to re-run the same commit. Requires a paid plan with credits remaining.
Cyclone did not patch — connect Cyclone on Agents, turn on auto-patch in Settings, and ensure the review had actionable inline findings (not an approve/all-clear summary).
Chat dispatch not running — connect Vortex on Agents, then quote a PR or stack (or paste a public github.com/owner/repo/pull/N URL) to run reviews and fixes.

Contact

Questions or feedback: contact@mergestorm.ai