GitHub pull requests

A GitHub pull request opens as its own tab: the remote diff, comments, commits, checks, and an AI review of that change set. Reviewing the PR does not need a local checkout. Fixing a finding does, because the agent edits the files in this clone.

Vortex talks to GitHub through the gh CLI. There is no GitHub token in app prefs.

Open a pull request

1. Have gh installed and authenticated (gh auth status).
2. Open ⌘K → Review Pull Request. That opens the PR for the current branch, or the first open PR if this branch has none.
3. Source Control also shows the PR for the current branch; click it to open the same tab.

The tab shows the PR's files, conversation, commits, and checks. Checkout runs gh pr checkout in the owning workspace root so the working tree matches the PR's head branch.

In chat, PR #42 and pull request #42 open the pull request when this workspace has exactly one GitHub repository. Two repositories, or none, leave the mention as text, because the number could belong to either. A full https://github.com/.../pull/42 link always opens. The agent includes that full URL when it creates a pull request.

A pull request whose repository is not one of this workspace's roots is read-only here. You can still read the remote diff; Checkout, Merge, and Fix with agent stay disabled, because those act on a local clone.

Act on the pull request

When this workspace owns the repository, the tab can:

• Merge with squash. The confirm row can queue Auto-merge, which lands once the base branch's requirements are met, or Admin, which bypasses branch protection and asks you to confirm first. If GitHub refuses because the branch is not mergeable, the failure row offers those two. If it cannot merge for another reason, the button stays and says why: the pull request is a draft, it is already merged or closed, or checks have not passed.
• Revert a merged pull request.
• Mark ready for review, or convert an open pull request back to a draft.
• Close or Reopen.

Each of those leaves a result row on the tab, so the outcome is not only a toast. A failure stays there with Retry for that same action. Request reviewers takes GitHub logins, comma-separated, and asks gh to add them.

Checks

The Checks tab opens with a decision: merge blocked, still running, or passed. A required check is badged, and a failed required check is marked merge-blocking. Refresh reloads the rollup. A failed or pending check offers Retry, and Details opens that check on GitHub.

Changes and commits

Changes is the remote pull request diff, not your local checkout — the header says so. Search the file list, or filter to added, modified, deleted, or renamed.

Commits can be searched. Copy a SHA, open the commit, or open the compare of that commit against the pull request's base. Those links are built from the pull request's own URL, so a GitHub Enterprise host keeps working.

Run AI Review

Run AI Review sends the PR's own diff to a cloud model. It reads gh pr diff for that pull request, so the clone does not have to be on the PR branch. The pass looks for bugs, security smells, regressions, and any Code Review Rules in AGENTS.md.

• You need a cloud model and key in Settings → Models. A local-only model cannot run this pass.
• Progress shows Fetching the diff… then Reviewing the diff…, an elapsed clock after a few seconds, and Cancel. Switching tabs does not stop it.
• A review that fails is a framed headline plus Retry, with the raw diagnostic in a disclosure — not a toast that fades.
• Findings stay on the tab when you leave and come back, labelled with how long ago they landed. If the PR or branch changed under them, the list is marked stale until you re-run.
• Nothing in the working tree is modified. The review is one model call over the diff.

Source Control can run the same kind of pass against base...HEAD in this clone, without a pull request. That path reviews whatever is checked out, not a remote PR, and uses the same in-flight and failure row as the PR tab.

Open a finding

Click a finding to open that path at the reported line in the owning root. A foreign PR cannot open paths: there is no local tree to join them onto.

Fix with agent

A finding is written against the PR's post-image — the tree after the PR's commits. Handing it to an agent while this clone sits on main would edit a file that does not contain that line.

So Fix with agent (and Fix all) is refused unless the owning root is on the PR's head branch. If the branch cannot be read, the gate fails closed and offers Checkout. After Checkout, the buttons unlock.

When a fix is allowed:

• Fix with agent starts an Agent-mode run for that finding, or steers an in-flight run instead of starting a second one.
• Fix all sends up to eight findings, errors first. A longer list is truncated on purpose; the prompt says how many were dropped.
• Findings are treated as data, not instructions. The run still uses the ordinary tool allowlist.
• Watch the run in chat. The PR tab's Changes view is the remote diff, not the local edits.

Under Review mode, those edits wait as pending patches in the Changes panel. The toast says so. After a fix is handed off, the findings list is labelled as from before those edits — re-run the review to refresh it.

Headless review

vortex review is the same idea from a terminal or CI job: diff HEAD against a base, send it to a cloud model, honour Code Review Rules. It does not open a PR tab and it does not start a fix. See Headless CLI.

vortex review --json --base main --fail-on error

Next steps

• Review mode — pending patches for the edits a fix produces.
• Headless CLI — vortex review as a CI gate.
• Models and keys — the cloud key AI Review needs.

Get an invite

Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite and a download link.