@graypark/loophaus 2.0.0

package/bin/loophaus.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// loophaus CLI — install, status, stats, uninstall
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { access } from "node:fs/promises";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+
+const args = process.argv.slice(2);
+const command = args[0] || "install";
+const dryRun = args.includes("--dry-run");
+const force = args.includes("--force");
+const local = args.includes("--local");
+const showHelp = args.includes("--help") || args.includes("-h");
+
+function getHost() {
+  if (args.includes("--claude")) return "claude-code";
+  if (args.includes("--kiro")) return "kiro-cli";
+  const idx = args.indexOf("--host");
+  if (idx !== -1 && args[idx + 1]) return args[idx + 1];
+  return null;
+}
+
+const host = getHost();
+
+if (showHelp || command === "help") {
+  console.log(`loophaus — Control plane for coding agents
+
+Usage:
+  npx @graypark/loophaus install [--host <name>] [--force] [--dry-run]
+  npx @graypark/loophaus uninstall [--host <name>]
+  npx @graypark/loophaus status
+  npx @graypark/loophaus stats
+  npx @graypark/loophaus --version
+
+Hosts:
+  claude-code    Claude Code (auto-detected via ~/.claude/)
+  codex-cli      Codex CLI (auto-detected via ~/.codex/)
+  kiro-cli       Kiro CLI (auto-detected via ~/.kiro/)
+
+Install auto-detects available hosts if --host is not specified.
+
+Options:
+  --host <name>  Target a specific host
+  --claude       Shorthand for --host claude-code
+  --kiro         Shorthand for --host kiro-cli
+  --local        Install to project-local .codex/ (Codex only)
+  --force        Overwrite existing installation
+  --dry-run      Preview changes without modifying files
+`);
+  process.exit(0);
+}
+
+if (args.includes("--version")) {
+  const { getPackageVersion } = await import("../lib/paths.mjs");
+  console.log(getPackageVersion());
+  process.exit(0);
+}
+
+async function detectHosts() {
+  const hosts = [];
+  const { detect: detectClaude } = await import("../platforms/claude-code/installer.mjs");
+  const { detect: detectCodex } = await import("../platforms/codex-cli/installer.mjs");
+  const { detect: detectKiro } = await import("../platforms/kiro-cli/installer.mjs");
+
+  if (await detectClaude()) hosts.push("claude-code");
+  if (await detectCodex()) hosts.push("codex-cli");
+  if (await detectKiro()) hosts.push("kiro-cli");
+  return hosts;
+}
+
+async function runInstall() {
+  let targets = [];
+
+  if (host) {
+    targets = [host];
+  } else {
+    targets = await detectHosts();
+    if (targets.length === 0) {
+      console.log("No supported hosts detected. Install Claude Code, Codex CLI, or Kiro CLI first.");
+      console.log("Or specify a host: npx @graypark/loophaus install --host claude-code");
+      process.exit(1);
+    }
+    console.log(`Detected hosts: ${targets.join(", ")}\n`);
+  }
+
+  for (const t of targets) {
+    if (t === "claude-code") {
+      const { install } = await import("../platforms/claude-code/installer.mjs");
+      await install({ dryRun, force });
+    } else if (t === "codex-cli") {
+      const { install } = await import("../platforms/codex-cli/installer.mjs");
+      await install({ dryRun, force, local });
+    } else if (t === "kiro-cli") {
+      const { install } = await import("../platforms/kiro-cli/installer.mjs");
+      await install({ dryRun, force });
+    } else {
+      console.log(`Unknown host: ${t}`);
+    }
+  }
+}
+
+async function runUninstall() {
+  if (host === "claude-code" || args.includes("--claude")) {
+    const { uninstall } = await import("./uninstall.mjs");
+    await uninstall({ dryRun, claude: true });
+  } else if (host === "kiro-cli" || args.includes("--kiro")) {
+    const { uninstall } = await import("../platforms/kiro-cli/installer.mjs");
+    await uninstall({ dryRun });
+  } else {
+    const { uninstall } = await import("./uninstall.mjs");
+    await uninstall({ dryRun, local });
+  }
+}
+
+async function runStatus() {
+  const { read } = await import("../store/state-store.mjs");
+  const state = await read();
+  if (!state.active) {
+    console.log("No active loop.");
+    return;
+  }
+  const iterInfo = state.maxIterations > 0
+    ? `${state.currentIteration}/${state.maxIterations}`
+    : `${state.currentIteration}`;
+  console.log(`Loop Status`);
+  console.log(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+  console.log(`Active:     yes`);
+  console.log(`Iteration:  ${iterInfo}`);
+  console.log(`Promise:    ${state.completionPromise || "(none)"}`);
+
+  try {
+    const { readFile } = await import("node:fs/promises");
+    const prd = JSON.parse(await readFile("prd.json", "utf-8"));
+    if (Array.isArray(prd.userStories)) {
+      const done = prd.userStories.filter(s => s.passes === true).length;
+      const total = prd.userStories.length;
+      console.log("");
+      console.log("Stories");
+      console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      for (const s of prd.userStories) {
+        const icon = s.passes ? "\u2713" : " ";
+        console.log(`  ${icon} ${s.id}  ${s.title}`);
+      }
+      console.log(`\n  Progress: ${done}/${total} done`);
+    }
+  } catch { /* no prd.json */ }
+}
+
+async function runStats() {
+  const { readTrace } = await import("../core/event-logger.mjs");
+  const events = await readTrace();
+  if (events.length === 0) {
+    console.log("No trace data found. Run a loop first.");
+    return;
+  }
+  const iterations = events.filter(e => e.event === "iteration").length;
+  const stops = events.filter(e => e.event === "stop");
+  const lastStop = stops[stops.length - 1];
+  console.log(`Loop Stats`);
+  console.log(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+  console.log(`Total iterations: ${iterations}`);
+  console.log(`Total stops:      ${stops.length}`);
+  if (lastStop) {
+    console.log(`Last stop reason: ${lastStop.reason || "unknown"}`);
+    console.log(`Last stop at:     ${lastStop.ts || "unknown"}`);
+  }
+  console.log(`Trace file:       .loophaus/trace.jsonl (${events.length} events)`);
+}
+
+try {
+  switch (command) {
+    case "install": await runInstall(); break;
+    case "uninstall": await runUninstall(); break;
+    case "status": await runStatus(); break;
+    case "stats": await runStats(); break;
+    default:
+      if (command.startsWith("-")) {
+        await runInstall();
+      } else {
+        console.log(`Unknown command: ${command}`);
+        console.log("Run: npx @graypark/loophaus --help");
+        process.exit(1);
+      }
+  }
+} catch (err) {
+  console.error(`\u2718 ${err.message}`);
+  process.exit(1);
+}

package/bin/uninstall.mjs

@@ -0,0 +1,233 @@
+#!/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,
+  getClaudePluginCacheDir,
+  getClaudeSettingsPath,
+  getClaudeInstalledPluginsPath,
+} from "../lib/paths.mjs";
+import { getStatePath } from "../lib/state.mjs";
+
+const RALPH_HOOK_MARKER = "loophaus";
+
+function log(icon, msg) {
+  console.log(`  ${icon} ${msg}`);
+}
+
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function uninstallClaude({ dryRun = false } = {}) {
+  console.log("");
+  console.log(
+    `loophaus uninstaller — Claude Code${dryRun ? " (DRY RUN)" : ""}`,
+  );
+  console.log("");
+
+  // 1. Remove plugin cache directory
+  const cacheDir = getClaudePluginCacheDir();
+  if (await fileExists(cacheDir)) {
+    log(">", `Remove plugin cache: ${cacheDir}`);
+    if (!dryRun) {
+      await rm(cacheDir, { recursive: true, force: true });
+    }
+  } else {
+    log("-", "Plugin cache not found");
+  }
+
+  // 2. Remove from installed_plugins.json
+  const installedPluginsPath = getClaudeInstalledPluginsPath();
+  if (await fileExists(installedPluginsPath)) {
+    try {
+      const raw = await readFile(installedPluginsPath, "utf-8");
+      const data = JSON.parse(raw);
+      const pluginKey = "loophaus@loophaus-marketplace";
+      if (data.plugins && data.plugins[pluginKey]) {
+        delete data.plugins[pluginKey];
+        log(">", `Remove ${pluginKey} from installed_plugins.json`);
+        if (!dryRun) {
+          await writeFile(
+            installedPluginsPath,
+            JSON.stringify(data, null, 2),
+            "utf-8",
+          );
+        }
+      } else {
+        log("-", "Plugin not found in installed_plugins.json");
+      }
+    } catch {
+      log("!", "Warning: could not parse installed_plugins.json");
+    }
+  }
+
+  // 3. Remove from settings.json
+  const settingsPath = getClaudeSettingsPath();
+  if (await fileExists(settingsPath)) {
+    try {
+      const raw = await readFile(settingsPath, "utf-8");
+      const settings = JSON.parse(raw);
+      const pluginKey = "loophaus@loophaus-marketplace";
+      if (
+        settings.enabledPlugins &&
+        settings.enabledPlugins[pluginKey] !== undefined
+      ) {
+        delete settings.enabledPlugins[pluginKey];
+        log(">", `Disable ${pluginKey} in settings.json`);
+        if (!dryRun) {
+          await writeFile(
+            settingsPath,
+            JSON.stringify(settings, null, 2),
+            "utf-8",
+          );
+        }
+      }
+    } catch {
+      log("!", "Warning: could not parse settings.json");
+    }
+  }
+
+  console.log("");
+  if (dryRun) {
+    log("\u2714", "Dry run complete. No files were modified.");
+  } else {
+    log("\u2714", "loophaus uninstalled from Claude Code.");
+    console.log("");
+    console.log("  Run /reload-plugins in Claude Code to apply.");
+  }
+  console.log("");
+}
+
+export async function uninstall({
+  dryRun = false,
+  local = false,
+  claude = false,
+} = {}) {
+  if (claude) {
+    return uninstallClaude({ dryRun });
+  }
+
+  const pluginDir = local ? getLocalPluginDir() : getPluginInstallDir();
+  const hooksJsonPath = local ? getLocalHooksJsonPath() : getHooksJsonPath();
+  const skillsDir = local ? getLocalSkillsDir() : getSkillsDir();
+
+  console.log("");
+  console.log(
+    `loophaus uninstaller — Codex CLI${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 loophaus 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",
+    "ralph-interview",
+    "ralph-orchestrator",
+    "ralph-claude-interview",
+    "ralph-claude-loop",
+    "ralph-claude-cancel",
+    "ralph-claude-orchestrator",
+  ];
+  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", "loophaus 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");
+  const claude = args.includes("--claude");
+
+  uninstall({ dryRun, local, claude }).catch((err) => {
+    console.error(`\u2718 Uninstall failed: ${err.message}`);
+    process.exit(1);
+  });
+}

package/codex/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/codex/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/commands/cancel-ralph.md

@@ -0,0 +1,23 @@
+---
+description: "Cancel active Ralph Loop"
+allowed-tools:
+  [
+    "Bash(test -f .claude/ralph-loop.local.md:*)",
+    "Bash(rm .claude/ralph-loop.local.md)",
+    "Read(.claude/ralph-loop.local.md)",
+  ]
+hide-from-slash-command-tool: "true"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+
+3. **If EXISTS**:
+   - Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/commands/help.md

@@ -0,0 +1,96 @@
+---
+description: "Explain loophaus plugin and available commands"
+---
+
+# Loophaus Plugin Help
+
+Please explain the following to the user:
+
+## What is Loop?
+
+Loop implements the Ralph Wiggum technique — an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
+
+**Core concept:**
+
+```bash
+while :; do
+  cat PROMPT.md | claude-code --continue
+done
+```
+
+The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
+
+**Each iteration:**
+
+1. Claude receives the SAME prompt
+2. Works on the task, modifying files
+3. Tries to exit
+4. Stop hook intercepts and feeds the same prompt again
+5. Claude sees its previous work in the files
+6. Iteratively improves until completion
+
+## Available Commands
+
+### /loop <PROMPT> [OPTIONS]
+
+Start a loop in your current session.
+
+**Usage:**
+
+```
+/loop "Refactor the cache layer" --max-iterations 20
+/loop "Add tests" --completion-promise "TESTS COMPLETE"
+```
+
+**Options:**
+
+- `--max-iterations <n>` — Max iterations before auto-stop
+- `--completion-promise <text>` — Promise phrase to signal completion
+
+### /loop-stop
+
+Stop an active loop (removes the loop state file).
+
+### /loop-plan
+
+Interactive interview that generates a PRD with right-sized stories, activates the loop, and starts implementing story by story.
+
+**Usage:**
+
+```
+/loop-plan Add user authentication with JWT and login UI
+```
+
+### /loop-pulse
+
+Check the status of an active loop, including iteration count and story progress.
+
+### /loop-orchestrator
+
+Multi-agent orchestration patterns for parallel work streams.
+
+## Available Skills (via Skill tool)
+
+- `loophaus:ralph-interview` — PRD generation + loop start
+- `loophaus:ralph-orchestrator` — Multi-agent patterns
+- `loophaus:ralph-loop` — Direct loop execution
+- `loophaus:cancel-ralph` — Cancel active loop
+
+## Key Concepts
+
+### Completion Promises
+
+To signal completion, Claude must output a `<promise>` tag:
+
+```
+<promise>TASK COMPLETE</promise>
+```
+
+### PRD-driven Loops
+
+loophaus extends basic Loop with PRD (prd.json) and progress tracking (progress.txt), enabling story-by-story implementation with learnings carried across iterations.
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- loophaus: https://github.com/vcz-Gray/ralph-codex

package/commands/loop-plan.md

@@ -0,0 +1,55 @@
+---
+description: "Plan and start loop via interactive interview"
+argument-hint: "TASK_DESCRIPTION"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Agent", "Skill"]
+---
+
+# /loop-plan — Interactive Planning & Loop
+
+## Phase 1: Discovery Interview
+
+Ask the user 3-5 focused questions about $ARGUMENTS to understand:
+- What exactly needs to be built
+- Acceptance criteria
+- Technical constraints
+- Dependencies
+
+## Phase 2: PRD Generation
+
+Generate `prd.json` with user stories:
+
+```json
+{
+  "title": "<project title>",
+  "userStories": [
+    { "id": "US-001", "title": "<story>", "acceptance": "<criteria>", "passes": false },
+    ...
+  ]
+}
+```
+
+Right-size stories: each should be completable in 1-2 loop iterations.
+
+## Phase 3: Loop Activation
+
+After PRD approval, initialize the loop:
+
+1. Create `.loophaus/state.json`:
+```json
+{
+  "active": true,
+  "prompt": "<implementation prompt based on PRD>",
+  "completionPromise": "TASK COMPLETE",
+  "maxIterations": <stories * 2 + 3>,
+  "currentIteration": 0,
+  "sessionId": ""
+}
+```
+
+2. Start working on US-001 immediately.
+
+## Rules
+
+- Each iteration: pick next pending story, implement, verify, mark passes=true if done
+- Update `progress.txt` with status after each story
+- Use `<promise>TASK COMPLETE</promise>` ONLY when ALL stories pass