AGR — Agent-Guided Reviews

Turn a list of changed files into a review you can follow.

AGR opens agent-authored review steps in VS Code's native diff editor, with short notes and saved progress. Review a feature in a meaningful order, and revisit different parts of the same file in separate sections.

Your Claude Code or Codex agent creates .agr/<name>.json in the Git repository root. Use AGR: Switch Review to choose a walkthrough; progress is saved independently for each review.

Start a review

1. Open a trusted local Git repository in VS Code.

2. Run AGR: Install Agent Skills from the Command Palette, then choose Globally or This repository.

3. Ask Claude Code or Codex:

   Use the agr skill to create a guided review of my uncommitted changes. Split different concerns into separate steps and keep the review notes short.

4. Open AGR in the activity bar and click a step to see its diff and notes.

5. Mark the step reviewed using its checkbox or check action. Use the sidebar arrows for previous and next steps.

Repository skills are installed in .claude/skills/agr/ and .agents/skills/agr/. Start a fresh agent session if necessary. Existing skills are not overwritten. The helper requires Node.js 22+ and Git; the extension requires VS Code 1.95+.

Review the scope you need

• Uncommitted: staged and unstaged edits together, compared with HEAD.
• Staged: exactly what is in the Git index.
• Unstaged: saved working files compared with the index.
• PR or branch: merge-base compared with the feature tip.
• Commit range: an explicit base and head.
• Mixed: several comparisons, with optional file or directory limits.

Give your agent a PR link, branch name, or description of what you want reviewed. The agent records the chosen scope in the guide. For remote reviews, it fetches the Git objects using its existing tooling; AGR reads them locally without checking out another branch.

Progress that follows the changes

The sidebar nests checkable filenames under numbered sections and change groups, with a progress bar above the list. A file can appear in multiple steps. Each opens the complete native file diff at its relevant lines, while highlighting and review progress remain scoped to that step. Your notes and review progress are saved in .agr/<name>.json. Changed code, notes, or comparison baselines can require another review. Uncovered changes within the guide's scope appear under Unguided changes.

PR and branch reviews pin their commits. Ask the agent to regenerate the guide after remote updates. Default local comparisons follow HEAD. Diffs show saved snapshots; reopen a step to see newer saved edits. Unsaved buffers are excluded. Binary changes are listed for inspection in another viewer.

Commands

Search for AGR in the Command Palette to install skills, export a change snapshot, refresh the guide, open its JSON file, navigate steps, switch reviews, or select a repository in a multi-root workspace.

Privacy and local files

AGR works locally by default, collects no telemetry, and requires no model API key. PR guides from the updated skill offer Enable sync or Keep local when opened. AGR remembers your choice. Optional AGR: Connect GitHub PR uses your gh login to sync fully reviewed files to GitHub’s Viewed checkboxes. Local progress saves before background sync; failures offer Retry. AGR: Disconnect GitHub PR disables sync. The first version supports one complete, pinned github.com PR comparison. Your chosen agent handles generation under its own settings and credentials. AGR writes guide progress and, when requested, skill files or an exported snapshot. It does not stage or commit changes.

Guide artifacts are excluded from their own review, but remain ordinary files in Git. Add .agr/ to your Git ignore configuration if you want to keep them local.

Version 1.1 layout

Use named files such as .agr/checkout-flow.json and .agr/pr-142.json. The picker shows scope, progress, and stale or unavailable status. Root agr.json is no longer read: move existing guides into .agr/ and update the agent skill.

Local reviews can become stale after edits or commits. Their notes remain accessible, but old local file contents are not archived. Pinned reviews remain usable while their Git objects are available; fetch missing commits when needed.

Skill installation location

AGR: Install Agent Skills asks whether to install Globally or in This repository. Global installation works without an open project and writes to ~/.agents/skills/agr/ for Codex and ~/.claude/skills/agr/ for Claude Code. If CLAUDE_CONFIG_DIR is set in VS Code’s environment, its directory replaces ~/.claude. Repository installation writes both skill folders under the selected Git root. Canceling the prompt writes nothing.

Existing skills are not overwritten. Preserve customizations and move existing copies aside before reinstalling. Older repository skills may take precedence over a global installation, so update or remove those copies when switching to global skills. Review files always stay in each project’s .agr/ folder. Start a fresh agent session after installing.

Help

If no review appears, check that the guide is saved directly inside .agr/ in the selected Git repository root. Use AGR: Refresh after generating it. For stale steps, regenerate the guide against the latest changes.

Usage and troubleshooting · Source and issues · MIT license

AGR offers to update existing agent skills when the bundled skill content changes. Use AGR: Update Agent Skills to check manually. Choose the copies to update; the original folders are backed up outside the skill-discovery directories.

Upgrading from AGR 1.x

AGR 2.0 uses nested version 2 guides. Run AGR: Update Agent Skills after updating the extension. Existing version 1 guides migrate in place when their changes can be resolved, preserving valid approvals. Older extensions and helpers cannot read version 2 guides. See the migration guide.

GitHub discussions

Linked PR guides automatically load existing threads into the native diff. Post individual inline comments and replies, or edit your own comments. Each Post to GitHub or Save to GitHub action publishes immediately; AGR does not submit an approval or create a pending review. Use Refresh GitHub Comments for updates and Browse GitHub Discussions for outdated threads.

The sidebar includes an Open PR link, a short inline description, a Scope row, and Open Summary for the full Markdown description.