🔁 opencode-ralph-loop

English · 简体中文

A lightweight OpenCode plugin that implements the Ralph Loop pattern — a self-referential completion loop that keeps your AI agent working until a task is truly 100% done.

Also includes ebuilder agent support — switch to the ebuilder agent and auto-continuation activates automatically, no commands needed.

Inspired by the Ralph Loop and Sisyphus features in oh-my-opencode, reimplemented as a standalone plugin with zero dependencies.

🔄 How It Works

Ralph Loop (command-based)

User issues /ralph-loop or /ulw-loop command
  → Plugin writes loop state to .ralph-loop.state.json
  → Agent executes the task
  → session.idle event fires
  → Plugin checks Agent output for <promise>DONE</promise>
    → ✅ Found: Loop complete! Toast notification.
    → ❌ Not found: Inject continuation prompt → Agent continues
    → Repeat until completion or max iterations

ebuilder Agent (automatic)

User switches to ebuilder agent in TUI
  → chat.message hook detects agent === "ebuilder"
  → Plugin writes loop state to .ebuilder.state.json
  → Agent executes the task
  → session.idle event fires
  → Plugin checks Agent output for <promise>DONE</promise>
    → ✅ Found: Loop complete!
    → ❌ Not found: Inject continuation prompt → Agent continues
  → User switches back to build/plan → ebuilder state auto-cleared → Loop stops

✨ Features

| Feature | Description | |---------|-------------| | 🔁 /ralph-loop | Standard completion loop (max 100 iterations) | | 🚀 /ulw-loop | Ultrawork mode with maximum intensity (max 500 iterations) | | 🛑 /cancel-ralph | Cancel an active loop (works for both modes) | | 🤖 ebuilder agent | Auto-continuation when switched to ebuilder agent (max 500 iterations) | | 🎯 Completion promise detection | Scans Agent output for <promise>DONE</promise> | | 🔔 Toast notifications | Real-time iteration and completion updates | | 🛡️ In-flight protection | Prevents duplicate idle event handling | | ⚙️ Custom parameters | --max-iterations=N and --completion-promise=TEXT |

📦 安装

方式一：npm 包安装（推荐）

npm install -g opencode-ralph-loop-support

或在项目 opencode.json 的 plugin 数组中加入 opencode-ralph-loop-support（OpenCode 会自动安装）：

{
  "plugin": ["opencode-ralph-loop-support"]
}

方式二：GitHub Release 资产安装（无需 npm 登录）

每次发布都会同时上传一个 tarball 到 GitHub Releases，可直接从 URL 安装，不依赖 npm 账号/token：

npm install https://github.com/FountainChan/opencode-ralph-loop/releases/download/v1.0.2/opencode-ralph-loop-support-1.0.2.tar.gz

将 URL 中的版本号 v1.0.2 替换为最新发布版本即可。

方式三：本地路径安装（推荐，开发用）

cd ~/.cache/opencode
npm install /path/to/opencode-ralph-loop-support

💡 这会创建符号链接，修改源码后无需重新安装，改动实时生效。

方式四：GitHub 仓库安装

cd ~/.cache/opencode
npm install FountainChan/opencode-ralph-loop

方式五：直接文件路径（备选）

如果 npm 方式有问题，可直接在 opencode.json 的 plugin 字段引用 JS 文件路径：

{
  "plugin": [
    "file:///path/to/ralph-loop/src/index.js"
  ]
}

配置

在 ~/.config/opencode/opencode.json 中添加插件：

{
  "plugin": ["opencode-ralph-loop-support"]
}

如果需要使用 ebuilder agent（自动续写），额外添加 agent 配置：

{
  "agent": {
    "ebuilder": {
      "mode": "primary",
      "description": "Autonomous agent with auto-continuation.",
      "prompt": "You are ebuilder..."
    }
  }
}

🗂️ 项目结构

opencode-ralph-loop/
├── src/
│   └── index.js        # 插件入口
├── scripts/
│   └── cleanup.py      # 清理脚本（卸载前执行）
├── package.json
├── README.md
└── .gitignore

🧹 卸载

在删除插件前，执行清理脚本以移除残留的命令条目：

# 1. 预览要清理的内容
python scripts/cleanup.py --source ralph-loop --dry-run

# 2. 执行清理
python scripts/cleanup.py --source ralph-loop

# 3. 卸载 npm 包
cd ~/.cache/opencode
npm uninstall opencode-ralph-loop-support

# 4. 从 opencode.json 的 plugin 数组中移除 "opencode-ralph-loop-support"

💡 --dry-run 可以先预览效果，确认无误后再实际执行。

🎮 Usage

🤖 ebuilder Agent (recommended for long tasks)

1. Switch to the ebuilder agent in the TUI (Tab key or agent selector)
2. Type your task normally
3. The agent will work continuously without stopping
4. Switch back to build to stop auto-continuation

🔁 Ralph Loop Commands

# Start a standard loop
/ralph-loop "Refactor the auth module and ensure all tests pass"

# Start an ultrawork loop (maximum intensity)
/ulw-loop "Migrate all API clients to v2"

# With custom parameters
/ralph-loop "Build the dashboard" --max-iterations=50 --completion-promise=SHIPPED

# Cancel an active loop
/cancel-ralph

🏁 How the Agent Signals Completion

When the Agent has fully completed the task, it outputs:

<promise>DONE</promise>

The plugin detects this tag in the Agent's response and stops the loop. You can customize the promise text with --completion-promise.

⚙️ Configuration

No configuration file needed. Loop states are stored in .ralph-loop.state.json and .ebuilder.state.json in the project directory and automatically cleaned up when loops complete or are cancelled.

📊 Comparison with oh-my-opencode

| Feature | oh-my-opencode | opencode-ralph-loop | |---------|---------------|-------------------| | 📁 File count | ~25 TypeScript files | 1 JS file | | 📦 Dependencies | Full OmO plugin | Zero dependencies | | 👁️ Oracle verification | ✅ | ❌ | | 🔄 Session reset strategy | ✅ | ❌ (continue only) | | 🔧 Session recovery | ✅ | ❌ | | 🛡️ Race condition mutex | ✅ (debounce) | ✅ (inFlight Set) | | 🔁 /ralph-loop | ✅ | ✅ | | 🚀 /ulw-loop | ✅ | ✅ | | 🛑 /cancel-ralph | ✅ | ✅ | | 🤖 ebuilder/Sisyphus agent | ✅ (Sisyphus) | ✅ (ebuilder) | | ⏩ Auto-continuation on agent switch | ✅ | ✅ | | 🔔 Toast notifications | ✅ | ✅ | | ⚙️ Custom max iterations | ✅ | ✅ | | 🎯 Custom completion promise | ✅ | ✅ |

📄 License

MIT