ralph-loop
Run, monitor, resume, merge, and debug Ralph loops. Use this skill whenever the user asks to operate `ralph run` or `ralph loops`, inspect loop state, recover suspended loops, analyze diagnostics, or unblock merge queue issues.
- License 许可
- MIT
- 最近更新
- 2026-09-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ralph-loop
- description
- Run, monitor, resume, merge, and debug Ralph loops. Use this skill whenever the user asks to operate `ralph run` or `ralph loops`, inspect loop state, recover suspended loops, analyze diagnostics, or unblock merge queue issues.
02 资源文件 3
- 参考文档agents/openai.yaml239 B
- 参考文档references/commands.md1.3 KB
- 参考文档references/diagnostics.md1.9 KB
03 SKILL.md 正文
Ralph Loop
Use this skill to operate Ralph loops from the outside.
Use This Skill For
- Starting or continuing a Ralph run with the right
-cand-Hinputs - Inspecting loop state, worktrees, logs, history, and diffs
- Resuming a hook-suspended loop
- Merging or discarding completed worktree loops
- Debugging unexpected loop behavior with current diagnostics files
Workflow
- Start with
ralph loops listorralph loops list --jsonto establish the current state. - If the user wants execution, run
ralph run ...with the right core config and hats source. - If the loop is stuck or suspicious, inspect
logs,history, anddiffbefore changing state. - If the loop is suspended, read
.ralph/suspend-state.jsonand useralph loops resume <id>. - If a loop is queued or in
needs-review, inspect the diff first, then usemerge,process,retry, ordiscardas appropriate. - Use diagnostics when you need detailed evidence about hats, events, tool calls, parse errors, or performance.
Guardrails
- Prefer the CLI over direct edits to
.ralphstate files. - Treat tasks and memories as the canonical runtime systems; do not center scratchpad as the primary state model.
- Inspect diffs before merging.
- Only remove lock or queue artifacts when the underlying process is confirmed dead.
- Manual edits under
.ralph/are last-resort recovery steps and should be called out explicitly when used.
Read These References When Needed
- For command recipes and operator flows:
references/commands.md - For diagnostics files and suspend-state details:
references/diagnostics.md
04 同仓库更多 Skills
ralph-hats
Create, inspect, validate, explain, and improve Ralph hat collections. Use this skill whenever the user asks to make or refine a `.ralph/hats/*.yml` workflow, debug hat routing, explain event topology, or tune a multi-hat Ralph run.
ralph-docs
Introspect, explain, and improve ralph-jev using the documentation shipped in its repository. Use this skill whenever the user asks questions about Ralph's behavior, wants to understand how a Ralph internal works (event loop, completion gate, judge evidence, Jev hooks, parallel loops, configuration), debug an unfamiliar failure mode, or propose a code change to the ralph-jev repo. The skill teaches the agent to answer from the repo's docs and source before guessing, and to scope improvements through the documented architecture rather than the local checkout alone.
complex-test-skill
A directory-style test skill for smoke testing
tui-validate
Validates Terminal User Interface (TUI) output using freeze for screenshot capture and LLM-as-judge for semantic validation. Supports both visual (PNG/SVG) and text-based validation modes.
tui-debug-in-pane
Use when you need to reproduce or debug TUI rendering issues (garbled output, broken streaming, layout corruption) by running ralph in a tmux split pane and capturing live output.
tmux-terminal
Interactive terminal control via tmux for TUI apps, prompts, and long-running CLI workflows.