self-review

demo-recording.webm

A local code review tool for developers working with AI coding agents.

When you use tools like Claude Code to generate code changes, you need to review those changes before accepting them. Today your options are: push to GitHub (exposing unfinished work to a remote server) or squint at diffs in the terminal.

self-review gives you GitHub's pull request review UI on your local machine — no remote, no account, no setup. Launch it from the terminal, review the diff, leave comments and suggestions, close the window. Your feedback is written to a file as structured XML that you feed directly back to your AI agent.

Use Cases

Reviewing AI Assistant Plans

Review rendered markdown plans from AI assistants and leave inline feedback on specific sections. Feed the structured XML back to improve the plan.

Learn more

Plans generated by AI assistants are often long markdown documents. Reviewing them in the terminal is difficult — by the time you reach the end, you've lost track of feedback you had at the beginning. self-review solves this with two features: rendered markdown view for readability, and in-context comments attached to specific paragraphs and sections.

Open the plan file in self-review, switch to the rendered view, and comment directly on the sections that need changes. The XML output preserves the exact location of each comment, so the AI assistant knows precisely what to fix.

# Review an AI-generated plan (as an untracked new file)
self-review

Raw diff of the plan file	Rendered markdown for easier reading
Comment attached to a specific section

Reviewing AI-Generated Code

Review code diffs in a GitHub-style split view with inline comments and suggestions, all without leaving your machine.

Learn more

After an AI assistant generates code changes, you need to review the diff before accepting it. You could push to GitHub and use a pull request, but that has drawbacks:

• Slower iteration — push, wait for CI, pull down comments, address them, push again
• Noisy git history — "address review comments" commits clutter the remote
• Privacy — unfinished or experimental code is exposed to the remote server and your team
• Wasted CI — intermediate pushes burn CI minutes on code that isn't ready

With self-review, you review locally. The code that eventually leaves your machine is code you own intellectually — you've read it, understood it, and refined it. Your team only sees the finished result.

# Review staged changes
self-review --staged

# Review changes between branches
self-review main

Side-by-side diff view	Inline comment on a specific line
Suggestion with proposed replacement code

Codebase Exploration

Open any directory and annotate the code with categorized comments — questions, improvements, documentation gaps — then feed the XML to an LLM to act on your notes.

Learn more

When onboarding to a new project, you need to understand the codebase before you can contribute. self-review lets you open a directory, browse the files, and leave categorized notes as you go. Tag comments as question, improvement, or needs-docs using custom categories defined in .self-review.yaml.

Once you're done, the XML file contains all your annotations with file paths, line numbers, and categories. You can feed this to an LLM and ask it to: create tickets for the improvements, generate documentation for the gaps, or explain the parts you didn't understand. No need to awkwardly copy file names, line numbers, and class names into a prompt.

# Review all changes in the working tree
self-review

File tree showing the directory structure	Comments tagged with different categories
Custom category selector for organizing notes

AI-Assisted Review

Have an AI assistant pre-generate a review, then open it in self-review to validate, edit, or discard each comment before feeding it back.

Learn more

Instead of starting your review from scratch, you can ask a second AI assistant to critique the changes first. Using the /self-review-critique skill included in this repo, the assistant generates an XML review file compatible with self-review. You then open self-review with --resume-from to load those comments.

From there, you curate the review: discard comments that are wrong, keep the ones that are useful, and add your own feedback on top. The final XML contains exactly the comments you approved — AI-suggested minus what you removed, plus what you added — ready to feed back to the coding assistant.

# Generate an AI review, then validate it
/self-review-critique --staged
self-review --staged --resume-from review.xml

AI-generated comments loaded from XML	Your own comments added alongside AI feedback

Installation

Download the latest release from GitHub Releases.

Linux (Debian/Ubuntu)

Download the .deb package and install it:

# Replace X.Y.Z with the version you downloaded
sudo dpkg -i self-review_X.Y.Z_amd64.deb

The self-review command will be available system-wide.

Linux (Fedora/RHEL)

Download the .rpm package and install it:

# Replace X.Y.Z with the version you downloaded
sudo rpm -i self-review-X.Y.Z-1.x86_64.rpm

The self-review command will be available system-wide.

macOS

Download the .zip archive, extract it, and move the app to your Applications folder:

unzip Self.Review-darwin-*.zip -d /Applications

Because the app is not yet code-signed, macOS Gatekeeper will flag it as damaged. Remove the quarantine attribute before opening:

xattr -cr /Applications/Self\ Review.app

To use the self-review command from the terminal, create a wrapper script:

sudo tee /usr/local/bin/self-review > /dev/null << 'SCRIPT'
#!/bin/bash
exec "/Applications/Self Review.app/Contents/MacOS/Self Review" "$@"
SCRIPT
sudo chmod +x /usr/local/bin/self-review

How it works

Instead of seeing your changes with git diff <arguments> execute self-review <arguments>. This will open the app and will record all the feedback in an XML file (review.xml by default).

You can continue your saved review if you didn't finish it:

# Resume a previous review
self-review --staged --resume-from review.xml

Examples

# Review staged changes — produces ./review.xml by default
self-review --staged

# Review changes between branches
self-review main

# Review the last commit
self-review HEAD^

# Review the current changes
self-review

Claude Code Skill

self-review ships with a Claude Code skill that closes the feedback loop: it reads your review XML, prioritizes the feedback, and executes the changes.

Install

Copy the skill directory into your project:

# From the self-review repo (or download the folder from GitHub)
cp -r .claude/skills/self-review-apply /path/to/your/project/.claude/skills/

Usage

After running self-review and producing a review.xml, invoke the skill in Claude Code:

/self-review-apply review.xml

Details

Your project should end up with: your-project/ └── .claude/ └── skills/ └──self-review-apply/ ├── SKILL.md └── self-review-v1.xsd

The skill will:

1. Read the XSD schema to understand the review format
2. Parse your review XML
3. Categorize and prioritize comments (security > bug > style > nit)
4. Output a task plan showing parallel and sequential work groups
5. Execute the changes — applying suggestions first, then addressing open-ended feedback

Configuration

Customize self-review with YAML configuration files:

• User config: ~/.config/self-review/config.yaml — personal preferences for all projects
• Project config: .self-review.yaml — per-project settings (committable)

Project config overrides user config, which overrides built-in defaults.

Available options

• theme: light, dark, or system (default: system)
• diff-view: split or unified (default: split)
• font-size: editor font size in pixels (default: 14)
• output-file: path for the review XML output (default: ./review.xml)
• ignore: file patterns to exclude from diff (gitignore-compatible syntax; defaults cover common vendor/build dirs and lock files)
• categories: custom comment tags (see example above)
• default-diff-args: default arguments passed to git diff
• show-untracked: show new files not yet added to git (default: true)
• word-wrap: wrap long lines in the diff viewer (default: true)
• max-files: maximum number of files before the large payload guard triggers (default: 500). Set to 0 to disable.
• max-total-lines: maximum total diff lines before the large payload guard triggers (default: 100000). Set to 0 to disable.

When either threshold is exceeded, a confirmation dialog appears. Cancelling exits the app; continuing enters large-payload mode with lazy content loading (file hunks are fetched on demand as you scroll).

Example: Custom comment categories

# .self-review.yaml
categories:
  - name: bug
    description: 'Likely defect or incorrect behavior'
    color: '#e53e3e'
  - name: security
    description: 'Potential security vulnerability'
    color: '#d69e2e'
  - name: nit
    description: 'Minor style or formatting suggestion'
    color: '#718096'
  - name: question
    description: 'Clarification needed'
    color: '#3182ce'

See docs/PRD.md for complete documentation.

Design principles

• CLI-first. Launched from the terminal, writes review output to a file. Behaves like a Unix tool.
• One-shot. Open → review → close → done. No servers, no persistent state.
• Local-only. No network access, no accounts, no telemetry. Your code stays on your machine.
• AI-native output. The XML format is designed to be parsed by LLMs, with an XSD schema they can reference for structure.