{"id":45893446,"url":"https://github.com/kenryu42/ralph-review","last_synced_at":"2026-05-17T11:01:37.969Z","repository":{"id":340964437,"uuid":"1167440207","full_name":"kenryu42/ralph-review","owner":"kenryu42","description":"Orchestrating coding agents for code review, verification and fixing via the ralph loop.","archived":false,"fork":false,"pushed_at":"2026-05-11T10:57:24.000Z","size":4741,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T12:33:25.664Z","etag":null,"topics":["claude-code","code-review","codex","ralph-loop","ralph-wiggum"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenryu42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-26T09:47:07.000Z","updated_at":"2026-05-11T10:57:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kenryu42/ralph-review","commit_stats":null,"previous_names":["kenryu42/ralph-review"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/kenryu42/ralph-review","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenryu42%2Fralph-review","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenryu42%2Fralph-review/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenryu42%2Fralph-review/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenryu42%2Fralph-review/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenryu42","download_url":"https://codeload.github.com/kenryu42/ralph-review/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenryu42%2Fralph-review/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33054454,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","code-review","codex","ralph-loop","ralph-wiggum"],"created_at":"2026-02-27T19:24:15.453Z","updated_at":"2026-05-17T11:01:37.963Z","avatar_url":"https://github.com/kenryu42.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ralph Review\n\n[![CI](https://github.com/kenryu42/ralph-review/actions/workflows/ci.yml/badge.svg)](https://github.com/kenryu42/ralph-review/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/github/kenryu42/ralph-review/branch/main/graph/badge.svg?token=C9QTION6ZF)](https://codecov.io/github/kenryu42/ralph-review)\n[![Version](https://img.shields.io/github/v/tag/kenryu42/ralph-review?label=version\u0026color=blue)](https://github.com/kenryu42/ralph-review)\n[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)\n\nOrchestrating coding agents for code review, verification, and fixing via the Ralph loop.\n\n---\n\n## Table of Contents\n\n- [How It Works](#how-it-works)\n- [Reviewer and Fixer Flow](#reviewer-and-fixer-flow)\n- [Workflows](#workflows)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Supported Coding Agents](#supported-coding-agents)\n- [Configuration](#configuration)\n- [License](#license)\n\n---\n\n## How It Works\n\nRalph Review now uses a batch-first workflow:\n\n1. `rr run` performs review only.\n2. The reviewer runs in a disposable session worktree and reports structured findings.\n3. Findings are deduplicated across review iterations and persisted as a session artifact.\n4. If findings exist, you choose which ones to fix with `rr fix`.\n5. The fixer handles the selected findings in a separate batch remediation phase.\n6. Resolved fixes are handed back to your working tree, either automatically or as a pending handoff\n   to apply manually.\n\nThis keeps review and remediation separate by default. The reviewer can focus on finding real\nissues, and the fixer treats those findings as input for a later, explicit remediation step.\n\nUse `rr run --auto` when you want Ralph Review to run remediation immediately after review. Add\n`--priority P0,P1` to auto-fix only selected priority levels.\n\n---\n\n## Reviewer and Fixer Flow\n\n```mermaid\nflowchart TD\n    A[Your repository] --\u003e B[rr run]\n    B --\u003e C[Preflight checks]\n    C --\u003e D[Start tmux session]\n    D --\u003e E[Create disposable review worktree]\n    E --\u003e F[Reviewer agent]\n    F --\u003e G{New findings?}\n    G -- Yes --\u003e H[Merge findings into inventory]\n    H --\u003e I{Max iterations reached or no new findings?}\n    I -- No --\u003e F\n    I -- Yes --\u003e J[Persist findings artifact]\n    G -- No --\u003e K[Clean review result]\n    J --\u003e L{Fix now?}\n    L -- Later --\u003e M[rr fix --session SESSION]\n    L -- \"rr run --auto\" --\u003e N[Select findings automatically]\n    M --\u003e O[Select findings by prompt, all, priority, or ID]\n    N --\u003e P[Create disposable fix worktree]\n    O --\u003e P\n    P --\u003e Q[Fixer agent batch remediation]\n    Q --\u003e R{Selected findings resolved?}\n    R -- Yes --\u003e S[Create handoff]\n    S --\u003e T{Auto-apply succeeds?}\n    T -- Yes --\u003e U[Fixes applied to working tree]\n    T -- No --\u003e V[Pending handoff]\n    V --\u003e W[rr apply or rr prune --discard]\n    R -- No --\u003e X[Retain remediation worktree for review]\n```\n\n### Reviewer\n\nThe reviewer analyzes the selected review scope for correctness, security, reliability, and\nmaintainability issues introduced by the change. It outputs structured findings with stable IDs\nsuch as `F001`, priorities `P0` through `P3`, and source locations.\n\nReviewer iterations continue until no new findings are discovered or `maxIterations` is reached.\nBy default the run stops early when an iteration finds nothing new. Use `--force` to run the full\niteration count.\n\n### Fixer\n\nThe fixer runs only after findings have been persisted and selected. It receives the selected\nfinding inventory, works in a disposable fix worktree, and returns a per-finding result:\n`resolved` or `unresolved`.\n\nWhen all selected findings are resolved, Ralph Review creates a handoff. Depending on the working\ntree state, the handoff may be applied automatically or left pending for `rr apply`. If selected\nfindings remain unresolved, Ralph Review keeps the remediation worktree available for inspection.\n\n---\n\n## Workflows\n\nRalph Review fits into a few common loops. Each workflow below shows the scenario\nfirst, then the exact commands.\n\n### 1. Review what you are about to commit\n\nYou just finished a feature on a working branch. Before you stage and push, you\nwant a second pair of eyes on staged, unstaged, and untracked changes.\n\n```bash\nrr run --uncommitted\n```\n\nFindings are printed and persisted. You can keep coding while the reviewer runs\nin the background and come back to triage when it is done.\n\n### 2. Review your branch against the base\n\nYou are preparing a pull request against `main` and want the reviewer to look at\nthe full diff, not just your last commit.\n\n```bash\nrr run --base main\n```\n\nAdd a focus instruction when the diff is large:\n\n```bash\nrr run --base main \"focus on auth boundaries and input validation\"\n```\n\n### 3. Re-review a single commit\n\nCI flagged something on a specific commit, or you are auditing a hotfix in\nisolation.\n\n```bash\nrr run --commit 9f3a2b1\n```\n\n### 4. Review now, fix later (the default loop)\n\n`rr run` only reviews. Findings get a stable ID (`F001`, `F002`, ...) and a\npriority (`P0` through `P3`). Triage them, then fix exactly what you want:\n\n```bash\nrr run\nrr fix --session SESSION --priority P0,P1\n# or pick by ID\nrr fix --session SESSION --id F003 --id F007\n```\n\nWhen the fixer is done it either applies the patch to your working tree\nautomatically, or leaves a pending handoff that you apply explicitly:\n\n```bash\nrr apply\n```\n\n### 5. Review and auto-fix in one shot\n\nTrusted change, low risk, you want the loop to close itself:\n\n```bash\nrr run --auto --priority P0,P1\n```\n\nThe reviewer runs first, then the fixer immediately remediates only matching\npriorities in a disposable worktree and hands the result back to you.\n\n\u003e Auto Setup picks the reviewer model based on Factory.ai's public code review\n\u003e benchmark. See [Why these models?](#why-these-models-auto-setup-model-selection)\n\u003e below.\n\n### 6. Pre-PR / team review workflow\n\nBefore opening a PR, run a base-branch review and let auto-fix clean up the\nobvious stuff. Anything left becomes review notes you can paste into the PR\ndescription.\n\n```bash\nrr run --base main --auto --priority P0\nrr log -n 1            # grab the latest review log\nrr log --json          # or pipe into your own tooling\n```\n\nFor an org-wide loop, persisted review logs (`rr log --json --global`) make it\neasy to feed findings into dashboards or follow-up issues.\n\n### 7. Triage with Interactive Mode\n\nRun `rr` with no arguments to open Interactive Mode. It shows active sessions,\nrecent history, review output, findings, fix results, and handoff status in a\nsingle view, which is convenient when several reviews are in flight.\n\n### Why these models? (Auto Setup model selection)\n\n`rr init` with Auto Setup chooses your reviewer and fixer's model. That list is\ninformed by Factory.ai's public code review benchmark, which scored 13 frontier\nand open-weight models against a golden set of 50 human-curated bugs across\nfive real-world repositories (Sentry, Grafana, Keycloak, Discourse, and\ncal.com).\n\nThe reviewer model priority (highest first) is currently:\n\n1. GPT-5.2\n2. Claude Opus 4.6\n3. Claude Sonnet 4.6\n4. Claude Opus 4.7\n5. GLM 5.1\n6. GPT-5.3 Codex\n7. Gemini 3.1 Pro Preview\n8. Kimi K2.6\n\nModels near the top scored highest on the benchmark for finding real bugs at a\nreasonable cost. The fixer priority is tuned separately and favors models that\nare strong at code edits rather than at finding issues.\n\nFor the methodology and full results, see Factory.ai's writeup:\n[Which Model Reviews Code Best?](https://factory.ai/news/code-review-benchmark).\n\nYou can always override the auto selection by running `rr init` and choosing\nCustomize Setup, or by editing `reviewer.model` and `fixer.model` in your\nconfiguration directly.\n\n---\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (runtime)\n- [tmux](https://github.com/tmux/tmux) (background sessions)\n- At least one [supported agent CLI](#supported-coding-agents) installed and authenticated\n\nRalph Review is a Bun-only TypeScript CLI. Use Bun for development and script execution.\n\n---\n\n## Installation\n\n```bash\n# Homebrew (install or update)\nbrew install kenryu42/tap/ralph-review\n\n# npm (install or update)\nnpm install -g ralph-review\n\n# Or let Ralph Review detect the install method and update itself\nrr update\n```\n\nFor update checks without installing, run:\n\n```bash\nrr update --check\n```\n\nIf install-source detection is ambiguous, force the package manager:\n\n```bash\nrr update --manager npm\nrr update --manager brew\n```\n\n---\n\n## Quick Start\n\n```bash\n# Configure reviewer and fixer agents\nrr init\n\n# Start Interactive Mode\nrr\n\n# Start a review-only background session\nrr run\n\n# Review against a base branch\nrr run --base main\n\n# Review staged, unstaged, and untracked changes\nrr run --uncommitted\n\n# Review a specific commit\nrr run --commit SHA\n\n# Fix findings after review completes\nrr fix --session SESSION_ID --all\n\n# Review and immediately fix P0/P1 findings\nrr run --auto --priority P0,P1\n```\n\n`rrr` is a shorthand alias for `rr run`. It starts a non-interactive review run without launching\nInteractive Mode.\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `rr` | Launch Interactive Mode |\n| `rrr` | Alias for `rr run` |\n| `rr init` | Configure reviewer and fixer agents |\n| `rr init --global` | Write the user-global config |\n| `rr init --local` | Write repo-local overrides to `.ralph-review/config.json` |\n| `rr run` | Run review only and persist findings for later fixing |\n| `rr run --base main` | Review changes against a base branch or ref |\n| `rr run --uncommitted` | Review staged, unstaged, and untracked changes |\n| `rr run --commit SHA` | Review changes introduced by a specific commit |\n| `rr run --max N` | Set max review iterations |\n| `rr run --force` | Run all configured iterations even if no new findings appear |\n| `rr run --auto` | Run remediation immediately after review completes |\n| `rr run --auto --priority P0,P1` | Auto-fix only findings with matching priorities |\n| `rr run --sound` | Play a completion sound for this run |\n| `rr run --no-sound` | Disable the completion sound for this run |\n| `rr fix --session SESSION` | Fix selected findings from a persisted review session |\n| `rr fix --session SESSION --all` | Select all persisted findings for remediation |\n| `rr fix --session SESSION --priority P0,P1` | Select findings by priority |\n| `rr fix --session SESSION --id F001 --id F003` | Select findings by ID |\n| `rr apply` | Apply a pending review handoff |\n| `rr apply --session HANDOFF` | Apply a specific pending handoff |\n| `rr prune` | Prune orphaned review session artifacts |\n| `rr prune --dry-run` | List prunable artifacts without deleting them |\n| `rr prune --discard --session HANDOFF` | Discard a pending handoff |\n| `rr list` / `rr ls` | List active review sessions |\n| `rr stop` | Stop a running review session |\n| `rr stop --all` | Stop all running review sessions |\n| `rr log` | View the latest review log for the current project |\n| `rr log -n 5` | View the last 5 review logs |\n| `rr log --json` | Print current-project review logs as JSON |\n| `rr log --json --global` | Print review logs across all projects as JSON |\n| `rr doctor` | Run environment and configuration diagnostics |\n| `rr doctor --fix` | Auto-resolve supported diagnostic issues |\n| `rr update` | Check for and install a newer version |\n| `rr update --check` | Check for a newer version without installing |\n\nYou can append one positional custom instruction to `rr run` when an explicit review target is\nselected:\n\n```bash\nrr run --base main \"focus on security boundaries\"\n```\n\n---\n\n## Supported Coding Agents\n\n| Agent | Link |\n|-------|------|\n| Claude Code | https://code.claude.com/docs/en/overview |\n| Codex | https://openai.com/codex/ |\n| Droid | https://factory.ai/ |\n| Gemini CLI | https://geminicli.com/ |\n| OpenCode | https://opencode.ai/ |\n| Pi | https://pi.dev |\n\nYou can assign different agents and models to the reviewer and fixer roles. For example, Codex can\nreview while Claude or Gemini fixes.\n\n---\n\n## Configuration\n\nRun `rr init` to create configuration. Ralph Review supports a user-global config and repo-local\noverrides:\n\n- Global config: `~/.config/ralph-review/config.json`\n- Repo-local overrides: `.ralph-review/config.json`\n\nBy default, `rr config show` displays the effective merged configuration for the current project.\n\n```bash\n# View effective configuration\nrr config show\n\n# View raw JSON\nrr config show --json\n\n# View only repo-local overrides\nrr config show --local\n\n# View one value\nrr config get reviewer.agent\n\n# Update global configuration\nrr config set maxIterations 8\n\n# Update repo-local configuration\nrr config set --local defaultReview.branch main\n\n# Edit configuration in $EDITOR\nrr config edit\nrr config edit --local\n```\n\nUseful settings include:\n\n| Key | Purpose |\n|-----|---------|\n| `reviewer` | Agent, model, and reasoning used for review |\n| `fixer` | Agent, model, and reasoning used for remediation |\n| `maxIterations` | Maximum reviewer iterations per run |\n| `iterationTimeout` | Per-agent timeout in milliseconds |\n| `defaultReview` | Default review target, such as uncommitted changes or a base branch |\n| `notifications.sound.enabled` | Completion sound preference |\n\nRun `rr doctor` to verify that your environment and configuration are valid. Add `--fix` to let it\nauto-resolve supported issues.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenryu42%2Fralph-review","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenryu42%2Fralph-review","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenryu42%2Fralph-review/lists"}