All guides

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:

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.

It doesn’t even need a branch. Ask “Ask me to review your uncommitted changes” for work the agent hasn’t committed yet, or “Ask me to review that commit” for a single commit.

You can also open these reviews yourself, from the session’s Git log tab. Select Uncommitted changes for the work not yet committed, a commit for that commit, or Review branch for the whole branch. Every one of them opens in the Review Room, and your review goes back to the agent session in that worktree. Without a running agent session there, the rows say why they are off.

A commit you open by selecting it is replaced by the next commit you select. To keep it, comment on it or mark a file Viewed.

2. Read the author’s briefing

The author attaches a briefing. It shows labelled Author’s briefing:

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.

These are threads in the review. Questions an agent asks you while it works show above its terminal instead. See Open questions from your agent.

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:

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, in the round view: your feedback with the changes that answer it, then the other changes since your review. The picker in the layer bar reads “Round N · since ‹date›”; pick All changes there for the whole PR. Open threads carry over, and so do Viewed marks on files that didn’t change. See Review the next round.

When a local branch becomes a PR, the review continues as the next round of that PR. A review of uncommitted changes or of one commit stays on its own.

feat/late-fees Author
? 1

Needs you · Should the grace period count calendar days or business days?

▸ Context
Calendar daysBusiness days Reply… 1 min ago

Needs you · Should the grace period count calendar days or business days?

▸ Context
Calendar daysBusiness days Reply… 1 min ago
Author:
Your review of the late-fee change is open. One thing I can't settle from the code.
Author:
Calendar days, then. Updating the threads and pushing.
The Author asks, and the session needs you.
You pick Calendar days.
The card is gone. Your answer reaches the Author as a message.