Migrating from Ralph Loops

If you’ve been running coding agent tasks inside Ralph Loops, you already understand the core insight: iteration beats perfection. You’ve seen what happens when you hand a well-written prompt to an AI agent and let it grind until the job is done.

This guide shows how to take that same philosophy and express it as a declarative, reproducible workflow in duckflux. You gain structure, observability, and composability without giving up the power of iterative automation.

---

What are Ralph Loops?

Ralph Wiggum is an iterative AI development methodology built on a deceptively simple idea: feed a prompt to a coding agent in a loop until the task is complete. Named after the Simpsons character (who stumbles forward until he accidentally succeeds), the technique treats failures as data points and bets on persistence.

Although it originated in the Claude Code ecosystem, the pattern is agent-agnostic. It works with any CLI-based coding agent (Codex, Gemini CLI, aider, etc.). The canonical form is a bash one-liner:

while :; do cat PROMPT.md | <your-agent-cli> ; done

Some agent plugins offer structured commands for it. For example, with the Claude Code Ralph plugin:

/ralph-loop:ralph-loop "Build the auth module" --max-iterations 15 --completion-promise "ALL_TESTS_PASS"

Ralph works. It has shipped hackathon projects overnight, completed $50k contracts for under $300 in API costs, and built entire programming languages. The methodology rests on four principles:

1. Iteration over perfection: refinement through repetition, not first-pass accuracy.
2. Failures are data: deterministic failures give you predictable, actionable feedback.
3. Operator skill matters: prompt quality determines outcomes, not just model capability.
4. Persistence wins: retry logic continues until the task is done.

Where Ralph starts to hurt

Ralph Loops excel at greenfield, single-agent tasks with clear completion criteria. But as your automation grows, the cracks show:

• No visibility. A bash loop gives you no structured trace of what happened, which iteration failed, or why.
• No composition. Chaining multiple Ralph Loops means writing more bash glue (conditionals, file watchers, error handling), all imperatively.
• No reuse. Each loop is a bespoke script. There’s no shared vocabulary for “retry 3 times”, “run these in parallel”, or “skip this step if X”.
• No portability. The loop is tied to your shell, your machine, your specific agent CLI setup.

These aren’t flaws in Ralph. They’re the natural ceiling of an imperative approach. Once you need orchestration, you need a DSL.

---

What is duckflux?

duckflux is a declarative, YAML-based workflow DSL. You describe what should happen and in what order. The runtime handles execution, retries, parallelism, error handling, and tracing.

flow:
  - type: exec
    run: npm test

No SDK. No boilerplate. No vendor lock-in. A workflow is a .duck.yaml file that any conforming runtime can execute.

Key features that matter for this migration:

• Retry & error handling: built into the spec, not bolted on with bash.
• Loops: native loop construct with until conditions and max caps, using CEL expressions.
• Parallel execution: declare concurrent steps without & and wait.
• I/O chaining: output from one step flows as input to the next, automatically.
• Execution tracing: structured logs of every step, input, output, and error.

---

Side-by-side comparison

Let’s look at a real pattern: running a code generation prompt iteratively until tests pass, with a maximum number of retries.

The Ralph way

# PROMPT.md contains the generation instructions
# $AGENT is your coding agent CLI (claude, codex, aider, etc.)
MAX=10
i=0
while [ $i -lt $MAX ]; do
  cat PROMPT.md | $AGENT
  if npm test 2>/dev/null; then
    echo "Tests pass. Done."
    exit 0
  fi
  i=$((i + 1))
  echo "Iteration $i/$MAX — tests failed, retrying..."
done
echo "Gave up after $MAX iterations."
exit 1

What’s happening here:

1. Feed the prompt to the coding agent.
2. Run the test suite.
3. If tests pass, stop. Otherwise, loop.
4. Give up after 10 iterations.

This works, but the logic is scattered across bash control flow, there’s no structured output, and extending it (add a lint step? run two agents in parallel?) means rewriting the script.

The duckflux way

codegen-loop.duck.yaml

flow:
  - as: generate-and-test
    type: exec
    run: cat PROMPT.md | $AGENT && npm test
    onError: retry
    retry:
      max: 10

That’s it. The same behavior (iterative execution with a retry ceiling) expressed in 6 lines of YAML.

But duckflux lets you go further. Let’s decompose the steps and add observability:

codegen-loop-v2.duck.yaml

participants:
  generate:
    type: exec
    run: cat PROMPT.md | $AGENT

flow:
  - loop:
      until: run-tests.status == "success"
      max: 10
      steps:
        - generate
        - as: run-tests
          type: exec
          run: npm test
          onError: skip

Now each iteration is traced individually. You can see exactly which iteration failed, what the test output was, and how many cycles it took. The loop construct replaces the bash loop, onError: skip replaces the silent 2>/dev/null, and until replaces the implicit exit condition.

---

Migration cookbook

Below are common Ralph patterns and their duckflux equivalents.

Simple loop until completion

Ralph:

while :; do cat PROMPT.md | $AGENT ; done

duckflux:

flow:
  - type: exec
    run: cat PROMPT.md | $AGENT
    onError: retry
    retry:
      max: 50

Phased loops (multi-step)

Ralph:

# Phase 1
/ralph-loop:ralph-loop "Build the API" --max-iterations 20 --completion-promise "API_DONE"
# Phase 2
/ralph-loop:ralph-loop "Build the UI" --max-iterations 20 --completion-promise "UI_DONE"

duckflux:

participants:
  build-api:
    type: exec
    run: cat PROMPT_API.md | $AGENT
    onError: retry
    retry:
      max: 20

  build-ui:
    type: exec
    run: cat PROMPT_UI.md | $AGENT
    onError: retry
    retry:
      max: 20

flow:
  - build-api
  - build-ui

Each phase is a named participant. Execution is sequential by default, so phase 2 only starts after phase 1 succeeds.

Parallel worktrees

Ralph:

git worktree add ../project-auth -b feature/auth
git worktree add ../project-api -b feature/api

cd ../project-auth
/ralph-loop:ralph-loop "Build auth" --max-iterations 30 &

cd ../project-api
/ralph-loop:ralph-loop "Build API" --max-iterations 30 &

wait

duckflux:

flow:
  - parallel:
      - as: auth
        type: exec
        run: cat PROMPT_AUTH.md | $AGENT
        cwd: ../project-auth
        onError: retry
        retry:
          max: 30
      - as: api
        type: exec
        run: cat PROMPT_API.md | $AGENT
        cwd: ../project-api
        onError: retry
        retry:
          max: 30

No &, no wait, no PID management. The runtime handles concurrency, and the trace shows both branches side by side.

Conditional continuation

Ralph:

cat PROMPT.md | $AGENT
if [ -f "output.json" ]; then
  cat PROMPT_PHASE2.md | $AGENT
fi

duckflux:

participants:
  phase1:
    type: exec
    run: cat PROMPT.md | $AGENT

  phase2:
    type: exec
    run: cat PROMPT_PHASE2.md | $AGENT

flow:
  - phase1
  - phase2:
      when: phase1.status == "success"

---

What you gain

Concern	Ralph Loop	duckflux
Retry logic	Hand-rolled bash	onError: retry + retry.max
Parallel execution	& + wait + PID tracking	parallel: with named branches
Error handling	set -e / trap / if chains	onError: fail | skip | retry per step
Execution trace	Terminal scrollback	Structured JSON trace with step-level detail
Composition	Copy-paste scripts	Named participants + nested workflows
Portability	Bash + your machine	Any duckflux-conforming runtime
Readability	Grows linearly with complexity	Declarative: complexity stays flat

---

Getting started

1. Install the runtime:

bun add -g @duckflux/runner

2. Write your workflow as a .duck.yaml file using the patterns above.

3. Run it:

quack run codegen-loop.duck.yaml

4. Inspect the trace to see exactly what happened at each step.

Tip

You don’t have to migrate everything at once. Start with your most painful Ralph loop (the one with the most bash glue around it) and express it as a duckflux workflow. Keep your simpler loops as-is until you feel the benefit.

---

Final thoughts

Ralph Loops proved that iterative AI automation works. duckflux takes that insight and gives it structure. The philosophy stays the same (iteration over perfection, persistence wins), but you trade bash glue for a declarative spec that’s reproducible, traceable, and composable.

The best prompt in the world still needs an orchestrator. That’s what duckflux is for.