Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Ralph Engine - Automated feedback loop with LSP diagnostics and AST-grep integration for continuous code quality improvement. Use when implementing error-driven development, automated fixing, or continuous quality validation workflows.
| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-08 | ✗→✓ | ▲ Improved | 325% | 0% |
| case-10 | ✗→✓ | ▲ Improved | 133% | 0% |
| case-11 | ✗→✓ | ▲ Improved | 51% | 0% |
| case-17 | ✗→✓ | ▲ Improved | 232% | 0% |
| case-12 | ✗→✓ | ▲ Improved | 106% | 0% |
Automated feedback loop system integrating LSP diagnostics, AST-grep security scanning, and test validation for continuous code quality improvement.
The /moai loop skill (.claude/skills/moai/workflows/loop.md) re-expresses this Ralph engine as a goal preset built ON the goal engine: a scan stage builds a finite issue queue, and the iterate-until-done decision is delegated to the goal engine (stop-goal) with the pre-filled condition "queue drained + diagnostics clean". In this preset architecture, this SKILL.md documents the underlying LSP / AST-grep / test / coverage diagnostic machinery that the goal-preset sweep drives; the preset layers the goal-engine composition on top of that machinery WITHOUT changing it. The four loop quadrants (goal-based sweep, turn-based /moai fix, time-based cadence, proactive CI-watch) are presets on the one goal engine, not independent engines.
Core Capabilities:
Key Components:
Commands:
When to Use:
The Ralph Engine follows a layered architecture. User commands such as /moai:loop, /moai:fix, and /moai enter the Command Layer. The Command Layer invokes the Hook System, which contains the PostToolUse Hook for LSP diagnostics and the Stop Hook for loop control. The Hook System connects to Backend Services including the LSP Client (MoAILSPClient), AST-grep Scanner, and Test Runner. Backend Services feed into Completion Check which evaluates whether errors are zero, tests pass, and coverage is met. Based on the Completion Check result, the system either continues the loop or completes.
The ralph.yaml configuration file contains the following sections and settings.
Under the ralph section, enabled controls whether Ralph is active (true by default).
Under the lsp section, auto_start controls automatic language server startup (true by default), timeout_seconds sets the connection timeout (30 seconds default), and graceful_degradation enables fallback to linters when LSP unavailable (true by default).
Under the ast_grep section, enabled controls AST-grep integration (true by default), security_scan enables security rule checking (true by default), and quality_scan enables code quality rule checking (true by default).
Under the loop section, max_iterations sets the maximum loop iterations (10 by default), auto_fix controls automatic fix application (false by default requiring confirmation), and require_confirmation requires user approval before fixes (true by default).
Under the completion subsection of loop, zero_errors requires no LSP or compiler errors (true by default), zero_warnings requires no warnings (false by default as optional), tests_pass requires all tests to pass (true by default), and coverage_threshold sets minimum coverage percentage (85 by default).
Under the hooks section, post_tool_lsp has enabled (true by default) and severity_threshold (error by default). The stop_loop_controller has enabled set to true by default.
The PostToolUse hook is triggered after Write and Edit operations. When invoked, Claude Code provides hook input containing the tool_name (such as Write) and tool_input containing the file_path and content.
The hook processes diagnostics and returns hook output with hookSpecificOutput containing the hookEventName (PostToolUse) and additionalContext describing the diagnostic results. For example, the context might report LSP found 2 errors and 3 warnings in file.py, with specific error messages including line numbers.
Exit code 0 indicates no action needed. Exit code 2 indicates attention needed due to errors found.
The Stop hook is triggered after each Claude response. The hook reads the loop state file located at .moai/cache/.moai_loop_state.json. This state contains active status (true or false), current iteration number, max_iterations limit, last_error_count from previous iteration, and completion_reason when finished.
The hook returns output with hookSpecificOutput containing hookEventName (Stop) and additionalContext reporting loop status. For example, it might report Ralph Loop CONTINUE at Iteration 3 of 10 with 2 Errors, and next actions to fix the remaining errors.
Exit code 0 indicates loop complete or inactive. Exit code 1 indicates continue loop with more work needed.
The Go LSP client is integrated into the hook system. LSP diagnostics are automatically collected via the post-tool hook (moai hook post-tool-use).
To get diagnostics for a file, call the get_diagnostics method asynchronously with the file path.
Process the returned diagnostics by iterating through each diagnostic object. Check the severity property against DiagnosticSeverity.ERROR to identify errors. Access the line number from diag.range.start.line and the message from diag.message.
The loop completes when all enabled conditions are met.
The zero_errors condition (default true) requires no LSP or compiler errors.
The zero_warnings condition (default false) optionally requires no warnings.
The tests_pass condition (default true) requires all tests to pass.
The coverage_threshold condition (default 85) requires minimum coverage percentage.
Extend the loop controller with custom conditions by implementing a check function. For example, create a function to count TODO comments in the codebase and return true only when the count reaches zero.
For GitHub Actions integration, create a workflow step that runs Claude with the /moai:loop command and max-iterations flag. Set the MOAI_LOOP_ACTIVE environment variable to true to enable loop mode.
When LSP is unavailable, the system falls back to linter-based diagnostics using tools like ruff or eslint, then to compiler error detection, and finally to test failure detection.
Check that ralph.enabled is set to true in configuration. Verify MOAI_DISABLE_LOOP_CONTROLLER environment variable is not set. Ensure the state file location is writable.
Check LSP server configuration in .moai/config/sections/lsp.yaml. Verify the language server is installed for your language. Check that MOAI_DISABLE_LSP_DIAGNOSTIC environment variable is not set.
Review the max_iterations setting to ensure it allows sufficient iterations. Review completion conditions to verify they are achievable. Send any message to interrupt the loop, or delete the state file (.moai/cache/.moai_loop_state.json) to reset.
Skills:
moai ast-grep / moai ast-edit: security scanning patterns and rewrites.claude/rules/moai/languages/python.md: Python-specific patterns (auto-loaded via paths frontmatter).claude/rules/moai/languages/typescript.md: TypeScript patterns (auto-loaded via paths frontmatter)Agents:
Commands:
MOAI_DISABLE_LSP_DIAGNOSTIC disables the LSP hook when set.
MOAI_DISABLE_LOOP_CONTROLLER disables the loop hook when set.
MOAI_LOOP_ACTIVE indicates whether the loop is currently active.
MOAI_LOOP_ITERATION contains the current iteration number.
CLAUDE_PROJECT_DIR contains the project root path.
Configuration is stored at .moai/config/sections/ralph.yaml.
Loop state is stored at .moai/cache/.moai_loop_state.json.
The LSP hook is located at .claude/hooks/moai/handle-post-tool.sh.
The loop hook is located at .claude/hooks/moai/handle-stop.sh.
LSP diagnostics are available for all 16 MoAI-supported languages: C++, C#, Elixir, Flutter, Go, Java, JavaScript, Kotlin, PHP, Python, R, Ruby, Rust, Scala, Swift, and TypeScript. Ralph detects the project language via marker files (for example go.mod for Go, pyproject.toml for Python, tsconfig.json for TypeScript, Cargo.toml for Rust, pubspec.yaml for Flutter) and spawns the matching language server on demand. Users install only the servers their projects actually need; missing servers trigger a warn-and-skip with an install hint, never a hard failure. See references/reference.md for the complete language-server-to-binary mapping table. Per .claude/rules/moai/development/coding-standards.md § Language Policy (16-language neutrality contract), no language receives priority over another.
Version: 1.2.0 Status: Active Integration: Claude Code Hooks, LSP Protocol, AST-grep Skill Name: moai-workflow-loop (formerly moai-ralph)
<!-- moai:evolvable-start id="rationalizations" -->
| Rationalization | Reality | |---|---| | "I will fix the remaining errors manually after the loop" | Manual follow-up means the loop did not finish its job. Errors left are errors shipped. | | "The loop hit max iterations, the remaining issues are minor" | Iteration limits exist for cost control, not as a quality seal. Report the unresolved list. | | "LSP warnings are not real errors" | Warnings that persist across iterations indicate ignored structural issues. Address or explicitly suppress. | | "I fixed the root cause, the other diagnostics will clear themselves" | Cascading fixes are not guaranteed. Run the diagnostic pass again and verify each resolution. | | "ast-grep rules are too strict for this codebase" | Rules reflect project conventions. Disable the specific rule with justification, do not skip the entire scan. | | "This iteration made no progress, I should stop" | Stagnation after 2 iterations triggers escalation, not silent exit. Follow the escalation protocol. |
Rule of 500: Changes touching more than 500 lines deserve their own loop iteration with focused diagnostics. Large changes mask individual regressions.
<!-- moai:evolvable-end -->
<!-- moai:evolvable-start id="red-flags" -->
<!-- moai:evolvable-end -->
<!-- moai:evolvable-start id="verification" -->
<!-- moai:evolvable-end -->
Other measured skills in the registry, with their headline benchmark lift.