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 .flux.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.flux.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.flux.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

Getting started

1. Install the runtime: {% raw %}

bun add -g @duckflux/runner

1. Write your workflow as a .flux.yaml file using the patterns above.

2. Run it:
   

duckflux run codegen-loop.flux.yaml

1. 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.

Check the duckflux docs for the full DSL reference, or jump straight to the spec.