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 | ; done

Enter fullscreen mode

Exit fullscreen mode

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"

Enter fullscreen mode

Exit fullscreen mode

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:

• Iteration over perfection: refinement through repetition, not first-pass accuracy.

• Failures are data: deterministic failures give you predictable, actionable feedback.

• Operator skill matters: prompt quality determines outcomes, not just model capability.

• 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`

Enter fullscreen mode

Exit fullscreen mode

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`

Enter fullscreen mode

Exit fullscreen mode

What's happening here:

• Feed the prompt to the coding agent.

• Run the test suite.

• If tests pass, stop. Otherwise, loop.

• 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

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

Enter fullscreen mode

Exit fullscreen mode

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:

flow:

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

Enter fullscreen mode

Exit fullscreen mode

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

Enter fullscreen mode

Exit fullscreen mode

duckflux:

flow:

• type: exec run: cat PROMPT.md | $AGENT onError: retry retry: max: 50`

Enter fullscreen mode

Exit fullscreen mode

Phased loops (multi-step)

Ralph:

Phase 2

/ralph-loop:ralph-loop "Build the UI" --max-iterations 20 --completion-promise "UI_DONE"`

Enter fullscreen mode

Exit fullscreen mode

duckflux:

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

flow:

• build-api
• build-ui`

Enter fullscreen mode

Exit fullscreen mode

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

Parallel worktrees

Ralph:

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`

Enter fullscreen mode

Exit fullscreen mode

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`

Enter fullscreen mode

Exit fullscreen mode

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

Conditional continuation

Ralph:

Enter fullscreen mode

Exit fullscreen mode

duckflux:

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

flow:

• phase1
• phase2: when: phase1.status == "success"`

Enter fullscreen mode

Exit fullscreen mode

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 \

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

• Install the runtime: {% raw %}

bun add -g @duckflux/runner

Enter fullscreen mode

Exit fullscreen mode

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

• Run it:

duckflux run codegen-loop.flux.yaml

Enter fullscreen mode

Exit fullscreen mode

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