@graypark/ralph-codex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viewcommz
+
+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

@@ -0,0 +1,176 @@
+# ralph-codex
+
+Ralph Loop for **OpenAI Codex CLI** — self-referential iterative development loops powered by Stop hooks.
+
+Ralph Loop is a development methodology where an AI agent works on a task in a continuous loop, seeing its own previous work each iteration, until a completion condition is met. This package brings that capability to Codex CLI with full cross-platform support.
+
+## Requirements
+
+- **Node.js** 18+
+- **Codex CLI** v0.114+ (experimental hooks engine required)
+
+## Installation
+
+### Option 1: npx (recommended)
+
+```bash
+npx @graypark/ralph-codex --global
+```
+
+### Option 2: Clone and install
+
+```bash
+git clone https://github.com/Viewcommz/ralph-codex.git
+cd ralph-codex
+node bin/install.mjs --global
+```
+
+### Options
+
+| Flag        | Description                                |
+| ----------- | ------------------------------------------ |
+| `--global`  | Install to `~/.codex/` (default)           |
+| `--local`   | Install to `.codex/` in current project    |
+| `--dry-run` | Preview changes without modifying anything |
+| `--force`   | Overwrite existing installation            |
+
+## Usage
+
+### Start a Ralph Loop
+
+In Codex CLI, use the slash command:
+
+```
+/ralph-loop "Build a REST API for todos with CRUD, validation, and tests" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
+```
+
+**Parameters:**
+
+| Parameter                   | Default    | Description                             |
+| --------------------------- | ---------- | --------------------------------------- |
+| `PROMPT`                    | (required) | Task description                        |
+| `--max-iterations N`        | 20         | Maximum loop iterations (0 = unlimited) |
+| `--completion-promise TEXT` | "TADA"     | Phrase that signals task completion     |
+
+### Cancel a Loop
+
+```
+/cancel-ralph
+```
+
+### How It Works
+
+1. You invoke `/ralph-loop` with a task prompt
+2. Codex works on the task normally
+3. When Codex tries to exit, the **Stop hook** intercepts
+4. The hook checks: max iterations reached? Completion promise found?
+5. If not done, the hook **blocks the exit** and feeds the same prompt back
+6. Codex sees its previous work in files and git history
+7. Codex continues iterating until completion
+
+### Completion Promise
+
+To signal task completion, Codex must output the promise phrase wrapped in XML tags:
+
+```
+<promise>ALL_TESTS_PASS</promise>
+```
+
+The promise is only valid when the statement is genuinely true. The loop is designed to prevent false exits.
+
+## Prompt Writing Tips
+
+### 1. Split into Phases
+
+```
+/ralph-loop "Phase 1: Set up project scaffold. Phase 2: Implement core logic. Phase 3: Add tests. Output <promise>DONE</promise> when all phases complete." --max-iterations 30
+```
+
+### 2. Objective Completion Criteria
+
+```
+/ralph-loop "Implement the auth module. Done when: all tests pass, no TypeScript errors, coverage > 80%." --completion-promise "AUTH_COMPLETE" --max-iterations 25
+```
+
+### 3. Always Set an Escape Hatch
+
+Always use `--max-iterations` to prevent infinite loops on impossible tasks.
+
+### 4. Self-Correction Pattern
+
+```
+/ralph-loop "Fix the failing CI pipeline. Run tests, read errors, fix code, repeat." --max-iterations 15 --completion-promise "CI_GREEN"
+```
+
+## Windows Support
+
+ralph-codex works natively on Windows without WSL or Git Bash:
+
+- All paths use `path.join()` (no hardcoded slashes)
+- The installer copies files instead of symlinks on Windows
+- State files use JSON (no Unix-specific formats)
+- Hooks use `node` as the interpreter (cross-platform)
+
+Tested on: Windows 10/11, macOS, Linux (Ubuntu/Debian).
+
+## Uninstall
+
+```bash
+npx @graypark/ralph-codex uninstall
+# or
+node bin/uninstall.mjs --global
+```
+
+This removes:
+
+- Plugin files from `~/.codex/plugins/ralph-codex/`
+- Stop hook entry from `~/.codex/hooks.json`
+- Skill files for `/ralph-loop` and `/cancel-ralph`
+- Any active state file
+
+## Architecture
+
+```
+ralph-codex/
+├── bin/
+│   ├── install.mjs      # Cross-platform installer
+│   └── uninstall.mjs    # Clean uninstaller
+├── hooks/
+│   ├── hooks.json        # Hook registration (reference)
+│   └── stop-hook.mjs     # Stop hook — the core loop engine
+├── commands/
+│   ├── ralph-loop.md     # /ralph-loop slash command
+│   └── cancel-ralph.md   # /cancel-ralph slash command
+├── lib/
+│   ├── paths.mjs         # Cross-platform path utilities
+│   └── state.mjs         # Loop state management
+└── package.json
+```
+
+## How It Compares to Claude Code's Ralph Loop
+
+| Feature            | Claude Code (official)                | ralph-codex (this)       |
+| ------------------ | ------------------------------------- | ------------------------ |
+| Runtime            | Bash (sh/perl)                        | Node.js (cross-platform) |
+| State format       | Markdown + YAML frontmatter           | JSON                     |
+| Windows support    | WSL required                          | Native                   |
+| Hook protocol      | `{"decision":"block","reason":"..."}` | Same                     |
+| Transcript parsing | `jq` + `grep`                         | Native Node.js           |
+| Installation       | Plugin marketplace                    | `npx` or manual          |
+
+## Development
+
+```bash
+# Install dev dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npx vitest
+```
+
+## License
+
+MIT

package/bin/install.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+import {
+  readFile,
+  writeFile,
+  mkdir,
+  cp,
+  readdir,
+  access,
+} from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  isWindows,
+  getCodexHome,
+  getHooksJsonPath,
+  getPluginInstallDir,
+  getSkillsDir,
+  getLocalCodexDir,
+  getLocalPluginDir,
+  getLocalHooksJsonPath,
+  getLocalSkillsDir,
+} from "../lib/paths.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+
+// Parse CLI args
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const forceFlag = args.includes("--force");
+const localMode = args.includes("--local");
+const showHelp = args.includes("--help") || args.includes("-h");
+const uninstallMode = args.includes("uninstall");
+
+if (showHelp) {
+  console.log(`ralph-codex installer
+
+Usage:
+  node bin/install.mjs [options]
+  npx ralph-codex install [options]
+
+Options:
+  --global      Install to ~/.codex/ (default)
+  --local       Install to .codex/ in current project
+  --dry-run     Show what would be done without making changes
+  --force       Overwrite existing installation without prompting
+  --help, -h    Show this help message
+
+  uninstall     Remove ralph-codex from Codex CLI
+`);
+  process.exit(0);
+}
+
+if (uninstallMode) {
+  const { uninstall } = await import("./uninstall.mjs");
+  await uninstall({ dryRun, local: localMode });
+  process.exit(0);
+}
+
+// Determine target paths based on mode
+const codexHome = localMode ? getLocalCodexDir() : getCodexHome();
+const pluginDir = localMode ? getLocalPluginDir() : getPluginInstallDir();
+const hooksJsonPath = localMode ? getLocalHooksJsonPath() : getHooksJsonPath();
+const skillsDir = localMode ? getLocalSkillsDir() : getSkillsDir();
+
+const RALPH_HOOK_MARKER = "ralph-codex";
+
+function log(icon, msg) {
+  console.log(`  ${icon} ${msg}`);
+}
+
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyPluginFiles() {
+  const dirs = ["hooks", "commands", "lib"];
+  for (const dir of dirs) {
+    const src = join(PROJECT_ROOT, dir);
+    const dest = join(pluginDir, dir);
+    log(">", `Copy ${dir}/ -> ${dest}`);
+    if (!dryRun) {
+      await mkdir(dest, { recursive: true });
+      await cp(src, dest, { recursive: true });
+    }
+  }
+  // Copy package.json for version tracking
+  const pkgSrc = join(PROJECT_ROOT, "package.json");
+  const pkgDest = join(pluginDir, "package.json");
+  log(">", `Copy package.json -> ${pkgDest}`);
+  if (!dryRun) {
+    await cp(pkgSrc, pkgDest);
+  }
+}
+
+async function mergeHooksJson() {
+  const stopHookCommand = `node "${join(pluginDir, "hooks", "stop-hook.mjs")}"`;
+
+  const newEntry = {
+    hooks: [
+      {
+        type: "command",
+        command: stopHookCommand,
+        timeout: 30,
+      },
+    ],
+  };
+
+  let existing = { hooks: {} };
+  if (await fileExists(hooksJsonPath)) {
+    try {
+      const raw = await readFile(hooksJsonPath, "utf-8");
+      existing = JSON.parse(raw);
+    } catch {
+      log("!", `Warning: existing hooks.json is malformed, creating fresh`);
+      existing = { hooks: {} };
+    }
+  }
+
+  if (!existing.hooks) {
+    existing.hooks = {};
+  }
+  if (!Array.isArray(existing.hooks.Stop)) {
+    existing.hooks.Stop = [];
+  }
+
+  // Remove any existing ralph-codex entries
+  existing.hooks.Stop = existing.hooks.Stop.filter((entry) => {
+    const cmds = entry.hooks || [];
+    return !cmds.some(
+      (h) => h.command && h.command.includes(RALPH_HOOK_MARKER),
+    );
+  });
+
+  // Add our entry
+  existing.hooks.Stop.push(newEntry);
+
+  log(">", `Merge Stop hook into ${hooksJsonPath}`);
+  log(" ", `Command: ${stopHookCommand}`);
+
+  if (!dryRun) {
+    await mkdir(dirname(hooksJsonPath), { recursive: true });
+    await writeFile(hooksJsonPath, JSON.stringify(existing, null, 2), "utf-8");
+  }
+}
+
+async function installSkills() {
+  const skillNames = ["ralph-loop", "cancel-ralph"];
+  for (const name of skillNames) {
+    const skillDir = join(skillsDir, name);
+    const skillMd = join(skillDir, "SKILL.md");
+    const commandSrc = join(pluginDir, "commands", `${name}.md`);
+
+    log(">", `Install skill: ${name} -> ${skillDir}`);
+
+    if (!dryRun) {
+      await mkdir(skillDir, { recursive: true });
+
+      // Read the command markdown and convert to SKILL.md format
+      const content = await readFile(
+        join(PROJECT_ROOT, "commands", `${name}.md`),
+        "utf-8",
+      );
+
+      // Replace ${RALPH_CODEX_ROOT} placeholder with actual install path
+      const resolved = content.replaceAll("${RALPH_CODEX_ROOT}", pluginDir);
+
+      await writeFile(skillMd, resolved, "utf-8");
+    }
+  }
+}
+
+async function main() {
+  console.log("");
+  console.log(`ralph-codex installer${dryRun ? " (DRY RUN)" : ""}`);
+  console.log(`Mode: ${localMode ? "local (.codex/)" : "global (~/.codex/)"}`);
+  console.log(`Target: ${pluginDir}`);
+  console.log("");
+
+  // Check for existing installation
+  if (!forceFlag && (await fileExists(pluginDir))) {
+    if (dryRun) {
+      log("!", "Existing installation found (would prompt for --force)");
+    } else {
+      log("!", "Existing installation found. Use --force to overwrite.");
+      process.exit(1);
+    }
+  }
+
+  // Step 1: Copy plugin files
+  console.log("[1/3] Copying plugin files...");
+  await copyPluginFiles();
+
+  // Step 2: Merge hooks.json
+  console.log("[2/3] Configuring Stop hook...");
+  await mergeHooksJson();
+
+  // Step 3: Install skills (slash commands)
+  console.log("[3/3] Installing skills...");
+  await installSkills();
+
+  console.log("");
+  if (dryRun) {
+    log("\u2714", "Dry run complete. No files were modified.");
+  } else {
+    log("\u2714", "ralph-codex installed successfully!");
+    console.log("");
+    console.log("  Usage in Codex CLI:");
+    console.log(
+      '    /ralph-loop "Build a REST API" --max-iterations 20 --completion-promise "DONE"',
+    );
+    console.log("    /cancel-ralph");
+    console.log("");
+    console.log("  To uninstall:");
+    console.log("    node bin/uninstall.mjs" + (localMode ? " --local" : ""));
+  }
+  console.log("");
+}
+
+main().catch((err) => {
+  console.error(`\u2718 Installation failed: ${err.message}`);
+  process.exit(1);
+});

package/bin/uninstall.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile, rm, access } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  getHooksJsonPath,
+  getPluginInstallDir,
+  getSkillsDir,
+  getLocalHooksJsonPath,
+  getLocalPluginDir,
+  getLocalSkillsDir,
+} from "../lib/paths.mjs";
+import { getStatePath } from "../lib/state.mjs";
+
+const RALPH_HOOK_MARKER = "ralph-codex";
+
+function log(icon, msg) {
+  console.log(`  ${icon} ${msg}`);
+}
+
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function uninstall({ dryRun = false, local = false } = {}) {
+  const pluginDir = local ? getLocalPluginDir() : getPluginInstallDir();
+  const hooksJsonPath = local ? getLocalHooksJsonPath() : getHooksJsonPath();
+  const skillsDir = local ? getLocalSkillsDir() : getSkillsDir();
+
+  console.log("");
+  console.log(`ralph-codex uninstaller${dryRun ? " (DRY RUN)" : ""}`);
+  console.log("");
+
+  // 1. Remove ralph-codex entries from hooks.json
+  if (await fileExists(hooksJsonPath)) {
+    try {
+      const raw = await readFile(hooksJsonPath, "utf-8");
+      const config = JSON.parse(raw);
+
+      if (config.hooks && Array.isArray(config.hooks.Stop)) {
+        const before = config.hooks.Stop.length;
+        config.hooks.Stop = config.hooks.Stop.filter((entry) => {
+          const cmds = entry.hooks || [];
+          return !cmds.some(
+            (h) => h.command && h.command.includes(RALPH_HOOK_MARKER),
+          );
+        });
+        const removed = before - config.hooks.Stop.length;
+
+        if (removed > 0) {
+          log(">", `Remove ${removed} Stop hook entry from ${hooksJsonPath}`);
+          if (!dryRun) {
+            await writeFile(
+              hooksJsonPath,
+              JSON.stringify(config, null, 2),
+              "utf-8",
+            );
+          }
+        } else {
+          log("-", "No ralph-codex hooks found in hooks.json");
+        }
+      }
+    } catch {
+      log("!", `Warning: could not parse ${hooksJsonPath}`);
+    }
+  } else {
+    log("-", "No hooks.json found");
+  }
+
+  // 2. Remove plugin directory
+  if (await fileExists(pluginDir)) {
+    log(">", `Remove plugin directory: ${pluginDir}`);
+    if (!dryRun) {
+      await rm(pluginDir, { recursive: true, force: true });
+    }
+  } else {
+    log("-", "Plugin directory not found");
+  }
+
+  // 3. Remove skill directories
+  const skillNames = ["ralph-loop", "cancel-ralph"];
+  for (const name of skillNames) {
+    const skillDir = join(skillsDir, name);
+    if (await fileExists(skillDir)) {
+      log(">", `Remove skill: ${skillDir}`);
+      if (!dryRun) {
+        await rm(skillDir, { recursive: true, force: true });
+      }
+    }
+  }
+
+  // 4. Remove state file
+  const statePath = getStatePath();
+  if (await fileExists(statePath)) {
+    log(">", `Remove state file: ${statePath}`);
+    if (!dryRun) {
+      await rm(statePath, { force: true });
+    }
+  }
+
+  console.log("");
+  if (dryRun) {
+    log("\u2714", "Dry run complete. No files were modified.");
+  } else {
+    log("\u2714", "ralph-codex uninstalled successfully.");
+  }
+  console.log("");
+}
+
+// Run directly if not imported
+const isDirectRun =
+  process.argv[1] &&
+  (process.argv[1].endsWith("uninstall.mjs") ||
+    process.argv[1].endsWith("uninstall"));
+
+if (isDirectRun) {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const local = args.includes("--local");
+
+  uninstall({ dryRun, local }).catch((err) => {
+    console.error(`\u2718 Uninstall failed: ${err.message}`);
+    process.exit(1);
+  });
+}

package/commands/cancel-ralph.md

@@ -0,0 +1,30 @@
+---
+name: cancel-ralph
+description: "Cancel the active Ralph Loop"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if the state file exists at `.codex/ralph-loop.state.json`.
+
+2. **If NOT found**: Say "No active Ralph loop found."
+
+3. **If found**:
+   - Read the state file to get `currentIteration`.
+   - Set `active` to `false` by running:
+
+   ```bash
+   node -e "
+   import { readState, writeState } from '${RALPH_CODEX_ROOT}/lib/state.mjs';
+   const state = await readState();
+   const iter = state.currentIteration;
+   state.active = false;
+   await writeState(state);
+   console.log('Cancelled Ralph loop at iteration ' + iter);
+   "
+   ```
+
+   Alternatively, edit `.codex/ralph-loop.state.json` directly and set `"active": false`.
+   - Report: "Cancelled Ralph loop (was at iteration N)."

package/commands/ralph-loop.md

@@ -0,0 +1,73 @@
+---
+name: ralph-loop
+description: "Start a Ralph Loop — self-referential iterative development loop"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+---
+
+# Ralph Loop Command
+
+You are about to start a Ralph Loop. Parse the user's arguments as follows:
+
+## Argument Parsing
+
+1. Extract `--max-iterations N` (default: 20). Must be a positive integer or 0 (unlimited).
+2. Extract `--completion-promise TEXT` (default: "TADA"). Multi-word values must be quoted.
+3. Everything else is the **prompt** — the task description.
+
+## Setup
+
+Run this command to initialize the Ralph loop state file:
+
+```bash
+node -e "
+import { writeState } from '${RALPH_CODEX_ROOT}/lib/state.mjs';
+await writeState({
+  active: true,
+  prompt: PROMPT_HERE,
+  completionPromise: PROMISE_HERE,
+  maxIterations: MAX_HERE,
+  currentIteration: 0,
+  sessionId: ''
+});
+"
+```
+
+Replace `PROMPT_HERE`, `PROMISE_HERE`, and `MAX_HERE` with the parsed values. Use proper JSON string escaping for the prompt.
+
+Alternatively, create the state file directly at `.codex/ralph-loop.state.json`:
+
+```json
+{
+  "active": true,
+  "prompt": "<user's prompt>",
+  "completionPromise": "<promise text>",
+  "maxIterations": 20,
+  "currentIteration": 0,
+  "sessionId": ""
+}
+```
+
+## After Setup
+
+Display this message to the user:
+
+```
+Ralph loop activated!
+
+Iteration: 1
+Max iterations: <N or "unlimited">
+Completion promise: <promise text>
+
+The stop hook will now block session exit and feed the SAME PROMPT back.
+Your previous work persists in files and git history.
+To cancel: /cancel-ralph
+```
+
+Then immediately begin working on the user's task prompt.
+
+## Rules
+
+- When a completion promise is set, you may ONLY output `<promise>TEXT</promise>` when the statement is genuinely and completely TRUE.
+- Do NOT output false promises to exit the loop.
+- Each iteration sees your previous work in files. Build on it incrementally.
+- If stuck, document what's blocking and try a different approach.

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "description": "Ralph Loop stop hook for self-referential iterative loops in Codex CLI",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${RALPH_CODEX_ROOT}/hooks/stop-hook.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/stop-hook.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { readState, writeState } from "../lib/state.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+function extractPromise(text, promisePhrase) {
+  const regex = new RegExp(
+    `<promise>\\s*${escapeRegex(promisePhrase)}\\s*</promise>`,
+    "s",
+  );
+  return regex.test(text);
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function getLastAssistantText(transcriptPath) {
+  if (!transcriptPath) return "";
+  try {
+    const raw = await readFile(transcriptPath, "utf-8");
+    const lines = raw.trim().split("\n");
+    const assistantLines = lines.filter((line) => {
+      try {
+        const obj = JSON.parse(line);
+        return obj.role === "assistant";
+      } catch {
+        return false;
+      }
+    });
+    const recent = assistantLines.slice(-100);
+    for (let i = recent.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(recent[i]);
+        const contents = obj.message?.content || obj.content;
+        if (Array.isArray(contents)) {
+          for (let j = contents.length - 1; j >= 0; j--) {
+            if (contents[j].type === "text" && contents[j].text) {
+              return contents[j].text;
+            }
+          }
+        } else if (typeof contents === "string") {
+          return contents;
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+  } catch {
+    // transcript not found or unreadable
+  }
+  return "";
+}
+
+async function main() {
+  let hookInput = {};
+  try {
+    const raw = await readStdin();
+    if (raw.trim()) {
+      hookInput = JSON.parse(raw);
+    }
+  } catch {
+    // no stdin or malformed — proceed with empty input
+  }
+
+  const state = await readState();
+
+  // Not active — allow exit silently
+  if (!state.active) {
+    process.exit(0);
+  }
+
+  // Session isolation: if state has a sessionId, only match that session
+  if (
+    state.sessionId &&
+    hookInput.session_id &&
+    state.sessionId !== hookInput.session_id
+  ) {
+    process.exit(0);
+  }
+
+  // Increment iteration
+  state.currentIteration += 1;
+
+  // Check max iterations
+  if (state.maxIterations > 0 && state.currentIteration > state.maxIterations) {
+    process.stderr.write(
+      `Ralph loop: max iterations (${state.maxIterations}) reached.\n`,
+    );
+    state.active = false;
+    await writeState(state);
+    process.exit(0);
+  }
+
+  // Check completion promise in transcript
+  if (state.completionPromise) {
+    const transcriptPath = hookInput.transcript_path || null;
+    const lastText =
+      hookInput.last_assistant_message ||
+      (await getLastAssistantText(transcriptPath));
+
+    if (lastText && extractPromise(lastText, state.completionPromise)) {
+      process.stderr.write(
+        `Ralph loop: completion promise "${state.completionPromise}" detected.\n`,
+      );
+      state.active = false;
+      await writeState(state);
+      process.exit(0);
+    }
+  }
+
+  // Save updated iteration
+  await writeState(state);
+
+  // Build continuation prompt
+  const iterInfo =
+    state.maxIterations > 0
+      ? `${state.currentIteration}/${state.maxIterations}`
+      : `${state.currentIteration}`;
+
+  const reason = [
+    state.prompt,
+    "",
+    "---",
+    `Ralph Loop iteration ${iterInfo}. Continue working on the task above.`,
+  ].join("\n");
+
+  const output = {
+    decision: "block",
+    reason,
+  };
+
+  if (state.completionPromise) {
+    output.systemMessage = `Ralph iteration ${iterInfo} | To stop: output <promise>${state.completionPromise}</promise> (ONLY when TRUE)`;
+  } else {
+    output.systemMessage = `Ralph iteration ${iterInfo} | No completion promise — loop runs until max iterations`;
+  }
+
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`Ralph stop-hook error: ${err.message}\n`);
+  process.exit(0);
+});

package/lib/paths.mjs

@@ -0,0 +1,41 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function isWindows() {
+  return process.platform === "win32";
+}
+
+export function getCodexHome() {
+  if (process.env.CODEX_HOME) {
+    return process.env.CODEX_HOME;
+  }
+  return join(homedir(), ".codex");
+}
+
+export function getHooksJsonPath() {
+  return join(getCodexHome(), "hooks.json");
+}
+
+export function getPluginInstallDir() {
+  return join(getCodexHome(), "plugins", "ralph-codex");
+}
+
+export function getSkillsDir() {
+  return join(getCodexHome(), "skills");
+}
+
+export function getLocalCodexDir() {
+  return join(process.cwd(), ".codex");
+}
+
+export function getLocalPluginDir() {
+  return join(getLocalCodexDir(), "plugins", "ralph-codex");
+}
+
+export function getLocalHooksJsonPath() {
+  return join(getLocalCodexDir(), "hooks.json");
+}
+
+export function getLocalSkillsDir() {
+  return join(getLocalCodexDir(), "skills");
+}

package/lib/state.mjs

@@ -0,0 +1,45 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+const DEFAULT_STATE = {
+  active: false,
+  prompt: "",
+  completionPromise: "TADA",
+  maxIterations: 20,
+  currentIteration: 0,
+  sessionId: "",
+};
+
+export function getStatePath() {
+  return (
+    process.env.RALPH_STATE_FILE ||
+    join(process.cwd(), ".codex", "ralph-loop.state.json")
+  );
+}
+
+export async function readState() {
+  const statePath = getStatePath();
+  try {
+    const raw = await readFile(statePath, "utf-8");
+    return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULT_STATE };
+  }
+}
+
+export async function writeState(state) {
+  const statePath = getStatePath();
+  await mkdir(dirname(statePath), { recursive: true });
+  await writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+}
+
+export async function resetState() {
+  await writeState({ ...DEFAULT_STATE });
+}
+
+export async function incrementIteration() {
+  const state = await readState();
+  state.currentIteration += 1;
+  await writeState(state);
+  return state;
+}

package/lib/stop-hook-core.mjs

@@ -0,0 +1,129 @@
+import { readFile } from "node:fs/promises";
+
+export function extractPromise(text, promisePhrase) {
+  const regex = new RegExp(
+    `<promise>\\s*${escapeRegex(promisePhrase)}\\s*</promise>`,
+    "s",
+  );
+  return regex.test(text);
+}
+
+export function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export async function getLastAssistantText(transcriptPath) {
+  if (!transcriptPath) return "";
+  try {
+    const raw = await readFile(transcriptPath, "utf-8");
+    const lines = raw.trim().split("\n");
+    const assistantLines = lines.filter((line) => {
+      try {
+        const obj = JSON.parse(line);
+        return obj.role === "assistant";
+      } catch {
+        return false;
+      }
+    });
+    const recent = assistantLines.slice(-100);
+    for (let i = recent.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(recent[i]);
+        const contents = obj.message?.content || obj.content;
+        if (Array.isArray(contents)) {
+          for (let j = contents.length - 1; j >= 0; j--) {
+            if (contents[j].type === "text" && contents[j].text) {
+              return contents[j].text;
+            }
+          }
+        } else if (typeof contents === "string") {
+          return contents;
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+  } catch {
+    // transcript not found or unreadable
+  }
+  return "";
+}
+
+export async function processStopHook(hookInput, readStateFn, writeStateFn) {
+  const stderr = [];
+  const state = await readStateFn();
+
+  // Not active — allow exit
+  if (!state.active) {
+    return { exitCode: 0, stdout: "", stderr: "" };
+  }
+
+  // Session isolation
+  if (
+    state.sessionId &&
+    hookInput.session_id &&
+    state.sessionId !== hookInput.session_id
+  ) {
+    return { exitCode: 0, stdout: "", stderr: "" };
+  }
+
+  // Increment iteration
+  state.currentIteration += 1;
+
+  // Check max iterations
+  if (state.maxIterations > 0 && state.currentIteration > state.maxIterations) {
+    stderr.push(
+      `Ralph loop: max iterations (${state.maxIterations}) reached.\n`,
+    );
+    state.active = false;
+    await writeStateFn(state);
+    return { exitCode: 0, stdout: "", stderr: stderr.join("") };
+  }
+
+  // Check completion promise
+  if (state.completionPromise) {
+    const transcriptPath = hookInput.transcript_path || null;
+    const lastText =
+      hookInput.last_assistant_message ||
+      (await getLastAssistantText(transcriptPath));
+
+    if (lastText && extractPromise(lastText, state.completionPromise)) {
+      stderr.push(
+        `Ralph loop: completion promise "${state.completionPromise}" detected.\n`,
+      );
+      state.active = false;
+      await writeStateFn(state);
+      return { exitCode: 0, stdout: "", stderr: stderr.join("") };
+    }
+  }
+
+  // Save updated iteration
+  await writeStateFn(state);
+
+  // Build continuation prompt
+  const iterInfo =
+    state.maxIterations > 0
+      ? `${state.currentIteration}/${state.maxIterations}`
+      : `${state.currentIteration}`;
+
+  const reason = [
+    state.prompt,
+    "",
+    "---",
+    `Ralph Loop iteration ${iterInfo}. Continue working on the task above.`,
+  ].join("\n");
+
+  const output = { decision: "block", reason };
+
+  if (state.completionPromise) {
+    output.systemMessage = `Ralph iteration ${iterInfo} | To stop: output <promise>${state.completionPromise}</promise> (ONLY when TRUE)`;
+  } else {
+    output.systemMessage = `Ralph iteration ${iterInfo} | No completion promise — loop runs until max iterations`;
+  }
+
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify(output),
+    stderr: stderr.join(""),
+  };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@graypark/ralph-codex",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Ralph Loop for OpenAI Codex CLI — self-referential iterative development loops via Stop hooks",
+  "license": "MIT",
+  "author": "graypark",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Viewcommz/ralph-codex"
+  },
+  "homepage": "https://github.com/Viewcommz/ralph-codex#readme",
+  "bugs": {
+    "url": "https://github.com/Viewcommz/ralph-codex/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ralph-codex": "./bin/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "hooks/",
+    "commands/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "postinstall": "echo 'Run: npx ralph-codex --help'"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "codex",
+    "ralph-loop",
+    "autonomous",
+    "ai-agent",
+    "iterative-development",
+    "stop-hook",
+    "cross-platform"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  }
+}