> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run agent reviews

> Run read-only code reviews, Code Tours, Guided Reviews, or custom review skills with your installed local agent CLIs.

Open the **Agents** tab in a code review to run a separate agent over the current change. Job progress and logs stream into Plannotator. Completed findings appear as review annotations, where you decide what to keep, edit, copy, or send.

Agent jobs do not post to GitHub or GitLab and do not send feedback to the coding agent automatically. You remain responsible for checking each finding and choosing the review destination.

## Choose a review job

* **Code Review** looks for correctness, security, maintainability, and other concrete problems in the current change.
* **Code Tour** creates a narrated walkthrough with checkpoints. It runs with Claude or Codex.
* **Guided Review** organizes the change into ordered sections with summaries and live diffs. It can run with any supported review engine.
* **Custom review** runs a review profile from an enabled global agent skill.

You can run more than one engine, watch logs while each job runs, stop a running job, and compare their findings in the same review.

## Install and authenticate an agent CLI

Plannotator detects engines by checking for their command on `PATH`. The command must also be authenticated and have a usable model configuration.

| Engine             | Command Plannotator detects | Supported jobs                        |
| ------------------ | --------------------------- | ------------------------------------- |
| Claude Code        | `claude`                    | Code Review, Code Tour, Guided Review |
| Codex CLI          | `codex`                     | Code Review, Code Tour, Guided Review |
| Cursor CLI         | `agent`                     | Code Review, Guided Review            |
| OpenCode           | `opencode`                  | Code Review, Guided Review            |
| Pi                 | `pi`                        | Code Review, Guided Review            |
| GitHub Copilot CLI | `copilot`                   | Code Review, Guided Review            |

Model choices come from the installed provider where supported. A provider can appear installed but fail to launch if its CLI is signed out, lacks a configured model, or cannot access the repository.

## Review agents are read-only

Plannotator tells every review job not to modify files and starts each provider in its available read-only review posture. The exact guardrail belongs to the provider:

* Codex uses a read-only sandbox.
* Cursor runs in Ask mode with its sandbox enabled.
* OpenCode runs with its planning agent.
* Pi excludes its edit and write tools.
* Claude and GitHub Copilot receive restricted inspection-oriented tool and command policies.

These jobs are reviewers, not implementation agents. Treat provider output as untrusted review evidence, inspect each claimed issue, and make code changes only through your normal coding-agent or editor workflow.

## Run agents on the intended comparison

The job receives the comparison currently open in Plannotator. Choose the correct Git mode, Jujutsu revision, GitButler view, or pull-request scope before launching it.

For GitButler Stack and Branch reviews, the prompt identifies the on-screen patch as authoritative because filesystem reads can see other applied stacks or later branch layers. For stacked pull requests, an agent can review either **Layer** or **Full stack** when the local checkout exists.

A GitHub pull request or GitLab merge request needs the temporary local checkout that Plannotator prepares by default. Agent jobs are unavailable with `--no-local` or after checkout preparation fails. See [Review pull requests and merge requests](/open-source/workflows/pull-requests).

## Add a custom review

Choose **Add a review** in the Agents tab to enable a global skill as a review profile. Plannotator searches global skill directories, including:

* `~/.claude/skills`
* `~/.codex/skills`
* `~/.agents/skills`
* The XDG agents skills directory when configured

Repository-local skills are intentionally ignored for custom reviews because a fork or downloaded repository should not be able to supply the prompt that reviews itself.

If the skill contains `SKILL.md`, its body replaces the built-in review prompt for that profile. Plannotator reads it again at launch, so saved edits apply to the next job. The skill can refer the reviewer to supporting files in its own directory, but the review remains read-only.

Enabled review profiles are stored in `~/.plannotator/review-skills.json`. Use the Agents tab to manage this file instead of editing it by hand.

For quick questions about selected lines instead of a full background review, use [Ask AI during a review](/open-source/workflows/ask-ai).

Last verified against Plannotator OSS v0.23.1 on July 18, 2026. Maintained by the Plannotator project.