# ralph-orchestrator

> Run Ralph orchestrator with Claude Code backend for autonomous task completion. Use when executing iterative AI agent workflows, automating multi-step coding tasks, or running Ralph in OpenClaw's non-interactive environment. Required for any Ralph orchestration tasks.

- Author: Mark Berjanskii
- Repository: mberjans/openclaw-skills
- Version: 20260209041332
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/mberjans/openclaw-skills
- Web: https://mule.run/skillshub/@@mberjans/openclaw-skills~ralph-orchestrator:20260209041332

---

---
name: ralph-orchestrator
description: Run Ralph orchestrator with Claude Code backend for autonomous task completion. Use when executing iterative AI agent workflows, automating multi-step coding tasks, or running Ralph in OpenClaw's non-interactive environment. Required for any Ralph orchestration tasks.
---

# Ralph Orchestrator

## Overview

Ralph is a hat-based orchestration framework that keeps AI agents in iterative loops until tasks complete. It uses Claude Code as the backend to plan, execute, and verify work automatically.

## When to Use

Use Ralph for:
- Multi-step coding tasks requiring iteration
- Autonomous task completion without manual intervention
- Complex workflows with planning, execution, and verification phases
- Tasks that benefit from persistent scratchpad and memory

## Quick Start

### 1. Initialize Project

```bash
ralph init --backend claude
```

Creates `ralph.yml` configuration.

### 2. Run with Prompt

**For OpenClaw (non-interactive), always use:**

```bash
TERM=dumb setsid ralph run -p "Your task" --autonomous </dev/null 2>&1
```

**With prompt file:**

```bash
TERM=dumb setsid ralph run -P PROMPT.md --autonomous </dev/null 2>&1
```

## Critical Requirements

Non-interactive environments (OpenClaw) **must** use:

| Component | Purpose |
|-----------|---------|
| `setsid` | Create new session, detach from parent |
| `</dev/null` | Provide empty stdin |
| `TERM=dumb` | Avoid TTY issues |
| `--autonomous` | Headless mode (no TUI) |

Without these, Ralph will hang indefinitely.

## Common Commands

| Command | Purpose |
|---------|---------|
| `ralph init --backend claude` | Initialize with Claude backend |
| `ralph run -p "task" --autonomous` | Run with inline prompt |
| `ralph run -P file.md --autonomous` | Run with prompt file |
| `ralph plan "feature"` | Interactive planning session |
| `ralph preflight` | Validate config |
| `ralph clean` | Remove .ralph/ artifacts |

## Configuration

**ralph.yml:**
```yaml
cli:
  backend: "claude"

event_loop:
  prompt_file: "PROMPT.md"
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 100
```

## Workflow

1. Ralph reads prompt/task
2. Creates plan in scratchpad
3. Breaks into subtasks
4. Executes via Claude Code
5. Verifies results
6. Iterates until LOOP_COMPLETE or max iterations

## Output

- `.ralph/agent/scratchpad.md` - Live progress tracking
- `.ralph/agent/handoff.md` - Completion summary
- Git commits - Auto-committed changes

## Resources

- **[ralph-usage-guide.md](references/ralph-usage-guide.md)** - Full documentation with examples and troubleshooting