Documentation

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.

Surge is separate from the review agents: on-demand GitHub Actions runners for private repositories that scale to zero. See Surge — CI runners.

Connect agents and pick which repositories they watch on Agents, tune how they behave (auto-review, auto-patch, auto land) 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-v2.

Set ignored bot authors and review check colors in Settings → Vortex (see Dashboard settings).

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 posts a plain outcome comment. A pushed fix needs no marker: the push itself triggers the next Vortex review. When Cyclone leaves the findings open (nothing to change, failed, stopped), the comment starts with mergestorm-loop: dismiss, the same first line you or a coding agent post to dismiss findings, and Vortex resumes its paused review of that commit. 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.1 Flash = 4, Kimi K3 = 15, Opus 5 = 25, GPT-6 Astra = 30, Sol 5.6 = 40, Fable 5.1 = 50 credits per review. Tempest is available on all plans, including Free with 30 credits per month.
• Posts a GitHub check run named Tempest that reports progress and completion.

Surge — CI runners

Surge runs your GitHub Actions jobs on on-demand self-hosted runners: cloud VMs created for your repository when CI needs them and deleted once they sit idle (the idle timeout, 10 minutes by default). Nothing runs and no Surge minutes are counted while CI is quiet, so Surge scales to zero.

Surge is in public beta. Surge minutes are included with paid plans, each credit period: 300 on Scale, 1,000 per seat on Pro, and 3,000 per seat on Maelstrom (per-seat plans count up to 20 seats), while the subscription is active or trialing. See Billing. When the beta has no room for more runners, Surge does not start one for you and your jobs run on GitHub-hosted runners as they always have.

Requirements

• You sign in to Mergestorm with GitHub.
• The repository is private. Public and internal repositories are refused.
• You are an admin of that repository on GitHub.
• A Scale, Pro or Maelstrom plan with an active or trialing subscription, for Surge minutes.

Setup

1. Install the Mergestorm Surge GitHub App on the private repository.
2. Open Dashboard → Surge, enter the repository as owner/repo, and choose Create pool. An account has one pool, and a repository belongs to one pool. To move Surge to another repository, delete the pool in Settings → Surge and create a new one.

3. Point each job you want on Surge at the routing variable in your workflow file:

   jobs:
     test:
       runs-on: ${{ vars.CI_SURGE_RUNNER || 'ubuntu-latest' }}
       steps:
         - uses: actions/checkout@v4

   Mergestorm sets the repository variable CI_SURGE_RUNNER to your pool's runner label only while a Surge runner is online, and deletes it when Surge is off. With the variable unset the expression falls back to ubuntu-latest, so the same workflow keeps running on GitHub-hosted runners with no edits.

4. Turn Surge on in the Surge tab:
   • Manual — start a fixed number of runners. They stop, and Surge turns off, once the idle timeout passes with no jobs.
   • Auto — Surge starts runners when a watched workflow run needs them and scales back to zero after the idle timeout. Set Runners per CI run and the watched workflow names (default CI) in Settings → Surge. Auto learns about workflow runs from GitHub webhooks that Mergestorm receives through the Cyclone GitHub App (mergestorm-cyclone), so connect Cyclone on Agents for the same repository. Auto-patch keeps its own setting. The Surge tab's job list comes from the same webhooks.

Surge minutes

A Surge minute is one wall-clock minute of a runner VM, from creation to deletion (boot and idle time included), times a weight for the server size (0.75 for a 4 vCPU runner, 1 for an 8 vCPU runner). The Surge tab and the Billing page show minutes used and left this period and when the period resets. When your minutes run out, Surge stops routing: it clears the variable, lets running jobs finish, and deletes the runners, so new jobs run on GitHub-hosted runners. Auto pauses and tries again a few minutes later.

An account without a paid plan (Free or Starter, or a subscription that is not active or trialing) has 0 Surge minutes, so Surge will not turn on: starting runners in Manual shows “No Surge minutes left.”, Auto pauses as soon as CI asks for a runner, and your jobs keep running on GitHub-hosted runners.

Isolation

• Each runner VM belongs to one pool and one repository. VMs are never shared across customers or repositories.
• A runner registers for one job at a time, and its workspace is wiped between jobs. The VM accepts no inbound connections and holds no GitHub credential.
• VMs are deleted when idle, and after a maximum age (8 hours by default) whatever they are doing.

Limits

• Runners are Linux x64. Docker is off on Surge runners and jobs run without sudo, so keep jobs that build images or use service containers on GitHub-hosted runners. Install toolchains in the job (for example with actions/setup-node) rather than relying on software preinstalled on GitHub-hosted images.
• No persistent cache between runners yet: each VM starts clean.
• Stop Surge, or switching Manual off, clears the routing variable, lets running jobs finish, then deletes the runners. Stop Surge in Auto also switches the pool back to Manual.
• Delete a pool in Settings → Surge once Surge is off and its runners have shut down. Recorded usage stays on your account.

Troubleshooting

• Jobs still run on ubuntu-latest — the job's runs-on must read vars.CI_SURGE_RUNNER, Surge must be on with a runner online (the variable stays unset until then), and you need Surge minutes left. In Auto, check the workflow name is in the watched list and Cyclone is connected on the repository.
• "Surge runs only on private repositories" — the repository is public or internal. Use a private repository.
• "Surge can't use that repository" — the Mergestorm Surge app is not installed on it (or has no access to it), or you are not an admin of the repository.

Dashboard settings

Two tabs, two jobs. Agents is where you connect Vortex, Cyclone, and Tempest, configure the specialist fleet, and choose scope: Review all repositories (every repo in your GitHub App installation is eligible) or a hand-picked list from the monitored repos below it. Settings controls how the installed agents behave and how Surge runners are configured, grouped as Vortex, Cyclone, Tempest, Surge, and Stacks:

• 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.
• Ignore bot PR authors (Settings → Vortex) — skip automatic reviews for these GitHub logins; renovate and renovate[bot] are one entry. Leave empty to review bot PRs as today; @mention and dashboard triggers still force a review on skipped PRs.
• Check on skipped bot PRs (Vortex) — No check (default, nothing posted) or Neutral check (completed · skipped). A skip never posts a review comment.
• When review has findings (Vortex) — Neutral (default) or Fail for a completed review with findings. Clean or approved reviews are always green; incomplete reviews and continue-wave handoffs are always neutral.
• Reset to defaults (Vortex) — clears the ignore list, returns skipped bot PRs to No check, and findings to Neutral. Does not change auto-review, Cyclone (including skip-CI), or Stacks.
• 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.
• When a patch batch fails (Settings → Cyclone) — Fail check (default, today’s red X) or Neutral check. Infrastructure retries and exhausted credits are unchanged. Vortex reset does not touch it.
• Tempest — mention-triggered, so there is nothing to automate yet. Its model picker stays on Agents for now.
• Surge — configure runners per CI run, watched workflows, and delete the pool.
• Auto land new stacks — when on, stacks you open afterwards start with Auto land enabled and enter the merge queue once green. Off by default.

API keys for the Review Jobs API and the CLI, plus the unlink (danger zone) control, also live on Settings.

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 (all plans) by model: DeepSeek V4.1 Flash = 4, Kimi K3 = 15, Opus 5 = 25, GPT-6 Astra = 30, Sol 5.6 = 40, Fable 5.1 = 50 credits per review.

Every agent debits the same monthly pool — Vortex 1 · Cyclone 1 · Tempest 4–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

Agents: install MCP with curl -fsSL https://mergestorm.ai/install.sh | bash -s -- --mcp, then claude mcp add mergestorm -- npx -y mergestorm-mcp. Tools: whoami, credits, review_submit, review_wait, review_list. Skill: skills/mergestorm-review/SKILL.md. Without MCP, mg review --json and poll with mg status <id> --json --wait.

• 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, submitting key, credits) on Dashboard → Billing. Settings → API stays the place to create and revoke keys.
• Rate limits: at most 5 review jobs in flight per user (429 too_many_in_flight_jobs), 10 submits per minute per key, and 300 reads per minute per key (429 rate_limited). Both 429 responses include a Retry-After header.
• OpenAPI: the full contract lives in the repo at docs/openapi.v1.yaml.
• 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.

Explicitly enqueueing a stack is the only unattended auto-land path. mg stack land is a manual skip-queue escape. Neither MCP nor the review skill can land.

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

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