self-review

KO | EN

gitlite — search

#react #typescript #llm #go #golang #android #docker #macos #windows #awesome #cli #kubernetes #awesome-list #mcp

(★ 37)

Desktop application to review your own changes in Linux and macOS

self-review Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# self-review <img align="right" src="./assets/icon.png" alt="self-review logo" title="self-review" width="100">

[![CI](https://github.com/e0ipso/self-review/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/e0ipso/self-review/actions/workflows/ci.yml)
 
https://github.com/user-attachments/assets/ada04c50-9107-4f0d-a1ee-789016bbf2de

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.

![Screenshot](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshot.png)

## 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.

<details>
<summary>Learn more</summary>

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.

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

| | |
|---|---|
| ![Plan diff view](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc1-plan-diff.png) | ![Rendered markdown view](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc1-rendered.png) |
| Raw diff of the plan file | Rendered markdown for easier reading |
| ![Inline comment on plan](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc1-inline-comment.png) | |
| Comment attached to a specific section | |

</details>

### Reviewing AI-Generated Code

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

<details>
<summary>Learn more</summary>

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.

```bash
# Review staged changes
self-review --staged

# Review changes between branches
self-review main
```

| | |
|---|---|
| ![Split diff view](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc2-split-diff.png) | ![Inline comment](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc2-comment.png) |
| Side-by-side diff view | Inline comment on a specific line |
| ![Code suggestion](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc2-suggestion.png) | |
| Suggestion with proposed replacement code | |

</details>

### 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.

<details>
<summary>Learn more</summary>

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.

```bash
# Review all changes in the working tree
self-review
```

| | |
|---|---|
| ![File tree overview](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc3-file-tree.png) | ![Categorized comments](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc3-categorized.png) |
| File tree showing the directory structure | Comments tagged with different categories |
| ![Category selector](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc3-categories.png) | |
| Custom category selector for organizing notes | |

</details>

### 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.

<details>
<summary>Learn more</summary>

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.

The critique run also produces a **walkthrough guide** sidecar (`review.guide.xml`) via the `/self-review-guide` skill, which critique invokes as its first step (the guide skill also runs standalone). When self-review finds the guide next to its output file, the file tree reorganizes into named, ordered reading groups with rationales, each file gets a one-line description of its role in the change, and an overview appears before the first file. A Guided/Flat toggle always restores the plain alphabetical view, every file stays reachable, and a missing or invalid guide simply falls back to the flat view.

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.

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

| | |
|---|---|
| ![Pre-loaded AI comments](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc4-ai-comments.png) | ![Mixed AI and human comments](https://raw.githubusercontent.com/e0ipso/self-review/main/docs/screenshots/uc4-mixed-comments.png) |
| AI-generated comments loaded from XML | Your own comments added alongside AI feedback |

</details>

## Installation

### macOS

Install with [Homebrew](https://brew.sh/):

```bash
brew install --cask e0ipso/self-review/self-review
```

To upgrade later:

```bash
brew upgrade --cask self-review
```

<details>
<summary>Advanced Installation Instructions</summary>

Prefer to install manually? Download the latest release from
[GitHub Releases](https://github.com/e0ipso/self-review/releases).

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

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

</details>

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

```bash
xattr -cr /Applications/Self\ Review.app
```

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

```bash
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
```

### Linux

Install with [Homebrew](https://brew.sh/):

```bash
brew install e0ipso/self-review/self-review
```

To upgrade later:

```bash
brew upgrade self-review
```

<details>
<summary>Advanced Installation Instructions</summary>

Prefer to install manually? Download the latest release from
[GitHub Releases](https://github.com/e0ipso/self-review/releases).

**Debian/Ubuntu** — download the `.deb` package and install it:

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

**Fedora/RHEL** — download the `.rpm` package and install it:

```bash
# 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.

</details>

## 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:

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

### Examples

```bash
# 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

# Review a remote pull/merge request by URL
self-review https://github.com/owner/repo/pull/42
self-review https://gitlab.com/group/project/-/merge_requests/7
```

### Reviewing a remote PR/MR

Hand self-review a GitHub pull request or GitLab merge request URL (self-hosted GitLab works
too — the forge is detected from the URL shape) and review it in the same UI, existing
discussion threads included. The review is still written to a local `review.xml`; nothing is
ever sent back to the forge.

Under the hood the diff is materialized through local git: if you run the command from inside a
clone of that repository, self-review reuses it (it only fetches refs — your working tree is
untouched); otherwise it creates a temporary blobless clone under your system temp directory
and removes it when you close the app. Private repositories work through git's own credentials
(SSH keys or credential helpers — `gh auth setup-git` / `glab auth git-credential` wire your
forge CLI login into git). The `gh` / `glab` CLIs are only needed to sync the PR/MR discussion
threads; without them the review itself still works at full fidelity, just without the threads.

There is also a headless subcommand that fetches the discussion threads into a review file
without opening a window:

```bash
# Write the PR's discussion threads to ./review.xml (no window)
self-review fetch-comments https://github.com/owner/repo/pull/42

# Include threads GitLab marks resolved (default is unresolved only)
self-review fetch-comments https://gitlab.com/group/project/-/merge_requests/7 --all-threads
```

## Assistant Skill

self-review ships with an AI assistant skill that closes the feedback loop: it reads your review XML,
prioritizes the feedback, and executes the changes. It works with any assistant that supports
skill directories, such as **Claude Code**, **Codex**, **OpenCode**, and others.

The repo also ships two companion skills under `.agents/skills/`: `self-review-critique`
(pre-generates a review for you to curate) and `self-review-guide` (generates the walkthrough
guide sidecar that powers guided mode; critique runs it as its first step). Install them the
same way as `self-review-apply` below.

### Install

Copy the skill directory into your project:

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

### Usage

After running self-review and producing a `review.xml`, invoke the skill in your assistant:

```
/self-review-apply review.xml
```

<details>
<summary>Details</summary>
Your project should end up with:

<code>
your-project/
└── .agents/
    └── skills/
        └── self-review-apply/
            ├── SKILL.md
            └── self-review-v3.xsd
</code>

The skill will:

1. Read the XSD schema to understand the review format
2. Parse your review XML
3. Categorize and prioritize comments, honouring `--min-severity` / `--min-confidence` floors when given
4. Output a task plan showing parallel and sequential work groups
5. Execute the changes, applying suggestions first, then addressing open-ended
   feedback

</details>

## 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`)
- `guide-file`: path to the walkthrough guide sidecar (default: derived from `output-file` as `<output-basename>.guide.xml`, e.g. `review.guide.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).

<details>
<summary>Example: Custom comment categories</summary>

```yaml
# .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'
```

</details>

See [docs/PRD.md](docs/PRD.md#7-configuration) 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.
  The one opt-in exception: reviewing a remote PR/MR by URL fetches that repository through git
  and reads its discussion threads — and even then, nothing is ever sent to the forge.
- **AI-native output.** The XML format is designed to be parsed by LLMs, with an XSD schema they can
  reference for structure.

self-review

self-review Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

self-review

self-review Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README