cralph 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mguleryuz
+
+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,88 @@
+# cralph
+
+Claude in a loop. Point at refs, give it rules, let it cook.
+
+```
+refs/  ──loop──>  output/
+(source)   │      (result)
+           │
+        rules.md
+```
+
+## What is Ralph?
+
+[Ralph](https://ghuntley.com/ralph/) is a technique: run Claude in a loop until it signals completion.
+
+```bash
+while :; do cat PROMPT.md | claude -p ; done
+```
+
+cralph wraps this into a CLI with path selection and logging.
+
+## Install
+
+```bash
+bun add -g cralph
+```
+
+Or with npm:
+
+```bash
+npm install -g cralph
+```
+
+## Usage
+
+```bash
+# Interactive - prompts for everything
+cralph
+
+# With flags
+cralph --refs ./source --rules ./rules.md --output ./out
+
+# With config file
+cralph --paths-file ralph.paths.json
+```
+
+## Path Selection
+
+When prompted, choose how to specify each path:
+
+| Mode | What it does |
+|------|--------------|
+| Select from cwd | Pick directories/files interactively |
+| Manual | Type the path |
+| Paths file | Load from JSON config |
+
+## Config File
+
+```json
+{
+  "refs": ["./refs", "./more-refs"],
+  "rules": "./.cursor/rules/my-rules.mdc",
+  "output": "./output"
+}
+```
+
+Name it `ralph.paths.json` and cralph auto-detects it.
+
+## How It Works
+
+1. Reads your source material from `refs/`
+2. Injects your rules into the prompt
+3. Runs `claude -p --dangerously-skip-permissions` in a loop
+4. Stops when Claude outputs `<promise>COMPLETE</promise>`
+
+## Requirements
+
+- [Bun](https://bun.sh)
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+
+## Warning
+
+Runs with `--dangerously-skip-permissions`. Review output regularly.
+
+## Resources
+
+- [Ralph / Geoff Huntley](https://ghuntley.com/ralph/)
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)

package/index.ts

@@ -0,0 +1,5 @@
+// Re-export for programmatic usage
+export * from "./src/types";
+export { buildConfig, loadPathsFile, validateConfig } from "./src/paths";
+export { createPrompt, buildPrompt } from "./src/prompt";
+export { run } from "./src/runner";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "cralph",
+  "version": "1.0.0-alpha.0",
+  "description": "Claude in a loop. Point at refs, give it rules, let it cook.",
+  "author": "mguleryuz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mguleryuz/cralph"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "cli",
+    "automation",
+    "ralph",
+    "loop",
+    "bun"
+  ],
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "cralph": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run src/cli.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "citty": "^0.2.0",
+    "consola": "^3.4.2"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env bun
+
+import { defineCommand, runMain } from "citty";
+import { consola } from "consola";
+import { resolve } from "path";
+import {
+  buildConfig,
+  loadPathsFile,
+  validateConfig,
+  selectRefs,
+  selectRules,
+  selectOutput,
+} from "./paths";
+import { run } from "./runner";
+import type { RalphConfig } from "./types";
+
+const main = defineCommand({
+  meta: {
+    name: "cralph",
+    version: "1.0.0",
+    description: "Claude in a loop. Point at refs, give it rules, let it cook.",
+  },
+  args: {
+    refs: {
+      type: "string",
+      description: "Comma-separated refs paths (source material)",
+      required: false,
+    },
+    rules: {
+      type: "string",
+      description: "Path to rules file (.mdc or .md)",
+      required: false,
+    },
+    output: {
+      type: "string",
+      description: "Output directory",
+      required: false,
+    },
+    "paths-file": {
+      type: "string",
+      description: "Path to configuration file (JSON)",
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = process.cwd();
+    let config: RalphConfig;
+
+    try {
+      // If paths-file is provided, use it
+      if (args["paths-file"]) {
+        const pathsFilePath = resolve(cwd, args["paths-file"]);
+        consola.info(`Loading config from ${pathsFilePath}`);
+        const loaded = await loadPathsFile(pathsFilePath);
+        config = {
+          refs: loaded.refs.map((r) => resolve(cwd, r)),
+          rules: resolve(cwd, loaded.rules),
+          output: resolve(cwd, loaded.output),
+        };
+      }
+      // If all args are provided via CLI flags
+      else if (args.refs && args.rules && args.output) {
+        config = {
+          refs: args.refs.split(",").map((r) => resolve(cwd, r.trim())),
+          rules: resolve(cwd, args.rules),
+          output: resolve(cwd, args.output),
+        };
+      }
+      // Interactive mode - some or no args provided
+      else {
+        consola.info("Interactive configuration mode\n");
+
+        // Use provided args or prompt for missing ones
+        let refs: string[];
+        if (args.refs) {
+          refs = args.refs.split(",").map((r) => resolve(cwd, r.trim()));
+        } else {
+          refs = await selectRefs(cwd);
+        }
+
+        let rules: string;
+        if (args.rules) {
+          rules = resolve(cwd, args.rules);
+        } else {
+          rules = await selectRules(cwd);
+        }
+
+        let output: string;
+        if (args.output) {
+          output = resolve(cwd, args.output);
+        } else {
+          output = await selectOutput(cwd);
+        }
+
+        config = { refs, rules, output };
+      }
+
+      // Validate configuration
+      consola.info("Validating configuration...");
+      await validateConfig(config);
+
+      // Show config summary
+      consola.info("Configuration:");
+      consola.info(`  Refs: ${config.refs.join(", ")}`);
+      consola.info(`  Rules: ${config.rules}`);
+      consola.info(`  Output: ${config.output}`);
+      console.log();
+
+      // Confirm before running
+      const proceed = await consola.prompt("Start processing?", {
+        type: "confirm",
+        initial: true,
+      });
+
+      if (proceed !== true) {
+        consola.info("Cancelled.");
+        process.exit(0);
+      }
+
+      // Run the main loop
+      await run(config);
+    } catch (error) {
+      if (error instanceof Error) {
+        consola.error(error.message);
+      } else {
+        consola.error("An unexpected error occurred");
+      }
+      process.exit(1);
+    }
+  },
+});
+
+runMain(main);

package/src/paths.ts

@@ -0,0 +1,263 @@
+import { consola } from "consola";
+import { resolve, join, basename } from "path";
+import { readdir, stat } from "fs/promises";
+import type { PathSelectionMode, PathsFileConfig, RalphConfig } from "./types";
+
+/**
+ * List directories in a given path
+ */
+async function listDirectories(basePath: string): Promise<string[]> {
+  const entries = await readdir(basePath, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+    .map((e) => e.name);
+}
+
+/**
+ * List files matching patterns in a directory (recursive)
+ */
+async function listFilesRecursive(
+  basePath: string,
+  extensions: string[]
+): Promise<string[]> {
+  const results: string[] = [];
+
+  async function walk(dir: string) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".")) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        if (extensions.some((ext) => entry.name.endsWith(ext))) {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+
+  await walk(basePath);
+  return results;
+}
+
+/**
+ * Prompt user for path selection mode
+ */
+async function askSelectionMode(label: string): Promise<PathSelectionMode> {
+  const mode = await consola.prompt(`How would you like to specify ${label}?`, {
+    type: "select",
+    options: [
+      { label: "Select from current directory", value: "select" },
+      { label: "Enter path manually", value: "manual" },
+      { label: "Use paths file", value: "file" },
+    ],
+  });
+
+  if (typeof mode === "symbol") {
+    throw new Error("Selection cancelled");
+  }
+
+  return mode as PathSelectionMode;
+}
+
+/**
+ * Load configuration from a paths file
+ */
+export async function loadPathsFile(filePath: string): Promise<PathsFileConfig> {
+  const file = Bun.file(filePath);
+  if (!(await file.exists())) {
+    throw new Error(`Paths file not found: ${filePath}`);
+  }
+  const content = await file.json();
+  return content as PathsFileConfig;
+}
+
+/**
+ * Prompt user to select refs directories
+ */
+export async function selectRefs(cwd: string): Promise<string[]> {
+  const mode = await askSelectionMode("refs (reference material)");
+
+  if (mode === "manual") {
+    const input = await consola.prompt(
+      "Enter refs paths (comma-separated):",
+      { type: "text" }
+    );
+    if (typeof input === "symbol") throw new Error("Selection cancelled");
+    return input
+      .split(",")
+      .map((p) => resolve(cwd, p.trim()))
+      .filter(Boolean);
+  }
+
+  if (mode === "select") {
+    const dirs = await listDirectories(cwd);
+    if (dirs.length === 0) {
+      consola.warn("No directories found in current directory");
+      return selectRefs(cwd); // retry
+    }
+
+    const selected = await consola.prompt("Select refs directories:", {
+      type: "multiselect",
+      options: dirs.map((d) => ({ label: d, value: d })),
+    });
+
+    if (typeof selected === "symbol") throw new Error("Selection cancelled");
+    return (selected as string[]).map((d) => resolve(cwd, d));
+  }
+
+  // file mode - will be handled at config level
+  throw new Error("Use loadPathsFile for file-based configuration");
+}
+
+/**
+ * Prompt user to select a rules file
+ */
+export async function selectRules(cwd: string): Promise<string> {
+  const mode = await askSelectionMode("rules file");
+
+  if (mode === "manual") {
+    const input = await consola.prompt("Enter rules file path:", {
+      type: "text",
+    });
+    if (typeof input === "symbol") throw new Error("Selection cancelled");
+    return resolve(cwd, input.trim());
+  }
+
+  if (mode === "select") {
+    const files = await listFilesRecursive(cwd, [".mdc", ".md"]);
+    if (files.length === 0) {
+      consola.warn("No .mdc or .md files found");
+      return selectRules(cwd); // retry
+    }
+
+    // Show relative paths for readability
+    const options = files.map((f) => ({
+      label: f.replace(cwd + "/", ""),
+      value: f,
+    }));
+
+    const selected = await consola.prompt("Select rules file:", {
+      type: "select",
+      options,
+    });
+
+    if (typeof selected === "symbol") throw new Error("Selection cancelled");
+    return selected as string;
+  }
+
+  throw new Error("Use loadPathsFile for file-based configuration");
+}
+
+/**
+ * Prompt user to select output directory
+ */
+export async function selectOutput(cwd: string): Promise<string> {
+  const mode = await askSelectionMode("output directory");
+
+  if (mode === "manual") {
+    const input = await consola.prompt("Enter output directory path:", {
+      type: "text",
+      default: "./docs",
+    });
+    if (typeof input === "symbol") throw new Error("Selection cancelled");
+    return resolve(cwd, input.trim());
+  }
+
+  if (mode === "select") {
+    const dirs = await listDirectories(cwd);
+    const options = [
+      { label: "(create new)", value: "__new__" },
+      ...dirs.map((d) => ({ label: d, value: d })),
+    ];
+
+    const selected = await consola.prompt("Select output directory:", {
+      type: "select",
+      options,
+    });
+
+    if (typeof selected === "symbol") throw new Error("Selection cancelled");
+
+    if (selected === "__new__") {
+      const newDir = await consola.prompt("Enter new directory name:", {
+        type: "text",
+        default: "docs",
+      });
+      if (typeof newDir === "symbol") throw new Error("Selection cancelled");
+      return resolve(cwd, newDir.trim());
+    }
+
+    return resolve(cwd, selected as string);
+  }
+
+  throw new Error("Use loadPathsFile for file-based configuration");
+}
+
+/**
+ * Check if a paths file exists and offer to use it
+ */
+export async function checkForPathsFile(cwd: string): Promise<string | null> {
+  const candidates = ["ralph.paths.json", ".ralph.paths.json", "paths.json"];
+
+  for (const candidate of candidates) {
+    const filePath = join(cwd, candidate);
+    const file = Bun.file(filePath);
+    if (await file.exists()) {
+      const useIt = await consola.prompt(
+        `Found ${candidate}. Use it for configuration?`,
+        { type: "confirm", initial: true }
+      );
+      if (useIt === true) {
+        return filePath;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate that paths exist
+ */
+export async function validateConfig(config: RalphConfig): Promise<void> {
+  // Check refs
+  for (const ref of config.refs) {
+    try {
+      await stat(ref);
+    } catch {
+      throw new Error(`Refs path does not exist: ${ref}`);
+    }
+  }
+
+  // Check rules file
+  const rulesFile = Bun.file(config.rules);
+  if (!(await rulesFile.exists())) {
+    throw new Error(`Rules file does not exist: ${config.rules}`);
+  }
+
+  // Output directory will be created if needed
+}
+
+/**
+ * Interactive configuration builder
+ */
+export async function buildConfig(cwd: string): Promise<RalphConfig> {
+  // Check for existing paths file first
+  const pathsFile = await checkForPathsFile(cwd);
+
+  if (pathsFile) {
+    const loaded = await loadPathsFile(pathsFile);
+    return {
+      refs: loaded.refs.map((r) => resolve(cwd, r)),
+      rules: resolve(cwd, loaded.rules),
+      output: resolve(cwd, loaded.output),
+    };
+  }
+
+  // Interactive selection
+  const refs = await selectRefs(cwd);
+  const rules = await selectRules(cwd);
+  const output = await selectOutput(cwd);
+
+  return { refs, rules, output };
+}

package/src/prompt.ts

@@ -0,0 +1,59 @@
+import type { RalphConfig } from "./types";
+
+/**
+ * The main ralph prompt template.
+ * Generic prompt for any Ralph use case.
+ */
+const BASE_PROMPT = `You are an autonomous agent running in a loop.
+
+FIRST: Read and internalize the rules provided below.
+
+Your job is to process source material from the refs paths into the output directory.
+
+**CRITICAL: refs paths are READ-ONLY.** Never delete, move, or modify files in refs. Only create files in the output directory.
+
+Follow the rules to determine how to process each file. Track what you've done to avoid duplicate work.
+
+STOPPING CONDITION: When all source files have been processed according to the rules, output exactly:
+
+<promise>COMPLETE</promise>
+
+This signals the automation to stop. Only output this tag when truly done.`;
+
+/**
+ * Build the complete prompt with config and rules injected
+ */
+export function buildPrompt(config: RalphConfig, rulesContent: string): string {
+  const refsList = config.refs.map((r) => `- ${r}`).join("\n");
+
+  return `${BASE_PROMPT}
+
+---
+
+## Configuration
+
+**Refs paths (read-only source material):**
+${refsList}
+
+**Output directory:**
+${config.output}
+
+---
+
+## Rules
+
+The following rules define how to classify, refine, and write documentation:
+
+${rulesContent}
+`;
+}
+
+/**
+ * Read rules file and build complete prompt
+ */
+export async function createPrompt(config: RalphConfig): Promise<string> {
+  const rulesFile = Bun.file(config.rules);
+  const rulesContent = await rulesFile.text();
+
+  return buildPrompt(config, rulesContent);
+}

package/src/runner.ts

@@ -0,0 +1,188 @@
+import { consola } from "consola";
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import type { RalphConfig, RunnerState, IterationResult } from "./types";
+import { createPrompt } from "./prompt";
+
+const COMPLETION_SIGNAL = "<promise>COMPLETE</promise>";
+
+/**
+ * Initialize the runner state and log file
+ */
+async function initRunner(outputDir: string): Promise<RunnerState> {
+  const ralphDir = join(outputDir, ".ralph");
+  await mkdir(ralphDir, { recursive: true });
+
+  const state: RunnerState = {
+    iteration: 0,
+    startTime: new Date(),
+    logFile: join(ralphDir, "ralph.log"),
+    todoFile: join(ralphDir, "TODO.md"),
+  };
+
+  // Initialize log file
+  const logHeader = `═══════════════════════════════════════
+Ralph Session: ${state.startTime.toISOString()}
+═══════════════════════════════════════\n`;
+
+  await Bun.write(state.logFile, logHeader);
+
+  // Initialize TODO file if not exists
+  const todoFile = Bun.file(state.todoFile);
+  if (!(await todoFile.exists())) {
+    await Bun.write(
+      state.todoFile,
+      `# Ralph Agent Status
+
+## Current Status
+
+Idle - waiting for documents in refs/
+
+## Processed Files
+
+_None yet_
+
+## Pending
+
+_Check refs/ for new documents_
+`
+    );
+  }
+
+  return state;
+}
+
+/**
+ * Append to log file
+ */
+async function log(state: RunnerState, message: string): Promise<void> {
+  const timestamp = new Date().toLocaleTimeString();
+  const logLine = `[${timestamp}] ${message}\n`;
+  const file = Bun.file(state.logFile);
+  const existing = await file.text();
+  await Bun.write(state.logFile, existing + logLine);
+}
+
+/**
+ * Count files in refs directories (excluding .gitkeep and hidden files)
+ */
+async function countRefs(refs: string[]): Promise<number> {
+  let count = 0;
+
+  for (const refPath of refs) {
+    try {
+      const entries = await Array.fromAsync(
+        new Bun.Glob("**/*").scan({ cwd: refPath, onlyFiles: true })
+      );
+      count += entries.filter(
+        (e) => !e.startsWith(".") && !e.includes("/.") && e !== ".gitkeep"
+      ).length;
+    } catch {
+      // Directory might not exist or be empty
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Run a single Claude iteration
+ */
+async function runIteration(
+  prompt: string,
+  state: RunnerState,
+  cwd: string
+): Promise<IterationResult> {
+  state.iteration++;
+
+  consola.info(`Iteration ${state.iteration} — invoking Claude...`);
+  await log(state, `Iteration ${state.iteration} starting`);
+
+  // Run claude with the prompt piped in
+  const proc = Bun.spawn(["claude", "-p", "--dangerously-skip-permissions"], {
+    stdin: new Blob([prompt]),
+    stdout: "pipe",
+    stderr: "pipe",
+    cwd,
+  });
+
+  // Collect output
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  const output = stdout + stderr;
+
+  // Log output
+  await log(state, output);
+
+  // Check for completion signal
+  const isComplete = output.includes(COMPLETION_SIGNAL);
+
+  if (isComplete) {
+    consola.success(
+      `Complete! All files processed in ${state.iteration} iteration(s).`
+    );
+  } else if (exitCode === 0) {
+    consola.info(`Iteration ${state.iteration} complete`);
+  } else {
+    consola.warn(`Iteration ${state.iteration} exited with code ${exitCode}`);
+  }
+
+  // Print Claude's output
+  console.log(output);
+
+  return { exitCode, output, isComplete };
+}
+
+/**
+ * Main runner loop
+ */
+export async function run(config: RalphConfig): Promise<void> {
+  const cwd = process.cwd();
+
+  consola.box("cralph");
+  consola.info("Starting ralph...");
+
+  // Initialize state
+  const state = await initRunner(config.output);
+  consola.info(`Log: ${state.logFile}`);
+  consola.info(`TODO: ${state.todoFile}`);
+
+  // Count initial refs
+  const initialCount = await countRefs(config.refs);
+  consola.info(`Found ${initialCount} files to process`);
+
+  if (initialCount === 0) {
+    consola.warn("No files found in refs directories");
+    return;
+  }
+
+  // Build prompt once
+  const prompt = await createPrompt(config);
+
+  // Ensure output directory exists
+  await mkdir(config.output, { recursive: true });
+
+  consola.info("Press Ctrl+C to stop\n");
+
+  // Main loop
+  while (true) {
+    console.log("━".repeat(40));
+
+    const refCount = await countRefs(config.refs);
+    consola.info(`${refCount} ref files remaining`);
+
+    const result = await runIteration(prompt, state, cwd);
+
+    if (result.isComplete) {
+      break;
+    }
+
+    // Small delay between iterations
+    await Bun.sleep(2000);
+  }
+
+  const duration = (Date.now() - state.startTime.getTime()) / 1000;
+  consola.success(`Finished in ${duration.toFixed(1)}s`);
+}

package/src/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Path selection mode for CLI prompts
+ */
+export type PathSelectionMode = "manual" | "select" | "file";
+
+/**
+ * Configuration loaded from a paths file (e.g., ralph.paths.json)
+ */
+export interface PathsFileConfig {
+  refs: string[];
+  rules: string;
+  output: string;
+}
+
+/**
+ * Resolved configuration after path selection
+ */
+export interface RalphConfig {
+  /** Paths to reference material directories/files */
+  refs: string[];
+  /** Path to the rules file (.mdc or .md) */
+  rules: string;
+  /** Output directory for generated docs */
+  output: string;
+}
+
+/**
+ * Runner state during iteration
+ */
+export interface RunnerState {
+  iteration: number;
+  startTime: Date;
+  logFile: string;
+  todoFile: string;
+}
+
+/**
+ * Result of a single Claude invocation
+ */
+export interface IterationResult {
+  exitCode: number;
+  output: string;
+  isComplete: boolean;
+}