ralph-loop

What This Skill Does

The ralph-loop skill empowers OpenClaw agents to execute sophisticated coding workflows, commonly referred to as Ralph Loops. This skill leverages the exec and process tools to manage AI coding agents like Codex, Claude Code, OpenCode, and Goose. It ensures proper TTY support for interactive command-line interfaces, essential for many AI coding tools to function correctly. The process involves agents planning and building code by interacting with PROMPT.md and AGENTS.md, and referencing SPECS and IMPLEMENTATION_PLAN.md. The skill supports distinct PLANNING and BUILDING modes, incorporates backpressure mechanisms for stability, offers sandboxing for safety, and defines clear completion conditions. Users initiate these loops by requesting specific coding tasks, which the agent then orchestrates and executes using the specified tools.

Installation

To install the ralph-loop skill, use the following command:

clawhub install openclaw/skills/skills/addozhang/ralph-loop-agent

This command assumes you have ClawHub configured and accessible. The skill is part of the openclaw/skills repository, authored by addozhang.

Use Cases

The ralph-loop skill is ideal for automating complex coding tasks that require iterative development and interaction with AI coding assistants. Specific use cases include:

• Automated Code Generation: Guiding an AI to generate code from natural language requirements, specifications, or existing codebases.
• Iterative Refinement: Continuously improving code based on feedback, testing, or evolving requirements by running through the PLANNING and BUILDING loops.
• Bug Fixing and Patching: Providing an AI with context about a bug and having it iteratively attempt to fix and verify the solution.
• Feature Implementation: Breaking down a new feature request into manageable tasks, planning the implementation, and then building the code iteratively.
• Prototyping: Quickly generating and refining prototypes for new software ideas.

Example Prompts

1. "Run a BUILDING loop for the task: Implement user authentication using JWT. Use the claude model. Run for a maximum of 15 iterations."
2. "Start a PLANNING loop to refactor the database schema based on the latest specs. Use opencode and set max iterations to 7."
3. "Execute a full Ralph Loop (PLANNING and BUILDING) to add a new API endpoint for user profiles. Use the goose model and default iteration counts."

Tips & Limitations

• TTY Requirement: For interactive agents like OpenCode, Codex, Claude Code, Pi, and Goose, ensure pty: true is correctly configured in the exec tool parameters. Non-interactive CLIs might work with simpler loop configurations.
• Monitoring: The process tool is crucial for monitoring the exec sessions. Use poll for status, log for output, and kill for termination.
• Context Persistence: The skill relies on PROMPT.md and AGENTS.md to maintain context across iterations. Ensure these files are updated and available in the working directory.
• Completion Conditions: The loop's termination is often dictated by specific text within IMPLEMENTATION_PLAN.md. Define clear completion markers for reliable automated stopping.
• Resource Intensive: Running complex coding loops can be resource-intensive, both in terms of computation and AI model usage. Monitor costs and resource allocation.
• Agent Specifics: Different coding agents have varying strengths and weaknesses. Experiment with different models and configurations to find what works best for your task.
• Error Handling: Implement robust error handling and retry mechanisms within your prompts or agent logic to manage potential failures during code execution or AI interaction.