ralph-review 0.1.4 → 0.1.6

package/README.md

@@ -5,7 +5,7 @@
 [![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.
+Orchestrating coding agents for code review, verification and fixing via the ralph loop.
 
 ---
 
@@ -131,6 +131,10 @@ Treats review findings as untrusted input — verifies every claim against actua
 ## Installation
 
 ```bash
+# Homebrew (install or update)
+brew install kenryu42/tap/ralph-review
+
+# npm (install or update)
 npm install -g ralph-review
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ralph-review",
-  "version": "0.1.4",
-  "description": "A CLI tool that orchestrates agentic review-fix cycles until your code is clean.",
+  "version": "0.1.6",
+  "description": "Orchestrating coding agents for code review, verification and fixing via the ralph loop.",
   "license": "MIT",
   "type": "module",
   "author": {

package/src/commands/init.ts

@@ -211,11 +211,12 @@ const DEFAULT_MAX_ITERATIONS = 5;
 const DEFAULT_ITERATION_TIMEOUT_MINUTES = 30;
 
 const REVIEWER_AGENT_PRIORITY: readonly AgentType[] = ["codex", "droid", "claude", "gemini"];
-const FIXER_AGENT_PRIORITY: readonly AgentType[] = ["claude", "codex", "droid", "gemini"];
-const SIMPLIFIER_AGENT_PRIORITY: readonly AgentType[] = ["claude", "codex", "droid", "gemini"];
+const FIXER_AGENT_PRIORITY: readonly AgentType[] = ["codex", "claude", "droid", "gemini"];
+const SIMPLIFIER_AGENT_PRIORITY: readonly AgentType[] = ["codex", "claude", "droid", "gemini"];
 
 const MODEL_PRIORITY_MATCHERS: Record<ConfiguredRole, readonly ((model: string) => boolean)[]> = {
   reviewer: [
+    (model) => matchesModelId(model, "gpt-5.4"),
     (model) => matchesModelId(model, "gpt-5.3-codex"),
     (model) => matchesModelId(model, "gpt-5.2"),
     (model) => matchesModelId(model, "gpt-5.2-codex"),
@@ -223,11 +224,13 @@ const MODEL_PRIORITY_MATCHERS: Record<ConfiguredRole, readonly ((model: string)
     (model) => matchesModelId(model, "gemini-3-pro-preview"),
   ],
   fixer: [
-    (model) => matchesModelId(model, "claude-opus-4-6"),
+    (model) => matchesModelId(model, "gpt-5.4"),
     (model) => matchesModelId(model, "gpt-5.3-codex"),
+    (model) => matchesModelId(model, "claude-opus-4-6"),
     (model) => matchesModelId(model, "gemini-3-pro-preview"),
   ],
   "code-simplifier": [
+    (model) => matchesModelId(model, "gpt-5.4"),
     (model) => matchesModelId(model, "claude-opus-4-6"),
     (model) => matchesModelId(model, "gpt-5.3-codex"),
     (model) => isClaudeOpus45Model(model),
@@ -754,8 +757,8 @@ export async function buildAutoInitInput(
       iterationTimeoutMinutes,
       defaultReviewType: "uncommitted",
       runSimplifierByDefault: false,
-      runWatchByDefault: DEFAULT_CONFIG.run?.watch ?? true,
-      soundNotificationsEnabled: DEFAULT_CONFIG.notifications?.sound.enabled ?? true,
+      runWatchByDefault: true,
+      soundNotificationsEnabled: true,
     },
     skippedAgents,
   };
@@ -1043,14 +1046,21 @@ export async function runInitWithRuntime(
   }
 
   const resolvedInput = requireInitInput(runtime, input);
-  const inputWithPreferences: InitInput = {
-    ...resolvedInput,
-    runWatchByDefault: await promptForRunWatch(runtime, resolvedInput.runWatchByDefault),
-    soundNotificationsEnabled: await promptForSoundNotifications(
-      runtime,
-      resolvedInput.soundNotificationsEnabled
-    ),
-  };
+  const inputWithPreferences: InitInput =
+    setupMode === "auto"
+      ? {
+          ...resolvedInput,
+          runWatchByDefault: true,
+          soundNotificationsEnabled: true,
+        }
+      : {
+          ...resolvedInput,
+          runWatchByDefault: await promptForRunWatch(runtime, resolvedInput.runWatchByDefault),
+          soundNotificationsEnabled: await promptForSoundNotifications(
+            runtime,
+            resolvedInput.soundNotificationsEnabled
+          ),
+        };
 
   const config = buildConfig(inputWithPreferences);
   runtime.prompt.log.info(`Proposed configuration:\n${formatConfigDisplay(config)}`);

package/src/lib/agents/models.ts

@@ -17,6 +17,7 @@ export const claudeModelOptions = [
 ] as const;
 
 export const codexModelOptions = [
+  { value: "gpt-5.4", label: "GPT-5.4" },
   { value: "gpt-5.3-codex", label: "GPT-5.3 Codex" },
   { value: "gpt-5.2-codex", label: "GPT-5.2 Codex" },
   { value: "gpt-5.2", label: "GPT-5.2" },
@@ -37,6 +38,7 @@ export const droidModelOptions = [
   { value: "gpt-5.2", label: "GPT-5.2" },
   { value: "gpt-5.2-codex", label: "GPT-5.2-Codex" },
   { value: "gpt-5.3-codex", label: "GPT-5.3-Codex" },
+  { value: "gpt-5.4", label: "GPT-5.4" },
   { value: "gemini-3-pro-preview", label: "Gemini 3 Pro" },
   { value: "gemini-3.1-pro-preview", label: "Gemini 3.1 Pro" },
   { value: "gemini-3-flash-preview", label: "Gemini 3 Flash" },
@@ -63,6 +65,7 @@ const droidReasoningLevelsByModel: Record<string, readonly ReasoningLevel[]> = {
   "gpt-5.2": ["low", "medium", "high", "xhigh"],
   "gpt-5.2-codex": ["low", "medium", "high", "xhigh"],
   "gpt-5.3-codex": ["low", "medium", "high", "xhigh"],
+  "gpt-5.4": ["low", "medium", "high", "xhigh"],
   "claude-sonnet-4-5-20250929": ["low", "medium", "high"],
   "claude-sonnet-4-6": ["low", "medium", "high"],
   "claude-opus-4-5-20251101": ["low", "medium", "high"],

package/src/lib/html/dashboard/script.ts

@@ -163,6 +163,48 @@ const DASHBOARD_SCRIPT_TEMPLATE = `
   const sortByPriority = (fixes) =>
     [...fixes].sort((a, b) => getPriorityRank(a.priority) - getPriorityRank(b.priority));
 
+  const formatFixRangeHunk = (lineStart, lineEnd) => {
+    const count = lineEnd - lineStart + 1;
+    if (count <= 1) {
+      return \`@@ -\${lineStart} +\${lineStart} @@\`;
+    }
+    return \`@@ -\${lineStart},\${count} +\${lineStart},\${count} @@\`;
+  };
+
+  const normalizeFixCodeLocation = (fix) => {
+    const vmLocation = fix?.codeLocation;
+    if (
+      vmLocation &&
+      typeof vmLocation.absoluteFilePath === "string" &&
+      Number.isInteger(vmLocation.lineStart) &&
+      Number.isInteger(vmLocation.lineEnd) &&
+      vmLocation.lineStart > 0 &&
+      vmLocation.lineEnd >= vmLocation.lineStart
+    ) {
+      return vmLocation;
+    }
+
+    const rawLocation = fix?.code_location;
+    const start = rawLocation?.line_range?.start;
+    const end = rawLocation?.line_range?.end;
+    if (
+      rawLocation &&
+      typeof rawLocation.absolute_file_path === "string" &&
+      Number.isInteger(start) &&
+      Number.isInteger(end) &&
+      start > 0 &&
+      end >= start
+    ) {
+      return {
+        absoluteFilePath: rawLocation.absolute_file_path,
+        lineStart: start,
+        lineEnd: end,
+      };
+    }
+
+    return null;
+  };
+
   const extractFixes = (entries) => {
     const fixes = [];
     const skipped = [];
@@ -298,15 +340,24 @@ const DASHBOARD_SCRIPT_TEMPLATE = `
           <div class="panel-title">Fixes Applied</div>
           \${fixes.length
             ? \`<ul class="fix-list">\${fixes
-                .map((fix) => \`
+                .map((fix) => {
+                  const location = normalizeFixCodeLocation(fix);
+                  const filePath = fix.file || location?.absoluteFilePath || "";
+                  const range = location
+                    ? \`<div class="fix-range mono">\${escapeHtml(formatFixRangeHunk(location.lineStart, location.lineEnd))}</div>\`
+                    : "";
+
+                  return \`
                   <li class="fix-item">
                     <div class="fix-pill \${getPriorityPillClass(fix.priority)}">\${escapeHtml(fix.priority)}</div>
                     <div>
                       <div class="fix-title">\${escapeHtml(fix.title)}</div>
-                      <div class="fix-meta muted">\${escapeHtml(fix.file || "")}</div>
+                      <div class="fix-meta muted">\${escapeHtml(filePath)}</div>
+                      \${range}
                     </div>
                   </li>
-                \`)
+                \`;
+                })
                 .join("")}</ul>\`
             : '<div class="muted">No fixes recorded for this session.</div>'}
         </div>

package/src/lib/html/dashboard/styles.ts

@@ -359,6 +359,11 @@ export const DASHBOARD_CSS = `
   .fix-pill-default { background: var(--accent); }
   .fix-title, .skip-title { font-weight: 600; font-size: 13px; }
   .fix-meta, .skip-reason { font-size: 11px; margin-top: 4px; }
+  .fix-range {
+    margin-top: 6px;
+    color: rgba(237, 242, 255, 0.84);
+    font-size: 11px;
+  }
   .muted { color: var(--muted); }
   .empty { padding: 24px; text-align: center; color: var(--muted); border: 1px dashed var(--border); border-radius: 16px; background: rgba(9, 14, 23, 0.6); }
   .empty.tiny { padding: 12px; font-size: 12px; }

package/src/lib/html/dashboard/view-model.ts

@@ -17,6 +17,11 @@ interface FixViewModel {
   priority: FixEntry["priority"];
   title: string;
   file: string;
+  codeLocation?: {
+    absoluteFilePath: string;
+    lineStart: number;
+    lineEnd: number;
+  };
 }
 
 interface SkippedViewModel {
@@ -99,16 +104,45 @@ function formatRoleDisplay(name: string, model: string, reasoning: string): stri
   return `${name} (${details.join(", ")})`;
 }
 
+function toCodeLocationViewModel(fix: FixEntry): FixViewModel["codeLocation"] {
+  const location = fix.code_location;
+  if (!location) {
+    return undefined;
+  }
+
+  const lineStart = location.line_range?.start;
+  const lineEnd = location.line_range?.end;
+  if (
+    typeof location.absolute_file_path !== "string" ||
+    !Number.isInteger(lineStart) ||
+    !Number.isInteger(lineEnd) ||
+    lineStart < 1 ||
+    lineEnd < lineStart
+  ) {
+    return undefined;
+  }
+
+  return {
+    absoluteFilePath: location.absolute_file_path,
+    lineStart,
+    lineEnd,
+  };
+}
+
 function buildSessionViewModel(session: SessionStats): SessionViewModel {
   const { fixes, skipped } = extractFixes(session.entries ?? []);
   const priorities = new Set(fixes.map((fix) => fix.priority));
   const sortedFixes = [...fixes]
     .sort((a, b) => getPriorityRank(a.priority) - getPriorityRank(b.priority))
-    .map((fix) => ({
-      priority: fix.priority,
-      title: fix.title,
-      file: fix.file ?? "",
-    }));
+    .map((fix) => {
+      const codeLocation = toCodeLocationViewModel(fix);
+      return {
+        priority: fix.priority,
+        title: fix.title,
+        file: fix.file ?? "",
+        ...(codeLocation ? { codeLocation } : {}),
+      };
+    });
 
   const sortedSkipped = [...skipped]
     .sort((a, b) => getPriorityRank(a.priority) - getPriorityRank(b.priority))

package/src/lib/html/log/page.ts

@@ -3,8 +3,10 @@ import { getPriorityPillClass } from "@/lib/html/priority";
 import { escapeHtml, formatDate, formatDuration } from "@/lib/html/shared";
 import type {
   AgentSettings,
+  CodeLocation,
   FixEntry,
   IterationEntry,
+  LineRange,
   LogEntry,
   SkippedEntry,
   SystemEntry,
@@ -20,8 +22,64 @@ function isCodeSimplified(systemEntry: SystemEntry | undefined): boolean {
   return Boolean(systemEntry.codeSimplifier || systemEntry.reviewOptions?.simplifier);
 }
 
+function isValidLineRange(lineRange: LineRange | undefined): lineRange is LineRange {
+  if (!lineRange) {
+    return false;
+  }
+
+  return (
+    Number.isInteger(lineRange.start) &&
+    Number.isInteger(lineRange.end) &&
+    lineRange.start > 0 &&
+    lineRange.end >= lineRange.start
+  );
+}
+
+function isValidCodeLocation(location: CodeLocation | null | undefined): location is CodeLocation {
+  if (!location || typeof location.absolute_file_path !== "string") {
+    return false;
+  }
+
+  return isValidLineRange(location.line_range);
+}
+
+function getFixDisplayFile(fix: FixEntry): string {
+  if (fix.file) {
+    return fix.file;
+  }
+
+  const location = fix.code_location;
+  if (isValidCodeLocation(location)) {
+    return location.absolute_file_path;
+  }
+
+  return "";
+}
+
+function formatFixRangeHunk(start: number, end: number): string {
+  const count = end - start + 1;
+  if (count <= 1) {
+    return `@@ -${start} +${start} @@`;
+  }
+  return `@@ -${start},${count} +${start},${count} @@`;
+}
+
+function renderFixRange(fix: FixEntry): string {
+  const location = fix.code_location;
+  if (!isValidCodeLocation(location)) {
+    return "";
+  }
+
+  const lineStart = location.line_range.start;
+  const lineEnd = location.line_range.end;
+
+  return `<div class="fix-range mono">${escapeHtml(formatFixRangeHunk(lineStart, lineEnd))}</div>`;
+}
+
 function renderFixEntry(fix: FixEntry): string {
-  const file = fix.file ? `<span class="muted">${escapeHtml(fix.file)}</span>` : "";
+  const filePath = getFixDisplayFile(fix);
+  const file = filePath ? `<span class="muted">${escapeHtml(filePath)}</span>` : "";
+  const range = renderFixRange(fix);
   const pillClass = getPriorityPillClass(fix.priority);
   return `
     <li class="fix-item">
@@ -29,6 +87,7 @@ function renderFixEntry(fix: FixEntry): string {
       <div>
         <div class="fix-title">${escapeHtml(fix.title)}</div>
         <div class="fix-meta">${file}</div>
+        ${range}
       </div>
     </li>
   `;

package/src/lib/html/log/styles.ts

@@ -84,9 +84,15 @@ export const LOG_CSS = `
   .fix-pill-default { background: var(--accent); }
   .fix-title { font-weight: 600; }
   .fix-meta { font-size: 12px; margin-top: 4px; }
+  .fix-range {
+    margin-top: 6px;
+    color: rgba(237, 242, 255, 0.85);
+    font-size: 12px;
+  }
   .skip-title { font-weight: 600; }
   .skip-reason { font-size: 12px; }
   .muted { color: var(--muted); }
+  .mono { font-family: "Space Grotesk", monospace; }
   .callout {
     margin-top: 12px;
     padding: 12px 16px;

package/src/lib/prompts/fixer.ts

@@ -36,6 +36,7 @@ ${reviewOutput}
    - Prefer one aggregate command; otherwise run available lint -> typecheck -> test -> build.
    - Treat warnings as blocking.
    - Iterate fix + rerun until clean.
+6) For each APPLY item, include the applied code location when available (absolute path + line range).
 
 ## Special rule: tracking-status claims
 Claims like "file is untracked/not committed/missing from git" are SKIP in this pre-commit workflow.
@@ -69,6 +70,10 @@ ${FIX_SUMMARY_START_TOKEN}
       "title": "<one-line title>",
       "priority": "<P0 | P1 | P2 | P3>",
       "file": "<path or null>",
+      "code_location": {
+        "absolute_file_path": "<absolute path>",
+        "line_range": {"start": <int>, "end": <int>}
+      },
       "claim": "<issue claim>",
       "evidence": "<file:line / behavior>",
       "fix": "<what changed>"
@@ -95,6 +100,7 @@ JSON rules:
   - fixes MUST be []
   - skipped MUST contain only SKIP items
 - Include all APPLY items in fixes.
+- For each APPLY item, include code_location when available; otherwise set code_location to null or omit it.
 - Include all SKIP items in skipped with required reason prefix.
 - Use [] when empty.
 - Priority must be exactly P0/P1/P2/P3.

package/src/lib/tui/components/Header.tsx

@@ -80,18 +80,21 @@ export function Header({ branch, elapsed, session, projectPath, config }: Header
       flexShrink={0}
     >
       <box flexDirection="row">
-        <box flexDirection="column" width={12}>
+        <box flexDirection="column" width={20}>
           <text>
-            <span fg={TUI_COLORS.brand.logo}> {"   "}║ </span>
+            <span fg={TUI_COLORS.brand.title}>{" ██████╗ ██████╗ "}</span>
           </text>
           <text>
-            <span fg={TUI_COLORS.brand.logo}> ███████ </span>
+            <span fg={TUI_COLORS.brand.title}>{" ██╔══██╗██╔══██╗"}</span>
           </text>
           <text>
-            <span fg={TUI_COLORS.brand.logo}>▐██▃█▃██▌</span>
+            <span fg={TUI_COLORS.brand.title}>{" ██████╔╝██████╔╝"}</span>
           </text>
           <text>
-            <span fg={TUI_COLORS.brand.logo}> ██▅▅▅██ </span>
+            <span fg={TUI_COLORS.brand.title}>{" ██║  ██║██║  ██║"}</span>
+          </text>
+          <text>
+            <span fg={TUI_COLORS.brand.title}>{" ╚═╝  ╚═╝╚═╝  ╚═╝"}</span>
           </text>
         </box>
 

package/src/lib/types/fix.ts

@@ -1,11 +1,13 @@
 import type { FixDecision, Priority } from "./domain";
 import { VALID_FIX_DECISIONS, VALID_PRIORITIES } from "./domain";
+import type { CodeLocation } from "./review";
 
 export interface FixEntry {
   id: number;
   title: string;
   priority: Priority;
   file?: string | null;
+  code_location?: CodeLocation | null;
   claim: string;
   evidence: string;
   fix: string;
@@ -25,6 +27,37 @@ export interface FixSummary {
   skipped: SkippedEntry[];
 }
 
+function isLineRange(value: unknown): value is CodeLocation["line_range"] {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  return (
+    typeof obj.start === "number" &&
+    Number.isInteger(obj.start) &&
+    obj.start > 0 &&
+    typeof obj.end === "number" &&
+    Number.isInteger(obj.end) &&
+    obj.end >= obj.start
+  );
+}
+
+function isCodeLocation(value: unknown): value is CodeLocation {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  if (typeof obj.absolute_file_path !== "string") {
+    return false;
+  }
+
+  return isLineRange(obj.line_range);
+}
+
 function isFixEntry(value: unknown): value is FixEntry {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -38,6 +71,9 @@ function isFixEntry(value: unknown): value is FixEntry {
     typeof obj.priority === "string" &&
     VALID_PRIORITIES.includes(obj.priority as Priority) &&
     (obj.file === undefined || obj.file === null || typeof obj.file === "string") &&
+    (obj.code_location === undefined ||
+      obj.code_location === null ||
+      isCodeLocation(obj.code_location)) &&
     typeof obj.claim === "string" &&
     typeof obj.evidence === "string" &&
     typeof obj.fix === "string"

package/src/lib/types/index.ts

@@ -31,9 +31,11 @@ export type {
   SystemEntry,
 } from "./log";
 export {
+  type CodeLocation,
   type CodexReviewSummary,
   type Finding,
   isReviewSummary,
+  type LineRange,
   parseCodexReviewText,
   type ReviewSummary,
 } from "./review";

package/src/lib/types/review.ts

@@ -1,12 +1,12 @@
 import type { OverallCorrectness } from "./domain";
 import { VALID_OVERALL_CORRECTNESS } from "./domain";
 
-interface LineRange {
+export interface LineRange {
   start: number;
   end: number;
 }
 
-interface CodeLocation {
+export interface CodeLocation {
   absolute_file_path: string;
   line_range: LineRange;
 }