{
"markdown": "# self-review ![\"self-review](\"./assets/icon.png\" "\\"self-review\\"")
\n\n[](https://github.com/e0ipso/self-review/actions/workflows/ci.yml)\n \nhttps://github.com/user-attachments/assets/ada04c50-9107-4f0d-a1ee-789016bbf2de\n\nA local code review tool for developers working with AI coding agents.\n\nWhen you use tools like Claude Code to generate code changes, you need to review those changes\nbefore accepting them. Today your options are: push to GitHub (exposing unfinished work to a remote\nserver) or squint at diffs in the terminal.\n\n**self-review** gives you GitHub's pull request review UI on your local machine, no remote, no\naccount, no setup. Launch it from the terminal, review the diff, leave comments and suggestions,\nclose the window. Your feedback is written to a file as structured XML that you feed directly back\nto your AI agent.\n\n\n\n## Use Cases\n\n### Reviewing AI Assistant Plans\n\nReview **rendered markdown** plans from AI assistants and leave **inline feedback** on specific sections. Feed the structured XML back to improve the plan.\n\n\nLearn more
\n\nPlans 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.\n\nOpen 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.\n\n```bash\n# Review an AI-generated plan (as an untracked new file)\nself-review\n```\n\n| | |\n|---|---|\n|  |  |\n| Raw diff of the plan file | Rendered markdown for easier reading |\n|  | |\n| Comment attached to a specific section | |\n\n \n\n### Reviewing AI-Generated Code\n\nReview code diffs in a **GitHub-style split view** with **inline comments and suggestions**, all without leaving your machine.\n\n\nLearn more
\n\nAfter 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:\n\n- **Slower iteration**, push, wait for CI, pull down comments, address them, push again\n- **Noisy git history**, \"address review comments\" commits clutter the remote\n- **Privacy**, unfinished or experimental code is exposed to the remote server and your team\n- **Wasted CI**, intermediate pushes burn CI minutes on code that isn't ready\n\nWith 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.\n\n```bash\n# Review staged changes\nself-review --staged\n\n# Review changes between branches\nself-review main\n```\n\n| | |\n|---|---|\n|  |  |\n| Side-by-side diff view | Inline comment on a specific line |\n|  | |\n| Suggestion with proposed replacement code | |\n\n \n\n### Codebase Exploration\n\nOpen 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.\n\n\nLearn more
\n\nWhen 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`.\n\nOnce 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.\n\n```bash\n# Review all changes in the working tree\nself-review\n```\n\n| | |\n|---|---|\n|  |  |\n| File tree showing the directory structure | Comments tagged with different categories |\n|  | |\n| Custom category selector for organizing notes | |\n\n \n\n### AI-Assisted Review\n\nHave an AI assistant **pre-generate a review**, then open it in self-review to **validate, edit, or discard** each comment before feeding it back.\n\n\nLearn more
\n\nInstead 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.\n\nThe 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.\n\nFrom 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.\n\n```bash\n# Generate an AI review, then validate it\n/self-review-critique --staged\nself-review --staged --resume-from review.xml\n```\n\n| | |\n|---|---|\n|  |  |\n| AI-generated comments loaded from XML | Your own comments added alongside AI feedback |\n\n \n\n## Installation\n\n### macOS\n\nInstall with [Homebrew](https://brew.sh/):\n\n```bash\nbrew install --cask e0ipso/self-review/self-review\n```\n\nTo upgrade later:\n\n```bash\nbrew upgrade --cask self-review\n```\n\n\nAdvanced Installation Instructions
\n\nPrefer to install manually? Download the latest release from\n[GitHub Releases](https://github.com/e0ipso/self-review/releases).\n\nDownload the `.zip` archive, extract it, and move the app to your Applications folder:\n\n```bash\nunzip Self.Review-darwin-*.zip -d /Applications\n```\n\n \n\nBecause the app is not yet code-signed, macOS Gatekeeper will flag it as damaged. Remove the\nquarantine attribute before opening:\n\n```bash\nxattr -cr /Applications/Self\\ Review.app\n```\n\nTo use the `self-review` command from the terminal, create a wrapper script:\n\n```bash\nsudo tee /usr/local/bin/self-review > /dev/null << 'SCRIPT'\n#!/bin/bash\nexec \"/Applications/Self Review.app/Contents/MacOS/Self Review\" \"$@\"\nSCRIPT\nsudo chmod +x /usr/local/bin/self-review\n```\n\n### Linux\n\nInstall with [Homebrew](https://brew.sh/):\n\n```bash\nbrew install e0ipso/self-review/self-review\n```\n\nTo upgrade later:\n\n```bash\nbrew upgrade self-review\n```\n\n\nAdvanced Installation Instructions
\n\nPrefer to install manually? Download the latest release from\n[GitHub Releases](https://github.com/e0ipso/self-review/releases).\n\n**Debian/Ubuntu** — download the `.deb` package and install it:\n\n```bash\n# Replace X.Y.Z with the version you downloaded\nsudo dpkg -i self-review_X.Y.Z_amd64.deb\n```\n\n**Fedora/RHEL** — download the `.rpm` package and install it:\n\n```bash\n# Replace X.Y.Z with the version you downloaded\nsudo rpm -i self-review-X.Y.Z-1.x86_64.rpm\n```\n\nThe `self-review` command will be available system-wide.\n\n \n\n## How it works\n\nInstead of seeing your changes with `git diff ` execute `self-review `. This will open the app\nand will record all the feedback in an XML file (`review.xml` by default).\n\nYou can continue your saved review if you didn't finish it:\n\n```bash\n# Resume a previous review\nself-review --staged --resume-from review.xml\n```\n\n### Examples\n\n```bash\n# Review staged changes, produces ./review.xml by default\nself-review --staged\n\n# Review changes between branches\nself-review main\n\n# Review the last commit\nself-review HEAD^\n\n# Review the current changes\nself-review\n\n# Review a remote pull/merge request by URL\nself-review https://github.com/owner/repo/pull/42\nself-review https://gitlab.com/group/project/-/merge_requests/7\n```\n\n### Reviewing a remote PR/MR\n\nHand self-review a GitHub pull request or GitLab merge request URL (self-hosted GitLab works\ntoo — the forge is detected from the URL shape) and review it in the same UI, existing\ndiscussion threads included. The review is still written to a local `review.xml`; nothing is\never sent back to the forge.\n\nUnder the hood the diff is materialized through local git: if you run the command from inside a\nclone of that repository, self-review reuses it (it only fetches refs — your working tree is\nuntouched); otherwise it creates a temporary blobless clone under your system temp directory\nand removes it when you close the app. Private repositories work through git's own credentials\n(SSH keys or credential helpers — `gh auth setup-git` / `glab auth git-credential` wire your\nforge CLI login into git). The `gh` / `glab` CLIs are only needed to sync the PR/MR discussion\nthreads; without them the review itself still works at full fidelity, just without the threads.\n\nThere is also a headless subcommand that fetches the discussion threads into a review file\nwithout opening a window:\n\n```bash\n# Write the PR's discussion threads to ./review.xml (no window)\nself-review fetch-comments https://github.com/owner/repo/pull/42\n\n# Include threads GitLab marks resolved (default is unresolved only)\nself-review fetch-comments https://gitlab.com/group/project/-/merge_requests/7 --all-threads\n```\n\n## Assistant Skill\n\nself-review ships with an AI assistant skill that closes the feedback loop: it reads your review XML,\nprioritizes the feedback, and executes the changes. It works with any assistant that supports\nskill directories, such as **Claude Code**, **Codex**, **OpenCode**, and others.\n\nThe repo also ships two companion skills under `.agents/skills/`: `self-review-critique`\n(pre-generates a review for you to curate) and `self-review-guide` (generates the walkthrough\nguide sidecar that powers guided mode; critique runs it as its first step). Install them the\nsame way as `self-review-apply` below.\n\n### Install\n\nCopy the skill directory into your project:\n\n```bash\n# From the self-review repo (or download the folder from GitHub)\ncp -r .agents/skills/self-review-apply /path/to/your/project/.agents/skills/\n```\n\n### Usage\n\nAfter running self-review and producing a `review.xml`, invoke the skill in your assistant:\n\n```\n/self-review-apply review.xml\n```\n\n\nDetails
\nYour project should end up with:\n\n\nyour-project/\n└── .agents/\n └── skills/\n └── self-review-apply/\n ├── SKILL.md\n └── self-review-v3.xsd\n\n\nThe skill will:\n\n1. Read the XSD schema to understand the review format\n2. Parse your review XML\n3. Categorize and prioritize comments, honouring `--min-severity` / `--min-confidence` floors when given\n4. Output a task plan showing parallel and sequential work groups\n5. Execute the changes, applying suggestions first, then addressing open-ended\n feedback\n\n \n\n## Configuration\n\nCustomize **self-review** with YAML configuration files:\n\n- **User config:** `~/.config/self-review/config.yaml`, personal preferences for all projects\n- **Project config:** `.self-review.yaml`, per-project settings (committable)\n\nProject config overrides user config, which overrides built-in defaults.\n\n### Available options\n\n- `theme`: light, dark, or system (default: system)\n- `diff-view`: split or unified (default: split)\n- `font-size`: editor font size in pixels (default: 14)\n- `output-file`: path for the review XML output (default: `./review.xml`)\n- `guide-file`: path to the walkthrough guide sidecar (default: derived from `output-file` as `.guide.xml`, e.g. `review.guide.xml`)\n- `ignore`: file patterns to exclude from diff (gitignore-compatible syntax; defaults cover common vendor/build dirs and lock files)\n- `categories`: custom comment tags (see example above)\n- `default-diff-args`: default arguments passed to `git diff`\n- `show-untracked`: show new files not yet added to git (default: true)\n- `word-wrap`: wrap long lines in the diff viewer (default: true)\n- `max-files`: maximum number of files before the large payload guard triggers (default: 500). Set to `0` to disable.\n- `max-total-lines`: maximum total diff lines before the large payload guard triggers (default: 100000). Set to `0` to disable.\n\nWhen 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).\n\n\nExample: Custom comment categories
\n\n```yaml\n# .self-review.yaml\ncategories:\n - name: bug\n description: 'Likely defect or incorrect behavior'\n color: '#e53e3e'\n - name: security\n description: 'Potential security vulnerability'\n color: '#d69e2e'\n - name: nit\n description: 'Minor style or formatting suggestion'\n color: '#718096'\n - name: question\n description: 'Clarification needed'\n color: '#3182ce'\n```\n\n \n\nSee [docs/PRD.md](docs/PRD.md#7-configuration) for complete documentation.\n\n## Design principles\n\n- **CLI-first.** Launched from the terminal, writes review output to a file. Behaves like a Unix tool.\n- **One-shot.** Open → review → close → done. No servers, no persistent state.\n- **Local-only.** No network access, no accounts, no telemetry. Your code stays on your machine.\n The one opt-in exception: reviewing a remote PR/MR by URL fetches that repository through git\n and reads its discussion threads — and even then, nothing is ever sent to the forge.\n- **AI-native output.** The XML format is designed to be parsed by LLMs, with an XSD schema they can\n reference for structure.\n",
"bytes": 15041,
"sha": "99b82d880779288a571ce6a97b1dcd4b71972b489d3b843d9909062884d5fc85",
"repo_slug": "e0ipso/self-review",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_e0ipso_self_review_ai_kenkeep_nodes_inde_e5b1b8b3/readme"
}