ralph-review 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenryu42
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,212 @@
-# ralph-review
+# Ralph Review
 
-To install dependencies:
+[![CI](https://github.com/kenryu42/ralph-review/actions/workflows/ci.yml/badge.svg)](https://github.com/kenryu42/ralph-review/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/github/kenryu42/ralph-review/branch/main/graph/badge.svg?token=C9QTION6ZF)](https://codecov.io/github/kenryu42/ralph-review)
+[![Version](https://img.shields.io/github/v/tag/kenryu42/ralph-review?label=version&color=blue)](https://github.com/kenryu42/ralph-review)
+[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool that orchestrates agentic review-fix cycles until your code is clean.
+
+---
+
+## Table of Contents
+
+- [Why This Exists](#why-this-exists)
+- [How It Works](#how-it-works)
+- [Agent Roles](#agent-roles)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+- [Supported Coding Agents](#supported-coding-agents)
+- [Configuration](#configuration)
+- [License](#license)
+
+---
+
+## Why This Exists
+
+I've been a huge fan of Codex's review feature ever since its [first release](https://x.com/DanielEdrisian/status/1968819243694104899). Because the GPT Codex model actually reads many files to gather context and reasoning, it is slower than other agents, but it consistently finds bugs they miss.
+
+My usual workflow was repetitive: run a Codex review, copy and paste the findings into a new session,
+ask another agent if it agrees, and then ask it to fix the issues.
+
+Why not fix it in the same session? Because I wanted an independent second opinion before applying changes, and a fresh context helped avoid the first agent’s bias carrying into the fix.
+
+Doing that manually is tedious and time-consuming, so I built this tool to automate the loop. Inspired by the [Ralph Wiggum technique](https://ghuntley.com/ralph/) by Geoffrey Huntley. I also
+wanted an easy way to try different coding agents and models.
+
+I also occasionally run a code simplifier pass before review, so I included that workflow here too.
+
+If this helps other people, great. If not, it still helps me.
+
+---
+
+## How It Works
+
+Ralph Review automates code review by pairing two AI agents -- a **reviewer** and a **fixer** -- and looping until the code is clean or the iteration limit is reached.
+
+```text
+┌──────────────────────────────┐
+│         Your changes         │
+└──────────────┬───────────────┘
+               │
+               ▼
+┌──────────────────────────────┐
+│ Code Simplifier (optional)   │
+└──────────────┬───────────────┘
+               │
+               ▼
+      ┌─────────────────┐
+      │ Reviewer agent  │ ◀───────────────────────────────────────┐
+      └────────┬────────┘                                         │
+               │                                                  │
+               ▼                                                  │
+   ┌───────────────────────┐                                      │
+   │ Create git checkpoint │                                      │
+   └───────────┬───────────┘                                      │
+               │                                                  │
+               ▼                                                  │
+      ┌─────────────────┐                                         │
+      │   Fixer agent   │                                         │
+      │  (verify & fix) │                                         │
+      └────────┬────────┘                                         │
+               │                                                  │
+               ▼                                                  │
+    ┌───────────────────────┐                                     │
+    │   Parse fix summary   │                                     │
+    └──────────┬────────────┘                                     │
+               │                                                  │
+               ├── no issues found (verified by fixer) ──▶ Stop   │
+               ├── issues found, all skipped by fixer  ──▶ Stop   │
+               │                                                  │
+               ▼                                                  │
+  Discard checkpoint, loop back to Reviewer ──────────────────────┘
+  (until max iterations reached)
+```
+
+**How the cycle works:**
+
+1. An optional **code simplifier** pass can run first (enabled with `--simplifier`) to reduce code complexity before review.
+2. The **reviewer** analyzes your changes and returns structured review output.
+3. A **git checkpoint** is created so the fixer's changes can be rolled back if something goes wrong.
+4. The **fixer** independently reads the code, confirms each issue is real, and applies fixes only where warranted. It does not blindly trust the reviewer.
+5. The fixer outputs a structured summary. If it reports no actionable issues left -- either no real issues were found or all remaining items were safely skipped -- the cycle ends.
+6. Otherwise, the cycle repeats from step 2 until no issues remain or the configured iteration limit is hit.
+
+You can assign different AI agents to each role (e.g. Claude reviews, Gemini fixes).
+
+---
+
+## Agent Roles
+
+Ralph Review orchestrates three distinct roles. You can assign any [supported coding agent](#supported-coding-agents) to each role.
+
+### Code Simplifier (optional)
+
+Enabled with `--simplifier`. Runs once before the review loop begins, reducing code complexity while preserving exact behavior. Operates on the same diff scope as the reviewer (uncommitted changes, base branch diff, or a specific commit).
+
+Prompt adapted from the [Claude Code code-simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md).
+
+### Reviewer
+
+Analyzes changes for bugs that impact correctness, security, reliability, or maintainability. Outputs structured JSON with findings, each tagged P0–P3 by priority. Ignores style nits and pre-existing issues — only flags bugs introduced in the change. Does not suggest fixes.
+
+Prompt adapted from the [Codex CLI review prompt](https://github.com/openai/codex/blob/main/codex-rs/core/review_prompt.md).
+
+### Fixer
+
+Treats review findings as untrusted input — verifies every claim against actual code before acting. Classifies each issue as APPLY (real and fixable) or SKIP (false positive or not actionable). Applies minimal safe changes, then runs project verification (lint, typecheck, tests, build). When no actionable issues remain, signals the cycle to stop.
+
+---
+
+## Prerequisites
+
+- [Bun](https://bun.sh) (runtime)
+- [tmux](https://github.com/tmux/tmux) (background sessions)
+- At least one [supported agent CLI](#supported-coding-agents) installed and authenticated
+
+---
+
+## Installation
 
 ```bash
-bun install
+npm install -g ralph-review
+```
+
+---
+
+## Quick Start
+
+```bash
+# Auto-detect installed agents and configure reviewer/fixer
+rr init
+
+# Start a review cycle (runs in tmux)
+rr run
+
+# Or use shorthand alias for `rr run`
+rrr
 ```
 
-To run:
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `rr init` | Configure reviewer, fixer, and simplifier agents (auto-detects installed CLIs) |
+| `rr run` | Start review cycle in a tmux session |
+| `rr run --base main` | Review changes against a base branch |
+| `rr run --uncommitted` | Review staged, unstaged, and untracked changes |
+| `rr run --commit SHA` | Review changes introduced by a specific commit |
+| `rr run --max N` | Set max iterations |
+| `rr run --simplifier` | Run a code-simplifier pass before review iterations |
+| `rr config show` | Print full configuration |
+| `rr config set KEY VAL` | Update a config value (e.g. `rr config set maxIterations 8`) |
+| `rr list` | List active review sessions |
+| `rr status` | Show current review status |
+| `rr stop` | Stop running review session (`--all` to stop all) |
+| `rr log` | View review logs (`-n 5` for last 5, `--json` for JSON output) |
+| `rr dashboard` | Open review dashboard in browser |
+| `rr doctor` | Run environment and configuration diagnostics (`--fix` to auto-resolve) |
+
+The `rrr` command is a shorthand alias for `rr run` -- all flags work the same.
+
+---
+
+## Supported Coding Agents
+
+| Agent | Link |
+|-------|------|
+| Claude Code | https://code.claude.com/docs/en/overview |
+| Codex | https://openai.com/codex/ |
+| Droid | https://factory.ai/ |
+| Gemini CLI | https://geminicli.com/ |
+| OpenCode | https://opencode.ai/ |
+| Pi | https://pi.dev |
+
+---
+
+## Configuration
+
+After running `rr init`, Ralph Review stores its configuration in your project directory. You can view and modify settings with the `rr config` subcommand:
 
 ```bash
-bun run index.ts
+# View current configuration
+rr config show
+
+# Edit configuration in your editor
+rr config edit
+
+# Or set a specific config using cli
+rr config set maxIterations 5
 ```
 
-This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+Run `rr doctor` to verify that your environment and configuration are valid. Add `--fix` to let it auto-resolve common issues.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,25 +1,84 @@
 {
   "name": "ralph-review",
-  "version": "0.0.1",
-  "description": "",
+  "version": "0.1.0",
+  "description": "A CLI tool that orchestrates agentic review-fix cycles until your code is clean.",
   "license": "MIT",
   "type": "module",
-  "main": "index.ts",
-  "module": "index.ts",
-  "types": "index.ts",
-  "exports": {
-    ".": {
-      "import": "./index.ts",
-      "types": "./index.ts"
-    }
+  "author": {
+    "name": "J Liew",
+    "email": "jliew@420024lab.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kenryu42/ralph-review.git"
+  },
+  "homepage": "https://github.com/kenryu42/ralph-review#readme",
+  "bugs": {
+    "url": "https://github.com/kenryu42/ralph-review/issues"
+  },
+  "os": [
+    "!win32"
+  ],
+  "keywords": [
+    "cli",
+    "code-review",
+    "ai",
+    "codex",
+    "claude",
+    "opencode",
+    "automation",
+    "developer-tools"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "bin": {
+    "ralph-review": "src/cli.ts",
+    "rr": "src/cli.ts",
+    "rrr": "src/cli-rrr.ts"
   },
   "files": [
-    "index.ts"
+    "src/cli.ts",
+    "src/cli-rrr.ts",
+    "src/cli-core.ts",
+    "src/commands",
+    "src/lib",
+    "src/terminal"
   ],
+  "scripts": {
+    "dev:tui": "bun run scripts/tui-dev.tsx",
+    "build:schema": "bun run scripts/build-schema.ts",
+    "publish:dry-run": "bun run scripts/publish.ts --dry-run",
+    "publish:recover": "bun run scripts/publish.ts --recover",
+    "publish:recover:execute": "bun run scripts/publish.ts --recover --execute",
+    "rr": "bun run src/cli.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun test",
+    "typecheck": "tsc --noEmit",
+    "knip": "knip-bun",
+    "lint": "biome check --write .",
+    "lint:ci": "biome ci .",
+    "lint-staged": "lint-staged",
+    "check": "bun run typecheck && bun run knip && bun run lint && AGENT=1 bun test --coverage",
+    "check:ci": "bun run typecheck && bun run knip && bun run lint:ci && AGENT=1 bun test --coverage",
+    "prepare": "husky && bun run setup-hooks",
+    "setup-hooks": "bun -e 'await Bun.write(\".husky/pre-commit\", \"#!/usr/bin/env sh\\n\\nbun run knip && bun run lint-staged\\n\")' && chmod +x .husky/pre-commit"
+  },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@biomejs/biome": "^2.3.12",
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0",
+    "husky": "^9.1.7",
+    "knip": "^5.82.1",
+    "lint-staged": "^16.2.7",
+    "typescript": "^5",
+    "zod": "^4.3.6"
   },
-  "peerDependencies": {
-    "typescript": "^5"
+  "peerDependencies": {},
+  "dependencies": {
+    "@clack/prompts": "1.0.0-alpha.9",
+    "@opentui/core": "^0.1.75",
+    "@opentui/react": "^0.1.75",
+    "react": "^19.0.0"
   }
 }

package/src/cli-core.ts

@@ -0,0 +1,221 @@
+import {
+  type CommandDef,
+  formatCommandHelp,
+  formatMainHelp,
+  type OptionDef,
+} from "./lib/cli-parser";
+
+const SIMPLIFIER_OPTION: OptionDef = {
+  name: "simplifier",
+  type: "boolean",
+  description: "Run one code simplifier phase before review iterations",
+};
+
+export const COMMANDS: CommandDef[] = [
+  {
+    name: "init",
+    description: "Configure reviewer, fixer, and simplifier agents (auto or custom)",
+    examples: ["rr init"],
+  },
+  {
+    name: "config",
+    description: "Inspect and update configuration",
+    positional: [
+      {
+        name: "subcommand",
+        description:
+          "show = print full config | get = read one key | set = update one key | edit = open in $EDITOR",
+      },
+      { name: "key", description: "Dot-path config key (required for get/set)" },
+      { name: "value", description: "Value to write (required for set)" },
+    ],
+    examples: [
+      "rr config show",
+      "rr config get reviewer.agent",
+      "rr config set maxIterations 8",
+      "rr config edit",
+    ],
+  },
+  {
+    name: "run",
+    description: "Start review cycle",
+    options: [
+      { name: "max", alias: "m", type: "number", description: "Max iterations" },
+      {
+        name: "force",
+        alias: "f",
+        type: "boolean",
+        description: "Run full max iterations even if no issues are found",
+      },
+      {
+        name: "base",
+        type: "string",
+        placeholder: "BRANCH",
+        description: "Review changes against the given base branch",
+      },
+      {
+        name: "uncommitted",
+        type: "boolean",
+        description: "Review staged, unstaged, and untracked changes",
+      },
+      {
+        name: "commit",
+        type: "string",
+        placeholder: "SHA",
+        description: "Review the changes introduced by a commit",
+      },
+      {
+        name: "custom",
+        type: "string",
+        placeholder: "PROMPT",
+        description: "Custom review instructions",
+      },
+      {
+        name: "sound",
+        type: "boolean",
+        description: "Play a sound when session finishes (override config)",
+      },
+      {
+        name: "no-sound",
+        type: "boolean",
+        description: "Disable finish sound for this run (override config)",
+      },
+      {
+        name: "watch",
+        type: "boolean",
+        description: "Open Session Panel after starting the run (override config)",
+      },
+      {
+        name: "no-watch",
+        type: "boolean",
+        description: "Start run without opening Session Panel (override config)",
+      },
+      SIMPLIFIER_OPTION,
+    ],
+    examples: ["rr run", "rr run --base main", "rr run --no-watch"],
+  },
+  {
+    name: "list",
+    aliases: ["ls"],
+    description: "List active review sessions",
+    examples: ["rr list", "rr ls"],
+  },
+  {
+    name: "status",
+    description: "Show review status",
+    examples: ["rr status"],
+  },
+  {
+    name: "stop",
+    description: "Stop running review session",
+    options: [
+      { name: "all", alias: "A", type: "boolean", description: "Stop all running review sessions" },
+    ],
+    examples: ["rr stop", "rr stop --all"],
+  },
+  {
+    name: "log",
+    description: "View review logs",
+    options: [
+      { name: "json", type: "boolean", description: "Output as JSON" },
+      {
+        name: "last",
+        alias: "n",
+        type: "number",
+        description: "Number of sessions to show",
+        default: 1,
+      },
+      {
+        name: "global",
+        type: "boolean",
+        description: "Show all sessions across all projects (requires --json)",
+      },
+    ],
+    examples: ["rr log", "rr log -n 5", "rr log --json", "rr log --json --global"],
+  },
+  {
+    name: "dashboard",
+    description: "Open review dashboard in browser",
+    examples: ["rr dashboard"],
+  },
+  {
+    name: "doctor",
+    description: "Run environment and configuration diagnostics",
+    options: [
+      {
+        name: "fix",
+        type: "boolean",
+        description: "Automatically fix issues that can be resolved",
+      },
+    ],
+    examples: ["rr doctor", "rr doctor --fix"],
+  },
+  {
+    name: "_run-foreground",
+    description: "Internal: run review cycle in tmux foreground",
+    hidden: true,
+    options: [
+      { name: "max", type: "number", description: "Max iterations" },
+      {
+        name: "force",
+        alias: "f",
+        type: "boolean",
+        description: "Run full max iterations even if no issues are found",
+      },
+      SIMPLIFIER_OPTION,
+    ],
+  },
+];
+
+export function getCommandDef(name: string): CommandDef | undefined {
+  return COMMANDS.find((c) => c.name === name || c.aliases?.includes(name));
+}
+
+export interface ParsedArgs {
+  command: string;
+  args: string[];
+  showHelp: boolean;
+  showVersion: boolean;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const result: ParsedArgs = {
+    command: "",
+    args: [],
+    showHelp: false,
+    showVersion: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") {
+      result.showHelp = true;
+    } else if (arg === "--version" || arg === "-v") {
+      result.showVersion = true;
+    } else if (!result.command && !arg.startsWith("-")) {
+      result.command = arg;
+    } else {
+      result.args.push(arg);
+    }
+  }
+
+  return result;
+}
+
+export function getVersion(): string {
+  try {
+    const pkg = require("../package.json");
+    return pkg.version || "0.1.0";
+  } catch {
+    return "0.1.0";
+  }
+}
+
+export function printUsage(): string {
+  return formatMainHelp(COMMANDS, getVersion());
+}
+
+export function printCommandHelp(commandName: string): string | undefined {
+  const def = getCommandDef(commandName);
+  if (!def) return undefined;
+  return formatCommandHelp(def);
+}

package/src/cli-rrr.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+
+import { printCommandHelp } from "@/cli-core";
+import { startReview } from "@/commands/run";
+
+export interface RrrDeps {
+  printCommandHelp: typeof printCommandHelp;
+  startReview: typeof startReview;
+  log: (message: string) => void;
+  error: (message: string) => void;
+  exit: (code: number) => void;
+}
+
+const CONSOLE_LOG = console.log.bind(console) as (message: string) => void;
+const CONSOLE_ERROR = console.error.bind(console) as (message: string) => void;
+const PROCESS_EXIT = process.exit.bind(process) as (code: number) => void;
+
+const DEFAULT_RRR_DEPS: RrrDeps = {
+  printCommandHelp,
+  startReview,
+  log: CONSOLE_LOG,
+  error: CONSOLE_ERROR,
+  exit: PROCESS_EXIT,
+};
+
+function buildRrrDeps(overrides: Partial<RrrDeps>): RrrDeps {
+  return { ...DEFAULT_RRR_DEPS, ...overrides };
+}
+
+export async function runRrr(
+  args: string[] = process.argv.slice(2),
+  deps: Partial<RrrDeps> = {}
+): Promise<void> {
+  const rrrDeps = buildRrrDeps(deps);
+  if (args.includes("--help") || args.includes("-h")) {
+    rrrDeps.log("rrr - Quick alias for 'rr run'\n");
+    rrrDeps.log("USAGE:");
+    rrrDeps.log("  rrr [options]\n");
+    rrrDeps.log("All options are passed through to 'rr run'.\n");
+    const optionsMatch = rrrDeps
+      .printCommandHelp("run")
+      ?.match(/OPTIONS:[\s\S]*?(?=\nEXAMPLES:|\n\n|$)/);
+    if (optionsMatch) {
+      rrrDeps.log(optionsMatch[0]);
+    }
+    return;
+  }
+
+  await rrrDeps.startReview(args);
+}
+
+export function runRrrEntrypoint(
+  run?: () => Promise<void>,
+  deps: Pick<RrrDeps, "error" | "exit"> = DEFAULT_RRR_DEPS
+): void {
+  const runFn = run ?? runRrr;
+  runFn().catch((error) => {
+    deps.error(`Error: ${error}`);
+    deps.exit(1);
+  });
+}
+
+if (import.meta.main) {
+  runRrrEntrypoint();
+}