Review Agents

Optio can automatically launch a code review agent as a subtask of any coding task. The review agent examines the PR, checks for issues, and posts a GitHub review. This provides an automated first pass before human reviewers look at the code.

How It Works

1. A coding task opens a PR and transitions to pr_opened
2. The PR watcher detects the trigger condition (CI pass or PR open, depending on config)
3. A review subtask is created with taskType: "review" and blocksParent: true
4. The review agent runs in the same repo pod, scoped to the PR branch
5. The review agent posts its findings as a GitHub PR review
6. The parent coding task waits for the review subtask to complete before advancing

Enabling Reviews

Reviews are configured per repository. Navigate to Repos → (select repo) → Settings.

Trigger Options

The reviewTrigger setting controls when the review agent is launched:

Review Model

The reviewModel setting allows you to use a different (often cheaper) model for reviews. Since reviews are primarily reading and commenting on code rather than writing it, a lighter model often works well.

Custom Review Prompts

Override the default review prompt to match your team's review standards. The prompt template supports the same variable syntax as coding prompts, plus review-specific variables.

Review Variables

Example Custom Review Prompt

You are reviewing PR #{{PR_NUMBER}} in {{REPO_NAME}}.

Read the original task description from {{TASK_FILE}} to understand
what was requested.

Review the PR diff and check for:
1. Correctness — does the implementation match the task requirements?
2. Security — any SQL injection, XSS, or auth bypass risks?
3. Performance — any N+1 queries, unnecessary re-renders, or memory leaks?
4. Testing — are there adequate tests? Run "{{TEST_COMMAND}}" to verify.
5. Code style — does it follow the existing patterns in the codebase?

Post a GitHub review with your findings. If everything looks good,
approve the PR. If there are issues, request changes with specific,
actionable feedback.

Manual Review Trigger

You can manually trigger a review for any task that has an open PR, regardless of the automatic review settings:

curl -X POST https://optio.example.com/api/tasks/{taskId}/review \
  -H "Cookie: optio_session=YOUR_SESSION_TOKEN"

This is also available as a button in the task detail view when the task is in pr_opened state.

Review as a Subtask

Reviews are implemented as subtasks of the parent coding task. This means:

• The review appears in the subtask list (GET /api/tasks/:id/subtasks)
• It has blocksParent: true, so the parent waits for it to finish
• It runs in the same repo pod, sharing the cloned repository
• It has its own logs, state transitions, and cost tracking
• When the review subtask completes, onSubtaskComplete() checks if the parent can advance

Auto-Resume on Review

When a review (human or agent) requests changes, Optio can automatically resume the coding agent to address the feedback. This is controlled by the per-repo autoResume setting (enabled by default).

The flow:

1. PR watcher detects a "changes requested" review
2. Task transitions to needs_attention
3. The review comments are extracted and used as the resume prompt
4. Task is re-queued and the agent picks up the review feedback
5. Agent pushes fixes and the cycle repeats

Cost Considerations

Review tasks have their own cost tracking. To control review costs:

• Use a lighter model for reviews (e.g., sonnet or haiku)
• Set maxTurnsReview per-repo to limit the number of agent turns
• Use on_ci_pass trigger to avoid reviewing code that won't build
• Monitor costs in the Costs dashboard, which breaks down spending by task type (coding vs review)

Next Steps