Reviewing your agent’s work

When an agent finishes a change, it can ask you for a review. Three parties then work on the same lines:

• The author: the agent that wrote the change. It knows where it is unsure.
• The Companion: a read-only agent that didn’t write the change. It has nothing to defend.
• You: you decide what ships.

This guide follows one review from the hand-over to your verdict.

1. The author asks for a review

Ask the agent when it thinks it is done: “Ask me to review this branch.” Or: “Open a draft PR and ask me to review it.”

The review opens as a tab in the agent’s workspace, in the background. The session’s dot turns amber, and its header shows Review ready. Select it to bring the review forward.

A review of a local branch needs no PR and no GitHub round trip.

2. Read the author’s briefing

The author attaches a briefing. It shows labelled By the author:

• What changed, why, and the impact.
• A reading order. It drives the Reading list in the outline until you run ☰ Overview.
• Evidence: the commands it ran, such as tests and the build, with an output excerpt. It shows as “Author ran”. SimpleEdit doesn’t run these commands again, so it never shows them as verified.

The briefing is the author’s own view. Select ☰ Overview for an independent one: it checks the briefing’s claims against the diff.

3. Start where the author was unsure

The author can pin its open questions to lines. Each question arrives as a thread on its line, so you start where it was least sure. Questions without a line become threads on the change as a whole.

4. Check a worry with the Companion

On a thread, pick Companion as the recipient and select Ask. For example: “Is this real? Who else calls this function?”

The Companion reads the code at the head of the change, also outside the diff, and answers in the thread. It can’t edit files or post anything. Your conversation with it stays private.

For a broader second opinion, select ⚡ Deep review. See Tuning Deep review.

5. Answer the author on the line

When you know what you want, switch the thread’s recipient to Author and select Ask. The message goes to the agent that wrote the change. It doesn’t cut into a running turn: SimpleEdit holds the question until the author’s current turn ends, then sends it as the author’s next prompt.

The author answers in the same thread. Ask it to fix the code there: “Yes, handle the empty list here, and add a test.”

Author is offered only while the author’s session runs.

6. Submit your review

1. For each comment you want to send, pick the PR (or Review on a local branch) as the recipient and select Draft. The Companion can propose the text: select Redraft from conversation, then Use this text or Keep mine.
2. Select Submit reviews… and set a verdict.
3. Submit.

Where the review goes:

• A local branch: “your review goes back to the session that asked for it, and nowhere else.” Nothing goes to GitHub.
• A PR your agent asked about: pick Send to the requesting session, Also post to GitHub as you, or both.

Only your drafts are sent, never the conversation behind them. The agent gets your verdict and comments and works on them. It treats them as your judgment, not as orders, so it may push back in a thread.

7. The next round

When the agent asks again after its fixes, the review opens as the next round: open threads and Viewed marks carry over, and Show only the new changes shows what changed since you last looked.

When a local branch becomes a PR, the review continues as the next round of that PR.

Related

• Reviewing a PR stack: the Review Room in full.
• Reviewing plans with SimpleEdit: the same flow, for a plan.
• Running a Workflow: review gates use this flow too.