cralph 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -4,13 +4,13 @@
   <img src="assets/ralph.png" alt="Ralph cooking" width="500">
 </p>
 
-Claude in a loop. Point at refs, give it a rule, let it cook.
+Claude in a loop. Give it a rule, let it cook.
 
 ```
-refs/  ──loop──>  ./
-(source)   │      (output in cwd)
-           │
-        rule.md
+.ralph/
+├── rule.md ──loop──> ./
+├── refs/             (output)
+└── TODO.md
 ```
 
 ## What is Ralph?
@@ -21,7 +21,7 @@ refs/  ──loop──>  ./
 while :; do cat PROMPT.md | claude -p ; done
 ```
 
-cralph wraps this into a CLI with path selection and logging.
+cralph wraps this into a CLI with config, logging, and TODO tracking.
 
 ## Install
 
@@ -35,113 +35,108 @@ Or with npm:
 npm install -g cralph
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-# Run - auto-detects .ralph/paths.json in cwd
+# In an empty directory - creates starter structure
+cralph
+
+# Edit rule.md with your instructions, then run again
 cralph
+```
 
-# First run (no config) - interactive mode generates .ralph/paths.json
+## Usage
+
+```bash
+# Auto-detects .ralph/paths.json in cwd
 cralph
 
 # Override with flags
 cralph --refs ./source --rule ./rule.md --output .
-```
 
-## Path Selection
+# Auto-confirm prompts (CI/automation)
+cralph --yes
+```
 
-Simple multiselect for all paths:
+## How It Works
 
-- **Space** to toggle selection
-- **Enter** to confirm
-- **Ctrl+C** to exit
-- Shows all directories up to 3 levels deep
-- Pre-selects current values in edit mode
+1. Checks Claude CLI auth (cached for 6 hours)
+2. Loads config from `.ralph/paths.json`
+3. Runs `claude -p --dangerously-skip-permissions` in a loop
+4. Claude updates `.ralph/TODO.md` after each iteration
+5. Stops when Claude outputs `<promise>COMPLETE</promise>`
 
-## Config File
+## Config
 
 ```json
 {
-  "refs": ["./refs", "./more-refs"],
-  "rule": "./.cursor/rules/my-rules.mdc",
+  "refs": ["./.ralph/refs"],
+  "rule": "./.ralph/rule.md",
   "output": "."
 }
 ```
 
-Save as `.ralph/paths.json` and cralph auto-detects it. Output is typically `.` (current directory) since you'll run cralph in your repo.
+Save as `.ralph/paths.json`. Refs are optional reference material (read-only).
 
-## How It Works
+## Files
 
-1. Checks if Claude CLI is authenticated (exits with instructions if not)
-2. Reads your source material from `refs/`
-3. Injects your rule into the prompt
-4. Runs `claude -p --dangerously-skip-permissions` in a loop
-5. Stops when Claude outputs `<promise>COMPLETE</promise>`
+| File | Description |
+|------|-------------|
+| `.ralph/paths.json` | Configuration |
+| `.ralph/rule.md` | Your instructions for Claude |
+| `.ralph/refs/` | Optional reference material (read-only) |
+| `.ralph/TODO.md` | Task tracking (updated by Claude) |
+| `.ralph/ralph.log` | Session log |
+| `~/.cralph/auth-cache.json` | Auth cache (6h TTL) |
 
-## Expected Behavior
+### TODO Format
 
-**Auth check (runs first):**
-```
-◐ Checking Claude authentication...
-✔ Claude authenticated
-```
+Claude maintains this structure:
 
-If not authenticated:
-```
-◐ Checking Claude authentication...
-✖ Claude CLI is not authenticated
+```markdown
+# Tasks
 
-╭─────────────────────╮
-│ claude              │
-│                     │
-│ Then type: /login   │
-╰─────────────────────╯
+- [ ] Pending task
+- [x] Completed task
 
-ℹ After logging in, run cralph again.
-```
+# Notes
 
-**Auto-detect existing config:**
-```
-❯ Found .ralph/paths.json. What would you like to do?
-● 🚀 Run with this config
-○ ✏️  Edit configuration
+Any relevant context
 ```
 
-**Interactive Mode (no config file):**
+## First Run (Empty Directory)
+
 ```
-ℹ Interactive configuration mode
+ℹ Created .ralph/refs/ directory
+ℹ Created .ralph/rule.md with starter template
+ℹ Created .ralph/paths.json
 
-↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
-❯ Select refs directories:
-◻ 📁 src
-◻ 📁 src/components
-◼ 📁 docs
+╭──────────────────────────────────────────────╮
+│ 1. Add source files to .ralph/refs/          │
+│ 2. Edit .ralph/rule.md with your instructions│
+│ 3. Run cralph again                          │
+╰──────────────────────────────────────────────╯
+```
 
-↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
-❯ Select rule file:
-● 📄 .cursor/rules/my-rules.mdc (cursor rule)
-○ 📄 README.md
+## Prompts
 
-↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
-❯ Select output directory:
-● 📍 Current directory (.)
-○ 📁 docs
+**Config detected:**
+```
+❯ Found .ralph/paths.json. What would you like to do?
+● 🚀 Run with this config
+○ ✏️  Edit configuration
 ```
 
-**Save config after selection:**
+**TODO has progress:**
 ```
-? Save configuration to .ralph/paths.json? (Y/n)
-✔ Saved .ralph/paths.json
+? Found existing TODO with progress. Reset to start fresh? (Y/n)
 ```
 
-**Cancellation:**
-- Press `Ctrl+C` at any time to exit
-- Running Claude processes are terminated cleanly
+## Path Selection
 
-**Output Files:**
-- `.ralph/paths.json` - Configuration file
-- `.ralph/ralph.log` - Session log with timestamps
-- `.ralph/TODO.md` - Agent status tracker
+- **Space** - Toggle selection
+- **Enter** - Confirm
+- **Ctrl+C** - Exit
 
 ## Testing
 
@@ -149,7 +144,8 @@ If not authenticated:
 bun test
 ```
 
-Tests validate config loading, prompt building, and CLI behavior without calling Claude.
+- **Unit tests** - Config, prompt building, CLI
+- **E2E tests** - Full loop with Claude (requires auth)
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cralph",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Claude in a loop. Point at refs, give it a rule, let it cook.",
   "author": "mguleryuz",
   "license": "MIT",

package/src/paths.ts

@@ -1,6 +1,6 @@
 import { consola } from "consola";
 import { resolve, join } from "path";
-import { readdir, stat } from "fs/promises";
+import { readdir, stat, mkdir } from "fs/promises";
 import type { PathsFileConfig, RalphConfig } from "./types";
 
 // Dim text helper
@@ -105,16 +105,47 @@ export async function loadPathsFile(filePath: string): Promise<PathsFileConfig>
   return content as PathsFileConfig;
 }
 
+/**
+ * Create starter structure for empty directories
+ */
+export async function createStarterStructure(cwd: string): Promise<void> {
+  // Create .ralph/
+  const ralphDir = join(cwd, ".ralph");
+  await mkdir(ralphDir, { recursive: true });
+  
+  // Create .ralph/refs/
+  const refsDir = join(ralphDir, "refs");
+  await mkdir(refsDir, { recursive: true });
+  consola.info("Created .ralph/refs/ directory");
+  
+  // Create .ralph/rule.md
+  const rulePath = join(ralphDir, "rule.md");
+  await Bun.write(rulePath, STARTER_RULE);
+  consola.info("Created .ralph/rule.md with starter template");
+  
+  // Create .ralph/paths.json with default config
+  const pathsConfig = {
+    refs: ["./.ralph/refs"],
+    rule: "./.ralph/rule.md",
+    output: ".",
+  };
+  await Bun.write(join(ralphDir, "paths.json"), JSON.stringify(pathsConfig, null, 2));
+  consola.info("Created .ralph/paths.json");
+  
+  consola.box("1. Add source files to .ralph/refs/\n2. Edit .ralph/rule.md with your instructions\n3. Run cralph again");
+}
+
 /**
  * Prompt user to select refs directories (simple multiselect)
  */
 export async function selectRefs(cwd: string, defaults?: string[]): Promise<string[]> {
   // Get all directories up to 3 levels deep
-  const allDirs = await listDirectoriesRecursive(cwd, 3);
+  let allDirs = await listDirectoriesRecursive(cwd, 3);
   
   if (allDirs.length === 0) {
-    consola.warn("No directories found");
-    throw new Error("No directories available to select");
+    // Create starter structure and exit gracefully
+    await createStarterStructure(cwd);
+    process.exit(0);
   }
 
   // Convert to relative paths for display
@@ -146,14 +177,21 @@ export async function selectRefs(cwd: string, defaults?: string[]): Promise<stri
   return selected as string[];
 }
 
+const STARTER_RULE = `I want a file named hello.txt
+`;
+
 /**
  * Prompt user to select a rule file
  */
 export async function selectRule(cwd: string, defaultRule?: string): Promise<string> {
-  const files = await listFilesRecursive(cwd, [".mdc", ".md"]);
+  let files = await listFilesRecursive(cwd, [".mdc", ".md"]);
   if (files.length === 0) {
-    consola.warn("No .mdc or .md files found");
-    throw new Error("No rule files available to select");
+    // This shouldn't happen if selectRefs ran first, but handle it just in case
+    const rulePath = join(cwd, "rule.md");
+    await Bun.write(rulePath, STARTER_RULE);
+    consola.info("Created rule.md with starter template");
+    consola.box("Edit rule.md with your instructions then run cralph again");
+    process.exit(0);
   }
 
   // Show relative paths for readability

package/src/prompt.ts

@@ -8,13 +8,16 @@ 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.
+Your job is to follow the rules and complete the task. Write output to the output directory.
 
-**CRITICAL: refs paths are READ-ONLY.** Never delete, move, or modify files in refs. Only create files in the output directory.
+If refs paths are provided, they are READ-ONLY reference material. Never delete, move, or modify files in refs.
 
-Follow the rules to determine how to process each file. Track what you've done to avoid duplicate work.
+**IMPORTANT: At the end of EVERY iteration, update the TODO file with your progress.**
+Keep the TODO structure with these sections:
+- **# Tasks** - Checklist with [ ] for pending and [x] for done
+- **# Notes** - Any relevant notes or context
 
-STOPPING CONDITION: When all source files have been processed according to the rules, output exactly:
+STOPPING CONDITION: When done, update the TODO file, then output exactly:
 
 <promise>COMPLETE</promise>
 
@@ -23,8 +26,10 @@ 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");
+export function buildPrompt(config: RalphConfig, rulesContent: string, todoFile: string): string {
+  const refsList = config.refs.length > 0 
+    ? config.refs.map((r) => `- ${r}`).join("\n")
+    : "_None_";
 
   return `${BASE_PROMPT}
 
@@ -32,7 +37,10 @@ export function buildPrompt(config: RalphConfig, rulesContent: string): string {
 
 ## Configuration
 
-**Refs paths (read-only source material):**
+**TODO file (update after each iteration):**
+${todoFile}
+
+**Refs paths (optional, read-only reference material):**
 ${refsList}
 
 **Output directory:**
@@ -42,8 +50,6 @@ ${config.output}
 
 ## Rules
 
-The following rules define how to classify, refine, and write documentation:
-
 ${rulesContent}
 `;
 }
@@ -51,9 +57,9 @@ ${rulesContent}
 /**
  * Read rule file and build complete prompt
  */
-export async function createPrompt(config: RalphConfig): Promise<string> {
+export async function createPrompt(config: RalphConfig, todoFile: string): Promise<string> {
   const ruleFile = Bun.file(config.rule);
   const ruleContent = await ruleFile.text();
 
-  return buildPrompt(config, ruleContent);
+  return buildPrompt(config, ruleContent, todoFile);
 }

package/src/runner.ts

@@ -1,15 +1,73 @@
 import { consola } from "consola";
 import { join } from "path";
 import { mkdir } from "fs/promises";
+import { homedir } from "os";
 import type { RalphConfig, RunnerState, IterationResult } from "./types";
 import { createPrompt } from "./prompt";
 
 const COMPLETION_SIGNAL = "<promise>COMPLETE</promise>";
+const AUTH_CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
+
+const INITIAL_TODO_CONTENT = `# Tasks
+
+- [ ] Task 1
+- [ ] Task 2
+
+# Notes
+
+_None yet_
+`;
+
+/**
+ * Get the auth cache file path
+ */
+function getAuthCachePath(): string {
+  return join(homedir(), ".cralph", "auth-cache.json");
+}
+
+/**
+ * Check if cached auth is still valid
+ */
+async function isAuthCacheValid(): Promise<boolean> {
+  try {
+    const cachePath = getAuthCachePath();
+    const file = Bun.file(cachePath);
+    if (!(await file.exists())) {
+      return false;
+    }
+    const cache = await file.json();
+    const cachedAt = cache.timestamp;
+    const now = Date.now();
+    return now - cachedAt < AUTH_CACHE_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Save successful auth to cache
+ */
+async function saveAuthCache(): Promise<void> {
+  try {
+    const cachePath = getAuthCachePath();
+    const cacheDir = join(homedir(), ".cralph");
+    await mkdir(cacheDir, { recursive: true });
+    await Bun.write(cachePath, JSON.stringify({ timestamp: Date.now() }));
+  } catch {
+    // Ignore cache write errors
+  }
+}
 
 /**
  * Check if Claude CLI is authenticated by sending a minimal test prompt
+ * Uses cache to avoid checking too frequently (6 hour TTL)
  */
 export async function checkClaudeAuth(): Promise<boolean> {
+  // Check cache first
+  if (await isAuthCacheValid()) {
+    return true;
+  }
+
   try {
     // Send a minimal prompt to test auth
     const proc = Bun.spawn(["claude", "-p"], {
@@ -32,14 +90,31 @@ export async function checkClaudeAuth(): Promise<boolean> {
       return false;
     }
     
-    // If exit code is 0, auth is working
-    return exitCode === 0;
+    // If exit code is 0, auth is working - save to cache
+    if (exitCode === 0) {
+      await saveAuthCache();
+      return true;
+    }
+    
+    return false;
   } catch {
     return false;
   }
 }
 
 
+/**
+ * Check if the TODO file is in a clean/initial state
+ */
+async function isTodoClean(todoPath: string): Promise<boolean> {
+  const file = Bun.file(todoPath);
+  if (!(await file.exists())) {
+    return true; // Non-existent is considered clean
+  }
+  const content = await file.text();
+  return content.trim() === INITIAL_TODO_CONTENT.trim();
+}
+
 /**
  * Initialize the runner state and log file
  */
@@ -61,26 +136,29 @@ Ralph Session: ${state.startTime.toISOString()}
 
   await Bun.write(state.logFile, logHeader);
 
-  // Initialize TODO file if not exists
+  // Check TODO file state
   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_
-`
+  const todoExists = await todoFile.exists();
+  
+  if (!todoExists) {
+    // Create fresh TODO file
+    await Bun.write(state.todoFile, INITIAL_TODO_CONTENT);
+  } else if (!(await isTodoClean(state.todoFile))) {
+    // TODO exists and has been modified - ask about reset
+    const response = await consola.prompt(
+      "Found existing TODO with progress. Reset to start fresh?",
+      {
+        type: "confirm",
+        initial: true,
+      }
     );
+    
+    if (response === true) {
+      await Bun.write(state.todoFile, INITIAL_TODO_CONTENT);
+      consola.info("TODO reset to clean state");
+    } else {
+      consola.info("Continuing with existing TODO state");
+    }
   }
 
   return state;
@@ -97,28 +175,6 @@ async function log(state: RunnerState, message: string): Promise<void> {
   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;
-}
-
 // Track current subprocess for cleanup
 let currentProc: ReturnType<typeof Bun.spawn> | null = null;
 
@@ -204,17 +260,8 @@ export async function run(config: RalphConfig): Promise<void> {
   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);
+  const prompt = await createPrompt(config, state.todoFile);
 
   // Ensure output directory exists
   await mkdir(config.output, { recursive: true });
@@ -225,9 +272,6 @@ export async function run(config: RalphConfig): Promise<void> {
   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) {