ralph loop

Engineering Community

Skill notes

Use This Skill For

Starting or continuing a Ralph run with the right -c and -H inputs 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 list or ralph loops list --json to 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, and diff

Guardrails

Prefer the CLI over direct edits to .ralph state 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

Read These References When Needed

For command recipes and operator flows: references/commands.md For diagnostics files and suspend-state details: references/diagnostics.md

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@mikeyobrien · no license declared
Token usage
Moderate
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file 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 `-c` and `-H` inputs
- 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

1. Start with `ralph loops list` or `ralph loops list --json` to establish the
   current state.
2. If the user wants execution, run `ralph run ...` with the right core config
   and hats source.
3. If the loop is stuck or suspicious, inspect `logs`, `history`, and `diff`
   before changing state.
4. If the loop is suspended, read `.ralph/suspend-state.json` and use
   `ralph loops resume <id>`.
5. If a loop is queued or in `needs-review`, inspect the diff first, then use
   `merge`, `process`, `retry`, or `discard` as appropriate.
6. Use diagnostics when you need detailed evidence about hats, events, tool
   calls, parse errors, or performance.

## Guardrails

- Prefer the CLI over direct edits to `.ralph` state 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`

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.