AGENTS.md

1# src/hooks/ralph-loop/ -- Self-Referential Dev Loop
2 
3**Generated:** 2026-07-17
4 
5## OVERVIEW
6 
7**DEPRECATED.** Superseded by [`goal/`](../goal/) (PR #6184 "goal-replaces-ralph"). `ralphLoop` was removed from `HookNameSchema` and `create-session-hooks.ts`; the `/ralph-loop`, `/ulw-loop`, `/cancel-ralph` builtin commands and templates were removed; `ralph_loop` config is a deprecated passthrough for migration. The directory, `createRalphLoopHook` factory, and barrel export remain, but no composer imports them.
8 
9~52 .ts files (31 impl + 21 tests). Iterates a development loop until the agent emits `<promise>DONE</promise>` or max iterations reached. No longer wired into any tier.
10 
11## LOOP LIFECYCLE
12 
13```
14/ralph-loop → startLoop(sessionID, prompt, options)
15  → loopState.startLoop() → persists state to .omo/ralph-loop.local.md
16  → session.idle events → createRalphLoopEventHandler()
17    → completionPromiseDetector: scan output for <promise>DONE</promise>
18    → if not done: inject continuation prompt → loop
19    → if done or maxIterations: cancelLoop()
20```
21 
22## KEY FILES
23 
24| File | Purpose |
25|------|---------|
26| `ralph-loop-hook.ts` | `createRalphLoopHook()` -- composes controller + recovery + event handler |
27| `ralph-loop-event-handler.ts` | `createRalphLoopEventHandler()` -- handles session.idle, drives loop |
28| `loop-state-controller.ts` | State CRUD: startLoop, cancelLoop, getState, persist to disk |
29| `loop-session-recovery.ts` | Recover from crashed/interrupted loop sessions |
30| `completion-promise-detector.ts` | Scan session transcript for `<promise>DONE</promise>` |
31| `continuation-prompt-builder.ts` | Build continuation message for next iteration |
32| `continuation-prompt-injector.ts` | Inject built prompt into active session |
33| `storage.ts` | Read/write `.omo/ralph-loop.local.md` state file |
34| `message-storage-directory.ts` | Temp dir for prompt injection |
35| `with-timeout.ts` | API call wrapper with timeout (default 5000ms) |
36| `types.ts` | `RalphLoopState`, `RalphLoopOptions`, loop iteration types |
37 
38## STATE FILE
39 
40```
41.omo/ralph-loop.local.md  (gitignored)
42  → sessionID, prompt, iteration count, maxIterations, completionPromise, ultrawork flag
43```
44 
45## OPTIONS
46 
47```typescript
48startLoop(sessionID, prompt, {
49  maxIterations?: number  // Default from config (default: 100)
50  completionPromise?: string  // Custom "done" signal (default: "<promise>DONE</promise>")
51  ultrawork?: boolean  // Enable ultrawork mode for iterations
52})
53```
54 
55## EXPORTED INTERFACE
56 
57```typescript
58interface RalphLoopHook {
59  event: (input) => Promise<void>  // session.idle handler
60  startLoop: (sessionID, prompt, options?) => boolean
61  cancelLoop: (sessionID) => boolean
62  getState: () => RalphLoopState | null
63}
64```
65