cralph 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -36,7 +36,7 @@ bun add -g cralph
 ## Quick Start
 
 ```bash
-# In an empty directory - creates starter structure
+# In any directory without .ralph/ - creates starter structure
 cralph
 
 # Edit rule.md with your instructions, then run again
@@ -59,10 +59,11 @@ cralph --yes
 ## How It Works
 
 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>`
+2. Looks for `.ralph/` in current directory only (not subdirectories)
+3. Loads config from `.ralph/paths.json` or creates starter structure
+4. Runs `claude -p --dangerously-skip-permissions` in a loop
+5. Claude updates `.ralph/TODO.md` after each iteration
+6. Stops when Claude outputs `<promise>COMPLETE</promise>`
 
 ## Config
 
@@ -102,23 +103,31 @@ Claude maintains this structure:
 Any relevant context
 ```
 
-## First Run (Empty Directory)
+## First Run (No .ralph/ in cwd)
 
 ```
-? No directories found. Create starter structure in /path/to/dir? (Y/n)
+❯ No .ralph/ found in /path/to/dir
+● 📦 Create starter structure
+○ ⚙️  Configure manually
+```
+
+Select **Create starter structure** to generate the default config:
 
+```
 ℹ Created .ralph/refs/ directory
 ℹ Created .ralph/rule.md with starter template
 ℹ Created .ralph/paths.json
 
-╭──────────────────────────────────────────────╮
-│ 1. Add source files to .ralph/refs/          │
-│ 2. Edit .ralph/rule.md with your instructions│
-│ 3. Run cralph again                          │
-╰──────────────────────────────────────────────╯
+╭─────────────────────────────────────────────────╮
+│  1. Add source files to .ralph/refs/            │
+│  2. Edit .ralph/rule.md with your instructions  │
+│  3. Run cralph again                            │
+╰─────────────────────────────────────────────────╯
 ```
 
-Use `--yes` to skip confirmation (for CI/automation).
+Select **Configure manually** to skip starter creation and pick your own refs/rule/output.
+
+Use `--yes` to auto-create starter structure (for CI/automation).
 
 ## Prompts
 
@@ -140,11 +149,17 @@ Use `--yes` to skip confirmation (for CI/automation).
 - **Enter** - Confirm
 - **Ctrl+C** - Exit
 
-## Platform Notes
+## Platform Support
+
+cralph works on **macOS**, **Linux**, and **Windows** with platform-specific handling:
 
-### macOS Protected Directories
+| Platform | Protected Directories Skipped |
+|----------|------------------------------|
+| macOS    | Library, Photos Library, Photo Booth Library |
+| Linux    | lost+found, proc, sys |
+| Windows  | System Volume Information, $Recycle.Bin, Windows |
 
-cralph gracefully handles macOS permission errors (`EPERM`, `EACCES`) when scanning directories. Protected locations like `~/Pictures/Photo Booth Library` or iCloud folders are silently skipped, allowing the CLI to run from any directory including root (`/`).
+Permission errors (`EPERM`, `EACCES`) are handled gracefully on all platforms, allowing the CLI to run from any directory.
 
 ## Testing
 
@@ -152,7 +167,7 @@ cralph gracefully handles macOS permission errors (`EPERM`, `EACCES`) when scann
 bun test
 ```
 
-- **Unit tests** - Config, prompt building, CLI, access error handling
+- **Unit tests** - Config, prompt building, CLI, access error handling, platform detection, shutdown state
 - **E2E tests** - Full loop with Claude (requires auth)
 
 ## Requirements

package/index.ts

@@ -1,5 +1,7 @@
 // Re-export for programmatic usage
 export * from "./src/types";
-export { buildConfig, loadPathsFile, validateConfig } from "./src/paths";
+export { loadPathsFile, validateConfig, resolvePathsConfig, toRelativePath } from "./src/paths";
 export { createPrompt, buildPrompt } from "./src/prompt";
-export { run, cleanupSubprocess } from "./src/runner";
+export { run, checkClaudeAuth } from "./src/runner";
+export { cleanupSubprocess, setShuttingDown, isShuttingDown } from "./src/state";
+export { getPlatform, isClaudeInstalled, checkClaudeInstallation } from "./src/platform";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cralph",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "Claude in a loop. Point at refs, give it a rule, let it cook.",
   "author": "mguleryuz",
   "license": "MIT",
@@ -30,7 +30,8 @@
     "assets"
   ],
   "scripts": {
-    "start": "bun run src/cli.ts"
+    "start": "bun run src/cli.ts",
+    "type-check": "tsgo --noEmit --pretty"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/src/cli.ts

@@ -5,38 +5,41 @@ import { consola } from "consola";
 import { resolve, join } from "path";
 import { mkdir } from "fs/promises";
 import {
-  buildConfig,
   loadPathsFile,
   validateConfig,
   selectRefs,
   selectRule,
   selectOutput,
   checkForPathsFile,
+  resolvePathsConfig,
+  toRelativePath,
 } from "./paths";
-import { run, cleanupSubprocess, checkClaudeAuth } from "./runner";
+import { run, checkClaudeAuth } from "./runner";
 import type { RalphConfig } from "./types";
+import { setShuttingDown, isShuttingDown, cleanupSubprocess, throwIfCancelled } from "./state";
+import { checkClaudeInstallation } from "./platform";
 
 // Graceful shutdown on Ctrl+C
 function setupGracefulExit() {
-  let shuttingDown = false;
+  const exit = (code: number) => process.exit(code);
   
   process.on("SIGINT", () => {
-    if (shuttingDown) {
+    if (isShuttingDown()) {
       // Force exit on second Ctrl+C
-      process.exit(1);
+      exit(1);
     }
-    shuttingDown = true;
+    setShuttingDown();
     cleanupSubprocess();
     console.log("\n");
     consola.info("Cancelled.");
-    // Use setImmediate to ensure output is flushed
-    setImmediate(() => process.exit(0));
+    exit(0);
   });
   
   // Also handle SIGTERM
   process.on("SIGTERM", () => {
+    setShuttingDown();
     cleanupSubprocess();
-    process.exit(0);
+    exit(0);
   });
 }
 
@@ -87,7 +90,17 @@ const main = defineCommand({
     let config: RalphConfig;
 
     try {
-      // Check Claude authentication first - before any prompts
+      // Check Claude CLI is installed first
+      const claudeCheck = await checkClaudeInstallation();
+      
+      if (!claudeCheck.installed) {
+        consola.error("Claude CLI is not installed\n");
+        consola.box(claudeCheck.installInstructions);
+        consola.info("After installing, run cralph again.");
+        process.exit(1);
+      }
+      
+      // Check Claude authentication
       consola.start("Checking Claude authentication...");
       const isAuthed = await checkClaudeAuth();
       
@@ -109,11 +122,7 @@ const main = defineCommand({
         // Use existing config file
         consola.info(`Loading config from ${pathsFileResult.path}`);
         const loaded = await loadPathsFile(pathsFileResult.path);
-        config = {
-          refs: loaded.refs.map((r) => resolve(cwd, r)),
-          rule: resolve(cwd, loaded.rule),
-          output: resolve(cwd, loaded.output),
-        };
+        config = resolvePathsConfig(loaded, cwd);
       } else {
         // Load existing config for edit mode defaults
         let existingConfig: RalphConfig | null = null;
@@ -123,11 +132,7 @@ const main = defineCommand({
           const file = Bun.file(filePath);
           if (await file.exists()) {
             const loaded = await loadPathsFile(filePath);
-            existingConfig = {
-              refs: loaded.refs.map((r) => resolve(cwd, r)),
-              rule: resolve(cwd, loaded.rule),
-              output: resolve(cwd, loaded.output),
-            };
+            existingConfig = resolvePathsConfig(loaded, cwd);
           }
         } else {
           consola.info("Interactive configuration mode");
@@ -151,17 +156,20 @@ const main = defineCommand({
         // Offer to save config
         const saveConfig = await consola.prompt("Save configuration to .ralph/paths.json?", {
           type: "confirm",
+          cancel: "symbol",
           initial: true,
         });
+        
+        throwIfCancelled(saveConfig);
 
         if (saveConfig === true) {
           const ralphDir = join(cwd, ".ralph");
           await mkdir(ralphDir, { recursive: true });
           
           const pathsConfig = {
-            refs: config.refs.map((r) => "./" + r.replace(cwd + "/", "")),
-            rule: "./" + config.rule.replace(cwd + "/", ""),
-            output: config.output === cwd ? "." : "./" + config.output.replace(cwd + "/", ""),
+            refs: config.refs.map((r) => toRelativePath(r, cwd)),
+            rule: toRelativePath(config.rule, cwd),
+            output: toRelativePath(config.output, cwd),
           };
           await Bun.write(
             join(ralphDir, "paths.json"),
@@ -186,8 +194,11 @@ const main = defineCommand({
       if (!args.yes) {
         const proceed = await consola.prompt("Start processing?", {
           type: "confirm",
+          cancel: "symbol",
           initial: true,
         });
+        
+        throwIfCancelled(proceed);
 
         if (proceed !== true) {
           consola.info("Cancelled.");

package/src/paths.ts

@@ -1,12 +1,48 @@
 import { consola } from "consola";
 import { resolve, join } from "path";
 import { readdir, stat, mkdir } from "fs/promises";
+import type { Dirent } from "fs";
 import type { PathsFileConfig, RalphConfig } from "./types";
+import { isAccessError, shouldExcludeDir } from "./platform";
+import { throwIfCancelled } from "./state";
+
+// Starter rule template for new projects
+const STARTER_RULE = `I want a file named hello.txt
+`;
 
 // Dim text helper
 const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
 const CONTROLS = dim("↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit");
 
+/**
+ * Convert a PathsFileConfig to a resolved RalphConfig
+ */
+export function resolvePathsConfig(loaded: PathsFileConfig, cwd: string): RalphConfig {
+  return {
+    refs: loaded.refs.map((r) => resolve(cwd, r)),
+    rule: resolve(cwd, loaded.rule),
+    output: resolve(cwd, loaded.output),
+  };
+}
+
+/**
+ * Convert an absolute path to a relative path for config storage
+ */
+export function toRelativePath(absolutePath: string, cwd: string): string {
+  if (absolutePath === cwd) return ".";
+  return "./" + absolutePath.replace(cwd + "/", "");
+}
+
+/**
+ * Check if a directory entry should be skipped during traversal
+ */
+function shouldSkipDirectory(entry: Dirent): boolean {
+  if (!entry.isDirectory()) return true;
+  if (entry.name.startsWith(".")) return true;
+  if (shouldExcludeDir(entry.name)) return true;
+  return false;
+}
+
 /**
  * List directories in a given path
  */
@@ -17,7 +53,7 @@ async function listDirectories(basePath: string): Promise<string[]> {
       .filter((e) => e.isDirectory() && !e.name.startsWith("."))
       .map((e) => e.name);
   } catch (error) {
-    // Silently skip directories we can't access (EPERM, EACCES)
+    // Silently skip directories we can't access
     if (isAccessError(error)) {
       return [];
     }
@@ -25,34 +61,6 @@ async function listDirectories(basePath: string): Promise<string[]> {
   }
 }
 
-/**
- * Check if an error is a permission/access error
- */
-export function isAccessError(error: unknown): boolean {
-  if (error && typeof error === "object" && "code" in error) {
-    const code = (error as { code: string }).code;
-    return code === "EPERM" || code === "EACCES";
-  }
-  return false;
-}
-
-/**
- * Directories to exclude from listing
- */
-const EXCLUDED_DIRS = [
-  "node_modules",
-  "dist",
-  "build",
-  ".git",
-  ".next",
-  ".nuxt",
-  ".output",
-  "coverage",
-  "__pycache__",
-  "vendor",
-  ".cache",
-];
-
 /**
  * List directories recursively up to a certain depth
  */
@@ -69,7 +77,7 @@ export async function listDirectoriesRecursive(
     try {
       entries = await readdir(dir, { withFileTypes: true });
     } catch (error) {
-      // Silently skip directories we can't access (EPERM, EACCES)
+      // Silently skip directories we can't access
       if (isAccessError(error)) {
         return;
       }
@@ -77,10 +85,7 @@ export async function listDirectoriesRecursive(
     }
     
     for (const entry of entries) {
-      // Skip hidden and excluded directories
-      if (!entry.isDirectory()) continue;
-      if (entry.name.startsWith(".")) continue;
-      if (EXCLUDED_DIRS.includes(entry.name)) continue;
+      if (shouldSkipDirectory(entry)) continue;
       
       const fullPath = join(dir, entry.name);
       results.push(fullPath);
@@ -106,7 +111,7 @@ export async function listFilesRecursive(
     try {
       entries = await readdir(dir, { withFileTypes: true });
     } catch (error) {
-      // Silently skip directories we can't access (EPERM, EACCES)
+      // Silently skip directories we can't access
       if (isAccessError(error)) {
         return;
       }
@@ -116,9 +121,7 @@ export async function listFilesRecursive(
     for (const entry of entries) {
       const fullPath = join(dir, entry.name);
       if (entry.isDirectory()) {
-        // Skip hidden and excluded directories
-        if (entry.name.startsWith(".")) continue;
-        if (EXCLUDED_DIRS.includes(entry.name)) continue;
+        if (shouldSkipDirectory(entry)) continue;
         await walk(fullPath);
       } else if (entry.isFile()) {
         if (extensions.some((ext) => entry.name.endsWith(ext))) {
@@ -179,27 +182,52 @@ export async function createStarterStructure(cwd: string): Promise<void> {
  * @param autoConfirm - If true, skip confirmation prompts
  */
 export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?: boolean): Promise<string[]> {
-  // Get all directories up to 3 levels deep
-  let allDirs = await listDirectoriesRecursive(cwd, 3);
-  
-  if (allDirs.length === 0) {
+  // Check if .ralph/ exists in cwd - if not, offer to create starter structure
+  const ralphDir = join(cwd, ".ralph");
+  let ralphExists = false;
+  try {
+    await stat(ralphDir);
+    ralphExists = true;
+  } catch {
+    ralphExists = false;
+  }
+
+  if (!ralphExists) {
     // Ask before creating starter structure (skip if autoConfirm)
     if (!autoConfirm) {
-      const confirm = await consola.prompt(
-        `No directories found. Create starter structure in ${cwd}?`,
+      console.log(CONTROLS);
+      const action = await consola.prompt(
+        `No .ralph/ found in ${cwd}`,
         {
-          type: "confirm",
-          initial: true,
+          type: "select",
+          cancel: "symbol",
+          options: [
+            { label: "📦 Create starter structure", value: "create" },
+            { label: "⚙️  Configure manually", value: "manual" },
+          ],
         }
       );
       
-      if (confirm !== true) {
-        throw new Error("Setup cancelled");
+      throwIfCancelled(action);
+      
+      if (action === "create") {
+        await createStarterStructure(cwd);
+        process.exit(0);
       }
+      
+      // action === "manual" - continue to directory selection
+    } else {
+      // Auto-confirm mode: create starter structure
+      await createStarterStructure(cwd);
+      process.exit(0);
     }
-    
-    await createStarterStructure(cwd);
-    process.exit(0);
+  }
+
+  // Get all directories up to 3 levels deep
+  let allDirs = await listDirectoriesRecursive(cwd, 3);
+  
+  if (allDirs.length === 0) {
+    throw new Error("No directories found to select from");
   }
 
   // Convert to relative paths for display
@@ -219,21 +247,21 @@ export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?:
   console.log(CONTROLS);
   const selected = await consola.prompt("Select refs directories:", {
     type: "multiselect",
+    cancel: "symbol",
     options,
     initial: initialValues,
   });
 
-  // Handle cancel (symbol) or empty result
-  if (typeof selected === "symbol" || !selected || (Array.isArray(selected) && selected.length === 0)) {
+  // Handle cancel (symbol), shutdown, or empty result
+  throwIfCancelled(selected);
+  if (!selected || (Array.isArray(selected) && selected.length === 0)) {
     throw new Error("Selection cancelled");
   }
   
-  return selected as string[];
+  // Cast is safe: multiselect with string values returns string[]
+  return selected as unknown as string[];
 }
 
-const STARTER_RULE = `I want a file named hello.txt
-`;
-
 /**
  * Prompt user to select a rule file
  */
@@ -255,17 +283,18 @@ export async function selectRule(cwd: string, defaultRule?: string): Promise<str
     hint: f === defaultRule ? "current" : (f.endsWith(".mdc") ? "cursor rule" : "markdown"),
   }));
 
-  // Find index of default for initial selection
-  const initialIndex = defaultRule ? files.findIndex((f) => f === defaultRule) : 0;
+  // Find initial value for default selection
+  const initialValue = defaultRule && files.includes(defaultRule) ? defaultRule : files[0];
 
   console.log(CONTROLS);
   const selected = await consola.prompt("Select rule file:", {
     type: "select",
+    cancel: "symbol",
     options,
-    initial: initialIndex >= 0 ? initialIndex : 0,
+    initial: initialValue,
   });
 
-  if (typeof selected === "symbol") throw new Error("Selection cancelled");
+  throwIfCancelled(selected);
   return selected as string;
 }
 
@@ -287,21 +316,20 @@ export async function selectOutput(cwd: string, defaultOutput?: string): Promise
     })),
   ];
 
-  // Find initial index
-  let initialIndex = 0;
-  if (defaultDir) {
-    const idx = defaultDir === "." ? 0 : dirs.findIndex((d) => d === defaultDir) + 1;
-    if (idx >= 0) initialIndex = idx;
-  }
+  // Determine initial value for default selection
+  const initialValue = defaultDir && (defaultDir === "." || dirs.includes(defaultDir)) 
+    ? defaultDir 
+    : ".";
 
   console.log(CONTROLS);
   const selected = await consola.prompt("Select output directory:", {
     type: "select",
+    cancel: "symbol",
     options,
-    initial: initialIndex,
+    initial: initialValue,
   });
 
-  if (typeof selected === "symbol") throw new Error("Selection cancelled");
+  throwIfCancelled(selected);
 
   if (selected === ".") {
     return cwd;
@@ -330,6 +358,7 @@ export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise
       `Found .ralph/paths.json. What would you like to do?`,
       {
         type: "select",
+        cancel: "symbol",
         options: [
           { label: "🚀 Run with this config", value: "run" },
           { label: "✏️  Edit configuration", value: "edit" },
@@ -337,9 +366,7 @@ export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise
       }
     );
     
-    if (typeof action === "symbol") {
-      throw new Error("Selection cancelled");
-    }
+    throwIfCancelled(action);
     
     if (action === "run") {
       return { action: "run", path: filePath };
@@ -371,27 +398,3 @@ export async function validateConfig(config: RalphConfig): Promise<void> {
 
   // 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)),
-      rule: resolve(cwd, loaded.rule),
-      output: resolve(cwd, loaded.output),
-    };
-  }
-
-  // Interactive selection
-  const refs = await selectRefs(cwd);
-  const rule = await selectRule(cwd);
-  const output = await selectOutput(cwd);
-
-  return { refs, rule, output };
-}

package/src/platform.ts

@@ -0,0 +1,190 @@
+import { platform } from "os";
+import { which } from "bun";
+
+/**
+ * Supported platforms
+ */
+export type Platform = "darwin" | "linux" | "win32" | "unknown";
+
+/**
+ * Get the current platform
+ */
+export function getPlatform(): Platform {
+  const p = platform();
+  if (p === "darwin" || p === "linux" || p === "win32") {
+    return p;
+  }
+  return "unknown";
+}
+
+/**
+ * Platform-specific configuration
+ */
+interface PlatformConfig {
+  /** Error codes that indicate permission/access denied */
+  accessErrorCodes: string[];
+  /** Directories to always exclude from scanning */
+  systemExcludedDirs: string[];
+}
+
+/**
+ * Platform configurations
+ */
+const PLATFORM_CONFIGS: Record<Platform, PlatformConfig> = {
+  darwin: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [
+      // macOS protected directories
+      "Library",
+      "Photos Library.photoslibrary",
+      "Photo Booth Library",
+    ],
+  },
+  linux: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [
+      // Linux protected directories
+      "lost+found",
+      "proc",
+      "sys",
+    ],
+  },
+  win32: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [
+      // Windows protected directories
+      "System Volume Information",
+      "$Recycle.Bin",
+      "Windows",
+    ],
+  },
+  unknown: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [],
+  },
+};
+
+/**
+ * Get platform-specific configuration
+ */
+export function getPlatformConfig(): PlatformConfig {
+  return PLATFORM_CONFIGS[getPlatform()];
+}
+
+/**
+ * Check if an error is a permission/access error for the current platform
+ */
+export function isAccessError(error: unknown): boolean {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = (error as { code: string }).code;
+    return getPlatformConfig().accessErrorCodes.includes(code);
+  }
+  return false;
+}
+
+/**
+ * Check if a directory should be excluded on the current platform
+ */
+export function isSystemExcludedDir(dirName: string): boolean {
+  return getPlatformConfig().systemExcludedDirs.includes(dirName);
+}
+
+/**
+ * Common directories to exclude across all platforms (project-related)
+ */
+export const EXCLUDED_DIRS = [
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".output",
+  "coverage",
+  "__pycache__",
+  "vendor",
+  ".cache",
+];
+
+/**
+ * Check if a directory should be excluded (combines common + platform-specific)
+ */
+export function shouldExcludeDir(dirName: string): boolean {
+  return EXCLUDED_DIRS.includes(dirName) || isSystemExcludedDir(dirName);
+}
+
+// ============================================================================
+// Claude CLI Detection
+// ============================================================================
+
+/**
+ * Platform-specific install instructions for Claude CLI
+ */
+const CLAUDE_INSTALL_INSTRUCTIONS: Record<Platform, string> = {
+  darwin: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code
+
+Or via Homebrew:
+  brew install claude`,
+  linux: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code`,
+  win32: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code`,
+  unknown: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code`,
+};
+
+/**
+ * Get platform-specific Claude CLI install instructions
+ */
+export function getClaudeInstallInstructions(): string {
+  return CLAUDE_INSTALL_INSTRUCTIONS[getPlatform()];
+}
+
+/**
+ * Check if Claude CLI is installed and available in PATH
+ */
+export async function isClaudeInstalled(): Promise<boolean> {
+  try {
+    const claudePath = which("claude");
+    return claudePath !== null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Result of Claude CLI check
+ */
+export interface ClaudeCheckResult {
+  installed: boolean;
+  path?: string;
+  installInstructions: string;
+}
+
+/**
+ * Check Claude CLI installation and return detailed result
+ */
+export async function checkClaudeInstallation(): Promise<ClaudeCheckResult> {
+  const installInstructions = getClaudeInstallInstructions();
+  
+  try {
+    const claudePath = which("claude");
+    if (claudePath) {
+      return {
+        installed: true,
+        path: claudePath,
+        installInstructions,
+      };
+    }
+    return {
+      installed: false,
+      installInstructions,
+    };
+  } catch {
+    return {
+      installed: false,
+      installInstructions,
+    };
+  }
+}

package/src/runner.ts

@@ -4,6 +4,7 @@ import { mkdir } from "fs/promises";
 import { homedir } from "os";
 import type { RalphConfig, RunnerState, IterationResult } from "./types";
 import { createPrompt } from "./prompt";
+import { setCurrentProcess, throwIfCancelled } from "./state";
 
 const COMPLETION_SIGNAL = "<promise>COMPLETE</promise>";
 const AUTH_CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
@@ -102,7 +103,6 @@ export async function checkClaudeAuth(): Promise<boolean> {
   }
 }
 
-
 /**
  * Check if the TODO file is in a clean/initial state
  */
@@ -149,10 +149,13 @@ Ralph Session: ${state.startTime.toISOString()}
       "Found existing TODO with progress. Reset to start fresh?",
       {
         type: "confirm",
+        cancel: "symbol",
         initial: true,
       }
     );
     
+    throwIfCancelled(response);
+    
     if (response === true) {
       await Bun.write(state.todoFile, INITIAL_TODO_CONTENT);
       consola.info("TODO reset to clean state");
@@ -175,23 +178,6 @@ async function log(state: RunnerState, message: string): Promise<void> {
   await Bun.write(state.logFile, existing + logLine);
 }
 
-// Track current subprocess for cleanup
-let currentProc: ReturnType<typeof Bun.spawn> | null = null;
-
-/**
- * Kill any running subprocess on exit
- */
-export function cleanupSubprocess() {
-  if (currentProc) {
-    try {
-      currentProc.kill();
-    } catch {
-      // Process may have already exited
-    }
-    currentProc = null;
-  }
-}
-
 /**
  * Run a single Claude iteration
  */
@@ -213,14 +199,14 @@ async function runIteration(
     cwd,
   });
   
-  currentProc = proc;
+  setCurrentProcess(proc);
 
   // Collect output
   const stdout = await new Response(proc.stdout).text();
   const stderr = await new Response(proc.stderr).text();
   const exitCode = await proc.exited;
   
-  currentProc = null;
+  setCurrentProcess(null);
 
   const output = stdout + stderr;
 

package/src/state.ts

@@ -0,0 +1,80 @@
+/**
+ * Global state shared across modules
+ *
+ * This module provides centralized state management for:
+ * - Graceful shutdown handling (Ctrl+C / SIGINT / SIGTERM)
+ * - Prompt cancellation detection
+ * - Subprocess tracking for cleanup
+ */
+
+// ============================================================================
+// Shutdown State
+// ============================================================================
+
+let shuttingDown = false;
+
+/**
+ * Mark the process as shutting down
+ */
+export function setShuttingDown(): void {
+  shuttingDown = true;
+}
+
+/**
+ * Check if the process is shutting down (Ctrl+C was pressed)
+ */
+export function isShuttingDown(): boolean {
+  return shuttingDown;
+}
+
+/**
+ * Reset shutdown state (for testing purposes only)
+ */
+export function resetShutdownState(): void {
+  shuttingDown = false;
+}
+
+// ============================================================================
+// Prompt Cancellation
+// ============================================================================
+
+/**
+ * Check if a prompt result indicates cancellation and throw if so.
+ * Handles Symbol returns from consola prompts (when cancel: "symbol")
+ * and shutdown state.
+ *
+ * @param result - The result from a consola.prompt() call
+ * @throws Error with message "Selection cancelled" if cancelled
+ */
+export function throwIfCancelled(result: unknown): void {
+  if (typeof result === "symbol" || isShuttingDown()) {
+    throw new Error("Selection cancelled");
+  }
+}
+
+// ============================================================================
+// Subprocess Tracking
+// ============================================================================
+
+let currentProc: ReturnType<typeof Bun.spawn> | null = null;
+
+/**
+ * Set the current running subprocess for tracking
+ */
+export function setCurrentProcess(proc: ReturnType<typeof Bun.spawn> | null): void {
+  currentProc = proc;
+}
+
+/**
+ * Kill any running subprocess on exit
+ */
+export function cleanupSubprocess(): void {
+  if (currentProc) {
+    try {
+      currentProc.kill();
+    } catch {
+      // Process may have already exited
+    }
+    currentProc = null;
+  }
+}