/moai loop

The autonomous iterative fix-loop command. The AI diagnoses issues, fixes them, and verifies the fixes on its own, repeating automatically until every error is resolved.

Info

One-line summary: /moai loop is an autonomous fix engine called the “Ralph Engine.” It repeats diagnose → fix → verify to resolve every problem in the code automatically.

Info

Slash command: In Claude Code, type /moai:loop to run this command directly. Typing just /moai shows the list of all available subcommands.

While writing code, multiple problems can pile up at once — type errors, lint warnings, test failures. Instead of fixing these one by one manually, run /moai loop and the AI fixes everything iteratively and automatically.

Unlike /moai fix, which fixes only once, /moai loop keeps repeating until the completion conditions are satisfied.

This loop is the flagship example of v3’s second pillar, agentic loop engineering. Instead of a human intervening at every error, the loop diagnoses and fixes on its own, and the observations the loop leaves behind accumulate as raw material for harness learning (recursive self-learning). The engine implementation is internal/ralph/engine.go — each iteration’s Decide() judges one of continue / converge / request_review / abort in priority order.

/moai loop is a preset on top of the goal engine. While /moai goal "<condition>" is a general-purpose loop where the user declares the completion condition directly, /moai loop is a preset that pre-fills the condition “until the issue queue found by the diagnostic tools is fully drained.”

/moai goal "go test ./... exits 0; all ACs recorded as PASS"
/moai goal status | clear

If you can express the end state as a condition, use /moai goal; if it is “remove everything the tools find,” /moai loop is the right fit.

> /moai loop

Run it without arguments and it automatically finds and fixes every problem in the current project.

Limits the number of iterations:

# Iterate up to 20 times
> /moai loop --max 20

Warning

To prevent infinite loops, the default is 10 iterations (ralph.yaml’s loop.max_iterations). The iteration-ceiling priority is CLI --max flag > ralph.yaml loop.max_iterations > workflow.yaml loop_prevention.max_iterations.

In addition to the default scan lenses (LSP · lint · test failures · review lenses [security, @MX]), opt-in lenses widen the scan scope:

Only what a lens finds is placed in the queue; the loop never performs “invented improvements” outside the scanned queue.

/moai loop goes through the following steps on every iteration.

flowchart TD
    Start["/moai loop run"] --> Diag

    subgraph Diag["Step 1: parallel diagnostics"]
        D1["LSP diagnostics
type error check"]
        D2["AST-grep diagnostics
structural pattern check"]
        D3["Test run
failing test detection"]
        D4["Coverage measurement
check below 85%"]
    end

    Diag --> Collect["Step 2: issue collection"]
    Collect --> Todo["Step 3: TODO generation
fix task list"]
    Todo --> Fix["Step 4: sequential fixing
fix safely one by one"]
    Fix --> Verify["Step 5: verification
confirm fix results"]
    Verify --> Check{Completion
conditions met?}
    Check -->|No| Diag
    Check -->|Yes| Done["Loop completion stated"]

Four diagnostic tools run simultaneously to quickly identify every problem in the project.

Info

What are parallel diagnostics? The 4 diagnostics run at the same time, making them about 4x faster than running them sequentially. The collected problems are merged into a single list.

All the problems found by parallel diagnostics are organized into a single list.

Issues found (example):
  [LSP] src/auth/service.py:42 - cannot assign "int" to "str"
  [LSP] src/auth/router.py:15 - "User" type undefined
  [AST] src/utils/helper.py:3 - unused import "os"
  [TEST] tests/test_auth.py::test_login - AssertionError
  [COV] src/auth/service.py - coverage 62% (target 85%)

A fix-task list (TODO) is generated automatically from the collected issues. Dependency order is taken into account when deciding the fix sequence.

For example, if a type definition is missing, that type is added first, then the code using it is fixed.

Items in the TODO list are fixed one by one, sequentially. Fixing in parallel could cause conflicts, so they are handled safely one at a time.

After the fixes, diagnostics run again to confirm the problems are resolved. If issues remain, it goes back to Step 1 and repeats.

Two safeguards prevent infinite loops. Letting a loop run indefinitely also wastes tokens, so the safeguards protect both stability and tokenomics.

flowchart TD
    A[Run iteration] --> B{Maximum iterations
exceeded?}
    B -->|Yes: ceiling reached| C["Force stop
5-section verdict + persist residual issues"]
    B -->|No| D{N consecutive
no-progress iterations?}
    D -->|Yes: same failure repeats| E["Stagnation detected
request user intervention"]
    D -->|No| F[Continue to next iteration]

Warning

What if a stagnation occurs? If the AI fails to resolve the same failure signature consecutively, it stops automatically and requests your intervention with a 5-section evidence verdict. In that case, inspect the error yourself or provide a hint.

/moai loop ends the loop when all three of the following conditions are satisfied.

/moai fix and /moai loop look similar, but there is a key difference.

flowchart TD
    subgraph Fix["/moai fix (one-shot)"]
        F1[Parallel scan] --> F2[Issue collection]
        F2 --> F3[Level classification]
        F3 --> F4[Fix]
        F4 --> F5[Verify]
        F5 --> F6[Done]
    end

    subgraph Loop["/moai loop (iterative)"]
        L1[Parallel diagnostics] --> L2[Issue collection]
        L2 --> L3[TODO generation]
        L3 --> L4[Sequential fixing]
        L4 --> L5[Verify]
        L5 --> L6{Done?}
        L6 -->|No| L1
        L6 -->|Yes| L7[Done]
    end

Info

Selection guide: if there are only a few errors, resolve them quickly with /moai fix. If there are many errors or interrelated problems, /moai loop is more effective.

The agent delegation flow of the /moai loop command:

flowchart TD
    User["User request"] --> Orchestrator["MoAI orchestrator"]
    Orchestrator --> ManagerDDD["manager-develop agent"]

    ManagerDDD --> Diagnose["Parallel diagnostics"]
    Diagnose --> LSP["LSP"]
    Diagnose --> AST["AST-grep"]
    Diagnose --> Test["Tests"]
    Diagnose --> Cov["Coverage"]

    LSP --> Todo["TODO generation"]
    AST --> Todo
    Test --> Todo
    Cov --> Todo

    Todo --> Loop["Loop start"]

    Loop --> Fix["Delegate fixes to
manager-develop"]
    Fix --> Predicate{"Mechanical completion predicate
(queue drained + diagnostics clean)?"}
    Predicate -->|No| Loop
    Predicate -->|Yes| FinalPass["Step 1.5
independent final pass"]
    FinalPass --> Done["Done"]

Completion decision — mechanical predicate + independent final pass:

The loop’s successful termination is decided by a mechanical completion predicate — the orchestrator directly checks whether the issue queue is empty and the diagnostics (LSP/AST-grep/tests/coverage) are clean. No separate audit agent (sync-auditor) decides completion.

Once the predicate is satisfied, the Step 1.5 Independent Final Pass runs on the success-termination path — it runs /moai gate --fresh in a fresh context or spawns a read-only verification Agent to independently confirm the final state, so the loop does not inspect itself.

Agent roles:

Assume several errors remain after implementing code with /moai run.

# Check the current state
$ pytest --tb=short
# 3 tests failing
# Coverage: 71%

# Check LSP errors
# 5 type errors, 2 undefined references

# Run the loop
> /moai loop

Execution log:

[Iteration 1/10]
  Diagnostics: 5 LSP errors, 3 test failures, coverage 71%
  TODO: 7 fix tasks generated
  Fix: 5 type errors resolved
  Verify: 0 LSP errors, 2 test failures, coverage 71%

[Iteration 2/10]
  Diagnostics: 2 test failures, coverage 71%
  TODO: 2 fix tasks generated
  Fix: 2 test-logic fixes
  Verify: 0 LSP errors, 0 test failures, coverage 74%

[Iteration 3/10]
  Diagnostics: coverage 74% (target 85%)
  TODO: 3 test-addition tasks generated
  Fix: missing test cases added
  Verify: 0 LSP errors, 0 test failures, coverage 87%

Completion conditions met!
  - LSP errors: 0
  - Tests: all passing
  - Coverage: 87%

DONE

In this example, /moai loop resolved every problem in just 3 iterations. Doing it manually would have meant checking and fixing each error one by one.

You can limit iterations with the --max flag, or interrupt with Ctrl+C. The current state is saved, so you can resume later.

Use the --errors flag to fix errors only and skip warnings, or the --lens flag to adjust the scan scope:

# Fix errors only (skip warnings)
> /moai loop --errors

# Add the dead-code and coverage lenses
> /moai loop --lens clean,coverage

/moai loop handles only the error-fixing loop. /moai automatically runs the entire workflow from SPEC creation through implementation to documentation.

/moai loop aims to eliminate the issues found by diagnostic tools (LSP, tests, linters), while /moai goal keeps taking turns toward an arbitrary completion condition the user declared (e.g. “achieve AC-001 through AC-010”). /moai loop is a preset of the goal engine.

If the AI fails to resolve the same failure signature N times in a row (stagnation detection), it stops automatically and requests your intervention with a 5-section evidence verdict. In that case, inspect the code yourself or provide a hint.

• /moai fix - one-shot auto-fix
• /moai - fully autonomous automation
• TRUST 5 Quality System
• Domain-Driven Development