ralph-operations

What This Skill Does

The ralph-operations skill serves as the central control plane for managing the OpenClaw AI agent's orchestration loops. It provides a comprehensive suite of command-line utilities to inspect, monitor, debug, and manage the lifecycle of Ralph agents. Whether you are dealing with active execution threads in a primary workspace or navigating isolated worktrees, this skill gives you granular visibility into the agent's decision-making process, including hat selection, tool utilization, and event history.

Installation

To integrate this skill into your environment, use the OpenClaw CLI package manager:

clawhub install openclaw/skills/skills/paulpete/ralph-operations

Use Cases

• Debugging Agent Stall: When an agent appears to be looping or unresponsive, use ralph loops logs <id> -f to watch real-time event streams and identify blocked tool calls or backpressure issues.
• Post-Mortem Analysis: After a process finishes, inspect .ralph/agent/summary.md and the event history to understand exactly why a specific hat was selected or why a merge was rejected.
• Workflow Recovery: If an automated merge fails, utilize the retry and merge commands to resolve conflicts without losing the work performed in a temporary worktree.
• Diagnostics: Enable RALPH_DIAGNOSTICS=1 for deep performance profiling, which generates detailed audit logs in the .ralph/diagnostics/ folder for root-cause analysis.

Example Prompts

1. "Check if there are any active loops stuck in the needs-review state and give me a summary of the latest logs for the oldest one."
2. "I think the agent got confused by the project structure. Can you show me the diff for loop a3f2 so I can see what files it modified before the crash?"
3. "The primary loop is locked. Can you list the current worktrees, identify the stale processes, and prune anything that isn't actively running?"

Tips & Limitations

• Partial Matching: You don't need to type the full UUID for loops. Providing the last 4 characters (e.g., a3f2) is usually sufficient for most commands.
• Safety: Always attempt a graceful stop with ralph loops stop <id> before forcing a termination to ensure that handoff.md and tasks.jsonl files are flushed properly to disk.
• Context: Remember that primary loops operate in the root, while worktrees operate in isolated subdirectories; commands are context-aware, so ensure you are in the correct directory when managing specific agent instances.