Ralph Wiggum — Continuous Self-Referential AI Loops

flowchart LR
    subgraph UserEntry["User Interaction"]
        U["User"] -->|"/ralph-loop"| RL["Start Loop"]
        U -->|"/cancel-ralph"| CR["Cancel Loop"]
        U -->|"/ralph-wiggum:help"| HLP["Show Help"]
    end
    subgraph LoopEngine["Autonomous Loop Engine"]
        RL --> INIT["Initialize State File"]
        INIT --> WORK["Claude Performs Work"]
        WORK --> EXIT["Session Attempts Exit"]
        EXIT --> SH["stop-hook.sh Intercepts"]
        SH --> RS["Read State File"]
        RS --> CHECK{"Completion
Promise Met?"}
        CHECK -->|No| RF["Re-feed Prompt"]
        RF --> INCR["Increment Iteration"]
        INCR --> WORK
        CHECK -->|Yes| DONE["Allow Exit"]
    end
    subgraph StateManagement["State"]
        SF["ralph-loop.local.md"]
        GH["Git History"]
        RS --> SF
        RS --> GH
    end

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Hook as stop-hook.sh
    participant State as ralph-loop.local.md
    participant Git as Git History

    User->>Claude: /ralph-loop --promise "all tests pass"
    Claude->>State: Create state file (iteration: 0, max: 10)
    Claude->>Claude: Perform work (iteration 1)
    Claude->>Hook: Session exit triggered
    Hook->>State: Read current state
    State-->>Hook: iteration: 1, promise: "all tests pass"
    Hook->>Git: Check recent commits & diff
    Git-->>Hook: Changes summary
    Hook->>Hook: Evaluate completion promise
    Hook-->>Claude: Promise NOT met → block exit
    Hook->>State: Update iteration: 2
    Hook->>Claude: Re-feed prompt with context
    Claude->>Claude: Perform work (iteration 2)
    Claude->>Hook: Session exit triggered
    Hook->>State: Read current state
    Hook->>Git: Check recent commits
    Hook->>Hook: Evaluate completion promise
    Hook-->>Claude: Promise MET → allow exit
    Claude-->>User: Loop complete (2 iterations)

flowchart TD
    subgraph Initialization
        CMD["/ralph-loop --promise 'tests pass'"] --> PARSE["Parse Arguments"]
        PARSE --> CREATE["Create State File"]
        CREATE --> REGISTER["Register Stop Hook"]
    end
    subgraph IterationCycle["Each Iteration"]
        REGISTER --> WORK["Claude Performs Work"]
        WORK --> COMMIT["Changes Committed"]
        COMMIT --> TRIGGER["Exit Triggers Hook"]
        TRIGGER --> READ["Read State + Git"]
        READ --> EVAL{"Promise
Evaluation"}
        EVAL -->|"Not Met"| UPDATE["Update State File"]
        UPDATE --> REFEED["Re-feed Prompt"]
        REFEED --> WORK
        EVAL -->|"Met"| SUMMARY["Generate Summary"]
    end
    subgraph Termination
        SUMMARY --> LOG["Write Final Log"]
        LOG --> CLEANUP["Clean Up Hook"]
        CLEANUP --> EXIT["Session Exits"]
    end