Review an agent's work and merge the PR
How to read an agent's execution, give feedback, review the pull request, and handle edge cases before merging.
Agents never push code to your main branch or merge pull requests without you. This guide covers what to do between "implementation done" and "PR merged".
Reading the implementation
While the agent is working, or after it finishes, you can see what it did in two places:
The task thread shows the agent's tool calls in sequence — what files it read, what commands it ran, what edits it made. Scan this to understand the agent's reasoning, not just the output.
The live desktop view shows the agent's screen in real time via video stream. You can click into the stream and type directly to the agent if you want to redirect it mid-implementation.
Reviewing the diff
When a task reaches Review status, click Open PR to create a pull request in your repository. From there, use your normal review process — GitHub / GitLab / Bitbucket diffs, CI results, preview deployments.
Things to look for in an agent diff:
- Scope creep — the agent touched files you didn't expect. Read the diff, not just the summary.
- Test coverage — did the agent write tests? Are they meaningful or just stubs?
- Existing patterns — did the agent follow your project's conventions? If not, see Giving feedback.
Where the PR title and description come from
You don't write the pull request title and description, and neither does the agent write them into GitHub directly — Helix opens the PR and fills it in from a file the agent commits alongside the code.
When you approve an implementation, the agent is asked to write pull_request.md under the task's directory in the helix-specs branch, in this shape:
# Clear, concise PR title
## Summary
What changed and why.
## Testing
What you tested and the result.The first line is the title — a leading # is stripped. Everything after the first blank line becomes the PR description.
If the task changes more than one repository, the agent writes one file per repository — pull_request_<repo-name>.md — each describing only that repository's changes, and Helix falls back to the generic pull_request.md if a per-repo file is missing. All of these live on the same helix-specs branch, so a single push updates every open PR the task owns.
This matters for review in one practical way: the PR text is regenerated from the file. If a description is wrong or thin, you don't have to edit it on GitHub and hope it sticks — ask the agent to fix the file. The next push to helix-specs rewrites the title and description on every open PR for that task.
Giving feedback
If the implementation is wrong or incomplete, go back to the task and tell the agent in plain language:
The validation fires on every keystroke, which is annoying. It should only fire on blur (when the user leaves the field).
The agent will read your feedback, reopen the sandbox, fix the issue, and push to the same PR branch.
You can give feedback as many times as needed. Each round trips through the same plan→implement cycle, so significant changes go through another approval step.
Feedback attached to specific lines
Feedback can also be tied to particular lines of a file in the task's workspace, rather than described from memory in prose.
Line feedback does not reach the agent as you write it. It is held until you send your next message to the task, and then travels as part of that message — so several comments, on several files, arrive together with whatever you typed alongside them. A message carrying only comments and no prose of your own is still sent.
The agent does not receive a file name and a line number to go and look up. Each comment arrives as a structured block that carries the range and a copy of the lines it refers to:
<review_comment filePath="api/server.go" rangeLabel="L42 to L45" ...>
This should return early instead of nesting the happy path.
```go
if err != nil {
return err
}
```
</review_comment>
Two things follow from that, and they are the reason to prefer line feedback over describing a problem in prose:
- The agent sees the code as it was when you commented. The excerpt is quoted into the message, so your feedback still makes sense if the agent has since changed that part of the file, and it cannot resolve the wrong lines after an edit shifts them.
- The range is unambiguous. You are not relying on the agent to work out which occurrence of a pattern you meant.
Requesting changes on the PR
If you request changes via GitHub's review UI, the agent won't automatically see them — you need to go back to the Helix task and explicitly describe what needs fixing. Copy-paste the relevant comments from GitHub into the task thread.
Handling merge conflicts
If your main branch moved while the agent was working:
- Go to the task
- Tell the agent: "There are merge conflicts on the PR. Please rebase against main and resolve them."
- The agent will rebase and force-push to the branch
Wait for CI to pass again, then merge.
Merging
Merge the PR from your source control provider — Helix doesn't merge for you. Once merged, Helix marks the task as Done (on the next sync).
If something went badly wrong
If the agent made a mess and you want to start fresh:
- Close the PR without merging — the branch stays in your repo but the agent won't touch it again
- Delete the agent's branch if you want a clean slate
- Reopen the task with updated guidance, or write a new task
The agent's commits are on a separate branch; your main branch was never touched.