> ## 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, Code Tours, and Guided Reviews

> Run a code review, Code Tour, Guided Review, or custom review skill with an installed local agent CLI and understand its provider guardrails.

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.

Plannotator does not automatically post completed job findings to GitHub or GitLab or send them to the coding agent. You remain responsible for checking each finding and choosing the review destination. The provider process still has the permissions described below while the job runs.

## 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. Codex is the exception: Plannotator maintains the Codex model and reasoning-effort choices to match the current Codex CLI. A provider can appear installed but fail to launch if its CLI is signed out, lacks a configured model, or cannot access the repository.

## Understand provider guardrails

Plannotator tells every review job not to modify files or post comments. Those prompt instructions do not enforce read-only execution. The available guardrails depend on the provider:

* Codex runs with `--full-auto` in its workspace-write sandbox.
* Cursor runs in Ask mode with its sandbox enabled by default. If Cursor's sandbox cannot start on a restricted Linux system, set `PLANNOTATOR_CURSOR_SANDBOX=0` or set `"cursorSandbox": false` in `config.json` to omit the sandbox flag. In that mode, write protection depends on Ask mode and your Cursor configuration.
* OpenCode runs with its planning agent and retains shell access.
* Pi excludes its direct edit and write tools but retains Bash access.
* Claude receives file-reading tools and inspection-oriented Git and forge command patterns. Direct file-writing tools, WebFetch, WebSearch, and general-purpose shells are denied, but some allowed Git and forge patterns are broader than a strict read-only subcommand list.
* GitHub Copilot denies its direct write tool and specific high-risk version-control and forge operations. It allows Git and forge command families and auto-denies other shell tools.

Treat provider output as untrusted review evidence and inspect each claimed issue. Run a review job only where the selected provider's permissions and your repository isolation are acceptable.

## 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. See [Review GitButler Workspaces, Stacks, and Branches](/open-source/workflows/gitbutler#keep-annotations-tied-to-the-right-comparison) for this comparison boundary. 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).

## Reopen a Guided Review

Plannotator saves each successfully generated Guided Review under the data directory. Open **Previous guides** in the Agents tab to reopen or delete one. The list shows its title, age, and section progress.

Section completion persists with the saved guide. A completed section starts collapsed when you reopen it, but you can expand it without changing the state of other sections. Selecting a file chip, annotation, or AI citation expands the containing section and file, focuses it, and scrolls it into view.

A saved guide records the repository commit present when it was generated. If the repository has moved to another commit, the saved-guide list and reopened guide mark it **Diff changed**. Treat that warning as a reason to confirm that its summaries and file ranges still match the review.

Disable new guide writes with either setting:

```bash theme={null}
export PLANNOTATOR_GUIDE_HISTORY=0
```

```json theme={null}
{
  "guideHistory": false
}
```

Disabling history does not delete saved guides. Existing guide data remains readable through the local API, but the normal guide browser is hidden when AI features are disabled.

## 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. The selected provider's guardrails still apply.

Enabled review profiles are stored in `<data-directory>/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 on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.