Added Resume capability with the associated tests (#15)

* Added Resume capability with the associated tests

* Biome formatting code

* fix: add type annotations and fix flaky agent override test

- Add LoopState type annotations to cancel.ts and resume.ts to fix
  Biome noImplicitAnyLet lint errors
- Fix agent override test timeout by reading stdout incrementally
  and killing the process after collecting expected output

---------

Co-authored-by: Laith Al-Saadoon <9553966+theagenticguy@users.noreply.github.com>

Author: harmjeff

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [Unreleased]
+
+### Features
+
+* **resume:** add `ralph resume` command for resuming interrupted loops
+  - Resume stopped loops with full context about previous work
+  - Override loop parameters (min/max iterations, completion promise, agent)
+  - Enhanced prompt with instructions to review files, git history, and feedback
+  - Displays previous iteration number and quality score
+
+### Bug Fixes
+
+* **state:** preserve state on interruption instead of deleting
+  - Ctrl+C (SIGINT) now saves state with iteration and feedback
+  - Max iterations reached saves state for continuation
+  - `ralph cancel` marks state inactive instead of deleting
+  - Only delete state on successful task completion
+
+### Changes
+
+* **cancel:** `ralph cancel` now preserves state for resume instead of deleting
+* **loop-runner:** enhanced cleanup function to preserve state with iteration/feedback
+* **schema:** added `isResume` and `resumeFromIteration` fields to LoopConfig
+
+### Documentation
+
+* **resume:** added comprehensive RESUME_IMPLEMENTATION.md guide
+* **readme:** updated with resume command documentation and state preservation notes
+
 ## 1.0.0 (2026-01-12)
 
 

README.md

@@ -241,6 +241,13 @@ The agent will:
 3. Continue until it outputs `<promise>COMPLETE</promise>`
 4. Or stop when max iterations is reached
 
+If the loop is interrupted or you want to continue after it stops:
+
+```bash
+# Resume the loop with context about previous work
+ralph resume
+```
+
 ## Commands
 
 ### `ralph init`
@@ -288,14 +295,68 @@ ralph loop "Add input validation" -p "VALIDATION COMPLETE" -n 3 -m 20
 ralph loop "Build feature X" -a ./my-agent.json -m 15
 ```
 
+### `ralph resume`
+
+Resume a stopped Ralph loop with context about previous work.
+
+```bash
+ralph resume [OPTIONS]
+```
+
+**Options:**
+- `--min-iterations, -n` - Override minimum iterations before accepting completion
+- `--max-iterations, -m` - Override max iterations before auto-stop
+- `--completion-promise, -p` - Override phrase that signals completion
+- `--agent, -a` - Override agent name
+
+**How it works:**
+
+When you resume a stopped loop, Ralph will:
+1. Read the existing state file (`.kiro/ralph-loop.local.json`)
+2. Extract information about previous work and feedback
+3. Build an enhanced prompt with resume context that instructs the agent to:
+   - Review files that were created or modified
+   - Check git history to see what was accomplished
+   - Review previous feedback (quality score, next steps, improvements, blockers)
+4. Continue the loop from where it left off
+
+**Examples:**
+
+```bash
+# Resume with existing settings
+ralph resume
+
+# Resume but increase max iterations
+ralph resume -m 30
+
+# Resume with a different completion promise
+ralph resume -p "FINISHED"
+
+# Resume with all settings overridden
+ralph resume -n 5 -m 25 -p "DONE"
+```
+
+**Use cases:**
+- Loop was interrupted (Ctrl+C)
+- Hit max iterations but want to continue
+- Need to adjust iteration limits
+- Want the agent to re-evaluate with fresh context
+
 ### `ralph cancel`
 
-Cancel an active Ralph loop.
+Cancel an active Ralph loop and preserve state for resume.
 
 ```bash
 ralph cancel
 ```
 
+**What it does:**
+- Marks the loop as inactive (doesn't delete the state)
+- Preserves current iteration and feedback
+- Allows you to resume later with `ralph resume`
+
+**Note:** When a loop completes successfully (outputs the completion promise), the state is deleted automatically. When interrupted (Ctrl+C) or max iterations reached, the state is preserved for resume.
+
 ## How It Works
 
 ### 1. State File
@@ -555,6 +616,7 @@ Ralph embodies several key principles:
 
 ## Learn More
 
+- [Resume Feature Implementation Guide](RESUME_IMPLEMENTATION.md) - Complete documentation on the resume feature and state preservation
 - [Original technique by Geoffrey Huntley](https://ghuntley.com/ralph/)
 - [Ralph Orchestrator](https://github.com/mikeyobrien/ralph-orchestrator)
 - [Kiro CLI Documentation](https://kiro.dev/docs/cli/)

src/commands/cancel.ts

@@ -6,12 +6,12 @@
 import { unlink } from "node:fs/promises";
 import { log } from "@clack/prompts";
 
-import { stateFromJson } from "../schemas/state";
+import { type LoopState, stateFromJson } from "../schemas/state";
 import { SESSION_FILE, STATE_FILE } from "../utils/paths";
 
 /**
  * Cancels an active Ralph Wiggum loop.
- * Removes the state file and session file from the .ralph directory.
+ * Marks the state as inactive so it can be resumed later.
  * @returns Resolves when cancellation is complete
  */
 export async function cancelCommand(): Promise<void> {
@@ -22,21 +22,29 @@ export async function cancelCommand(): Promise<void> {
 		return;
 	}
 
-	// Try to get iteration number for display
+	// Read and parse the existing state
+	let state: LoopState;
 	let iteration: number | string = "?";
 	try {
 		const content = await stateFile.text();
-		const state = stateFromJson(content);
+		state = stateFromJson(content);
 		iteration = state.iteration;
 	} catch {
-		// Ignore parse errors, just show "?"
+		// If we can't parse the state, just delete it
+		await unlink(STATE_FILE).catch(() => {});
+		log.message("Cancelled Ralph loop (invalid state file)");
+		return;
 	}
 
-	// Delete state files
-	await Promise.all([
-		unlink(STATE_FILE).catch(() => {}),
-		unlink(SESSION_FILE).catch(() => {}),
-	]);
+	// Mark state as inactive (preserves for resume)
+	state.active = false;
+
+	// Write updated state back
+	await Bun.write(STATE_FILE, JSON.stringify(state));
+
+	// Delete session file (not needed for resume)
+	await unlink(SESSION_FILE).catch(() => {});
 
-	log.message(`Cancelled Ralph loop (was at iteration ${iteration})`);
+	log.message(`Cancelled Ralph loop at iteration ${iteration}`);
+	log.message("Run 'ralph resume' to continue where you left off.");
 }

src/commands/index.ts

@@ -7,3 +7,4 @@
 export { cancelCommand } from "./cancel";
 export { initCommand } from "./init";
 export { loopCommand } from "./loop";
+export { resumeCommand } from "./resume";

src/commands/resume.ts

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Resume command for Ralph Wiggum CLI.
+ * Resumes a stopped loop with context about previous work.
+ * @module commands/resume
+ */
+import { log } from "@clack/prompts";
+import pc from "picocolors";
+
+import { runLoop } from "../core/loop-runner";
+import { LoopConfigSchema } from "../schemas/config";
+import { type LoopState, stateFromJson } from "../schemas/state";
+import { STATE_FILE } from "../utils/paths";
+
+/**
+ * CLI options for the resume command (raw string values from commander).
+ */
+interface ResumeOptions {
+	/** Minimum iterations before checking completion (string from CLI) */
+	minIterations?: string;
+	/** Maximum iterations, 0 for unlimited (string from CLI) */
+	maxIterations?: string;
+	/** Phrase that signals loop completion */
+	completionPromise?: string;
+	/** Optional agent name override */
+	agent?: string;
+}
+
+/**
+ * Resumes a stopped Ralph Wiggum loop.
+ * Reads the existing state file, extracts information about previous work,
+ * and continues the loop with enhanced context.
+ * @param opts - Command options from CLI
+ * @returns Resolves when the loop completes or is interrupted
+ * @throws Exits process with code 1 if validation fails or no state file found
+ */
+export async function resumeCommand(opts: ResumeOptions): Promise<void> {
+	const stateFile = Bun.file(STATE_FILE);
+
+	// Check if state file exists
+	if (!(await stateFile.exists())) {
+		log.error(
+			pc.red(
+				"No stopped Ralph loop found. Run 'ralph loop' to start a new loop.",
+			),
+		);
+		process.exit(1);
+	}
+
+	// Read and parse the existing state
+	let existingState: LoopState;
+	try {
+		const content = await stateFile.text();
+		existingState = stateFromJson(content);
+	} catch (error) {
+		log.error(pc.red(`Failed to parse state file: ${error}`));
+		process.exit(1);
+	}
+
+	// Display information about the previous loop
+	log.info(pc.bold(pc.blue("Resuming Ralph loop")));
+	log.message(`   Previous iteration: ${existingState.iteration}`);
+	log.message(`   Original prompt: ${pc.dim(existingState.prompt)}`);
+	if (existingState.previousFeedback?.qualityScore) {
+		log.message(
+			`   Last quality score: ${existingState.previousFeedback.qualityScore}/10`,
+		);
+	}
+	console.log();
+
+	// Build enhanced prompt with resume context
+	const resumeContext = buildResumeContext(existingState);
+	const enhancedPrompt = `${resumeContext}\n\nOriginal task: ${existingState.prompt}`;
+
+	// Parse and validate options with Zod
+	// Use existing state values as defaults if not provided
+	const result = LoopConfigSchema.safeParse({
+		prompt: enhancedPrompt,
+		minIterations: opts.minIterations
+			? Number.parseInt(opts.minIterations, 10)
+			: existingState.minIterations,
+		maxIterations: opts.maxIterations
+			? Number.parseInt(opts.maxIterations, 10)
+			: existingState.maxIterations,
+		completionPromise:
+			opts.completionPromise ?? existingState.completionPromise,
+		agentName: opts.agent ?? null,
+		isResume: true,
+		resumeFromIteration: existingState.iteration,
+	});
+
+	if (!result.success) {
+		// Format Zod error messages
+		const errorMessages = result.error.issues
+			.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`)
+			.join("\n");
+		log.error(pc.red(`Validation error:\n${errorMessages}`));
+		process.exit(1);
+	}
+
+	await runLoop(result.data);
+}
+
+/**
+ * Builds context text about the previous loop for the resume prompt.
+ * @param state - The existing loop state
+ * @returns Formatted context string
+ */
+function buildResumeContext(state: ReturnType<typeof stateFromJson>): string {
+	const lines = [
+		"RESUME CONTEXT:",
+		"===============",
+		`You are resuming a Ralph loop that was stopped at iteration ${state.iteration}.`,
+		"",
+		"Before continuing, please:",
+		"1. Review what was accomplished in previous iterations by checking:",
+		"   - Files that were created or modified",
+		"   - Git history (git log, git diff)",
+		"   - Test results",
+		"   - Build artifacts",
+		"",
+		"2. Review the previous feedback to understand where you left off:",
+	];
+
+	if (state.previousFeedback) {
+		if (state.previousFeedback.qualitySummary) {
+			lines.push(`   Quality: ${state.previousFeedback.qualitySummary}`);
+		}
+
+		if (
+			state.previousFeedback.nextSteps &&
+			state.previousFeedback.nextSteps.length > 0
+		) {
+			lines.push("   Planned next steps:");
+			for (const step of state.previousFeedback.nextSteps) {
+				lines.push(`   - ${step}`);
+			}
+		}
+
+		if (
+			state.previousFeedback.improvements &&
+			state.previousFeedback.improvements.length > 0
+		) {
+			lines.push("   Areas for improvement:");
+			for (const improvement of state.previousFeedback.improvements) {
+				lines.push(`   - ${improvement}`);
+			}
+		}
+
+		if (
+			state.previousFeedback.blockers &&
+			state.previousFeedback.blockers.length > 0
+		) {
+			lines.push("   Blockers:");
+			for (const blocker of state.previousFeedback.blockers) {
+				lines.push(`   - ${blocker}`);
+			}
+		}
+
+		if (
+			state.previousFeedback.ideas &&
+			state.previousFeedback.ideas.length > 0
+		) {
+			lines.push("   Ideas to consider:");
+			for (const idea of state.previousFeedback.ideas) {
+				lines.push(`   - ${idea}`);
+			}
+		}
+	} else {
+		lines.push("   (No previous feedback available)");
+	}
+
+	lines.push("");
+	lines.push(
+		"3. Continue working toward completion of the original task below.",
+	);
+	lines.push("");
+
+	return lines.join("\n");
+}