ralph-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Wiggum - Long-Running Development Loops

Ralph Wiggum - 长期开发循环

Long-running iterative development loops with pacing control.

带有节奏控制的长期迭代开发循环工具。

When to Use

适用场景

Complex tasks requiring multiple iterations
Tasks with many discrete steps that build on each other
Work that benefits from periodic reflection

Do NOT use for simple one-shot tasks or quick fixes.

需多轮迭代的复杂任务
由多个相互依赖的离散步骤组成的任务
可从周期性复盘获益的工作

请勿用于简单的一次性任务或快速修复。

Agent Tool

Agent工具

Call

ralph_start

to begin a loop on yourself:

ralph_start({
  name: "loop-name",
  taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2",
  maxIterations: 50,        // Default: 50
  itemsPerIteration: 3,     // Optional: suggest N items per turn
  reflectEvery: 10,         // Optional: reflect every N iterations
  useSubagents: true,       // Optional: delegate each task to subagent
  subagentAgent: "default"  // Optional: subagent name (default: 'default')
})

调用

ralph_start

在自身启动循环：

ralph_start({
  name: "loop-name",
  taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2",
  maxIterations: 50,        // 默认值：50
  itemsPerIteration: 3,     // 可选：建议每轮处理N个事项
  reflectEvery: 10,         // 可选：每N轮进行一次复盘
  useSubagents: true,       // 可选：将每个任务委派给子Agent
  subagentAgent: "default"  // 可选：子Agent名称（默认值：'default')
})

Loop Behavior

循环行为

Task content is saved to
```
.ralph/<name>.md
```
Each iteration: work on task, update file
Call
```
ralph_done
```
tool to proceed to next iteration
When complete: output
```
<promise>COMPLETE</promise>
```
Loop ends on completion or max iterations (default 50)

任务内容将保存至
```
.ralph/<name>.md
```
每轮迭代：处理任务，更新文件
调用
```
ralph_done
```
工具进入下一轮迭代
完成时：输出
```
<promise>COMPLETE</promise>
```
循环在任务完成或达到最大迭代次数（默认50次）时结束

User Commands

用户命令

```
/ralph start <name|path>
```
- Start a new loop
```
/ralph resume <name>
```
- Resume loop
```
/ralph stop
```
- Pause loop (when agent idle)
```
/ralph-stop
```
- Stop active loop (idle only)
```
/ralph status
```
- Show loops
```
/ralph list --archived
```
- Show archived loops
```
/ralph archive <name>
```
- Move loop to archive
```
/ralph clean [--all]
```
- Clean completed loops
```
/ralph cancel <name>
```
- Delete loop
```
/ralph nuke [--yes]
```
- Delete all .ralph data

During streaming: press ESC to interrupt, send a normal message to resume, and run

/ralph-stop

when idle to end the loop.

```
/ralph start <name|path>
```
- 启动新循环
```
/ralph resume <name>
```
- 恢复循环
```
/ralph stop
```
- 暂停循环（仅当Agent处于空闲状态时）
```
/ralph-stop
```
- 停止活跃循环（仅空闲状态）
```
/ralph status
```
- 查看循环状态
```
/ralph list --archived
```
- 查看已归档循环
```
/ralph archive <name>
```
- 将循环归档
```
/ralph clean [--all]
```
- 清理已完成的循环
```
/ralph cancel <name>
```
- 删除循环
```
/ralph nuke [--yes]
```
- 删除所有.ralph数据

在流处理过程中：按ESC键中断，发送普通消息恢复，空闲时运行

/ralph-stop

结束循环。

Task File Format

任务文件格式

markdown

undefined

markdown

undefined

Task Title

任务标题

Brief description.

简要描述。

Goals

目标

Goal 1
Goal 2

目标1
目标2

Checklist

检查清单

Notes

备注

(Update with progress, decisions, blockers)

undefined

（更新进度、决策、障碍）

undefined

Subagent Mode

子Agent模式

Delegate each checklist task to a separate subagent thread:

bash

/ralph start my-tasks --use-subagents --subagent-agent default

How it works:

Extracts uncompleted checklist items (
```
- [ ] Task
```
)
Each task is delegated to a fresh subagent thread (1 task = 1 subagent)
Subagent completes task and marks it done (
```
- [x] Task
```
)
Main loop orchestrates and tracks progress
Automatic retry logic for failures (2 attempts)

Benefits:

Fresh context per task (no pollution)
Isolated execution (failures don't cascade)
Clear task tracking and progress reporting
Suitable for independent, discrete tasks

When to use:

Tasks are independent (no shared state)
Each task is substantial enough for separate execution
You want clean separation between tasks
Task list is well-defined upfront

将每个检查清单任务委派至独立的子Agent线程：

bash

/ralph start my-tasks --use-subagents --subagent-agent default

工作原理：

提取未完成的检查清单项（
```
- [ ] Task
```
）
每个任务被委派至全新的子Agent线程（1个任务对应1个子Agent）
子Agent完成任务并标记为已完成（
```
- [x] Task
```
）
主循环负责编排和跟踪进度
内置失败自动重试逻辑（最多2次尝试）

优势：

每个任务拥有独立上下文（无上下文污染）
执行过程隔离（单个任务失败不会影响全局）
任务跟踪和进度报告清晰明了
适用于独立的离散任务

适用场景：

任务相互独立（无共享状态）
每个任务的工作量足以单独执行
希望任务间保持清晰的边界
任务清单在前期已明确定义

Best Practices

最佳实践

Clear checklist: Break work into discrete items
Update as you go: Mark items complete, add notes
Reflect when stuck: Use reflection to reassess approach (normal mode)
Complete properly: Only output completion marker when truly done
Subagent mode: Use for independent tasks with clear boundaries

清晰的检查清单：将工作拆分为离散的事项
实时更新：标记已完成事项，添加备注
卡顿时复盘：遇到瓶颈时通过复盘重新评估方案（普通模式）
规范完成流程：仅在真正完成时输出完成标记
子Agent模式：用于边界清晰的独立任务