Operate and supervise Ralph loops through the production `ralph-mum` control plane. Use when a user needs to register or unregister a repo, launch or use `RalphMumUI`, inspect managed project state, read loop logs, troubleshoot supervisor issues, or start, stop, and restart a managed Ralph loop through the shipped app and CLI rather than ad-hoc dev scaffolding.
Use this guide when you want to operate Ralph loops through the production ralph-mum control plane.
This skill is for:
RalphMumUI app as the live supervisorralph-mum CLI for registration, inspection, and control.ralph/ state expected by the appThis skill is not the place to explain the Ralph loop pattern in general. For loop philosophy, pass shape, and durable repo artifacts, use the ralph-loop skill. This skill focuses on the production operator workflow.
ralph-mum is a small control plane for Ralph-managed repositories:
RalphMumUI is the primary app and supervisorralph-mum is the operator CLI.ralph/~/.config/ralph/projects.jsonMutating commands go through the app control plane:
registerunregisterstartstoprestartIf RalphMumUI is not running, those commands may fail because the control plane is unavailable.
Read-only commands work directly from the CLI:
liststatusinspectlogCurrent CLI surface:
ralph-mum register <path>
ralph-mum unregister <path-or-id>
ralph-mum list
ralph-mum status [<path-or-id>] [--json]
ralph-mum inspect <path-or-id> [--json]
ralph-mum log <path-or-id>
ralph-mum start <path-or-id>
ralph-mum stop <path-or-id>
ralph-mum restart <path-or-id>
The operator-facing minimum is:
AGENT.mdfix_plan.mdprompt.txtspec.md or specs/.ralph/config.json.ralph/state.jsonDo not hand-edit .ralph/state.json unless you are intentionally repairing a broken loop.
For how to structure the Ralph loop itself, what should be in the prompt, and how a bounded pass should behave, refer to ralph-loop.
.ralph/config.json shapeThe current production config is a v1 config with this shape:
{
"version": 1,
"prompt_file": "prompt.txt",
"poll_seconds": 5,
"worker": {
"kind": "codex",
"args": [
"exec",
"--model",
"gpt-5.4-mini",
"--dangerously-bypass-approvals-and-sandbox",
"--skip-git-repo-check"
],
"prompt_mode": "file"
}
}
The app launches the worker directly from this config and passes prompt.txt to the worker. No repo-local .ralph/run-worker.sh wrapper is required.
Current validator constraints:
version must be 1worker.kind must be codexworker.prompt_mode must be fileprompt_file must not be blankworker.args must not be emptyprompt.txtUse a repo-root prompt.txt as the bounded-pass prompt. A minimal starting point is:
You are working inside this repository in a supervised Ralph loop.
Read `AGENT.md`, `fix_plan.md`, and `spec.md` or `specs/` first.
Do one concrete, bounded unit of work that moves the project forward.
Prefer small, verifiable changes over broad refactors.
Update durable repo memory when needed.
Run relevant validation for the change when feasible.
At the very end, print exactly one final line in this format:
WATCHDOG_STATUS: continue
Use one of these final statuses:
- WATCHDOG_STATUS: continue
- WATCHDOG_STATUS: complete
- WATCHDOG_STATUS: blocked
- WATCHDOG_STATUS: unsafe
Adjust the body of the prompt for the repo, but keep the final status contract intact.
Make sure the target repo has:
AGENT.mdfix_plan.mdprompt.txtspec.md or specs/.ralph/config.json.ralph/state.jsonIf those files do not exist yet, create them first.
ralph-mum register /absolute/path/to/repo
ralph-mum list
ralph-mum status --json
ralph-mum start /absolute/path/to/repo
Use either the repo path or the registered project id in later commands.
List projects:
ralph-mum list
Check status:
ralph-mum status
ralph-mum status /path/to/repo --json
Inspect one project:
ralph-mum inspect /path/to/repo
ralph-mum inspect /path/to/repo --json
Read the current log:
ralph-mum log /path/to/repo
Control the loop:
ralph-mum start /path/to/repo
ralph-mum stop /path/to/repo
ralph-mum restart /path/to/repo
Unregister a project:
ralph-mum unregister /path/to/repo
The current system can surface statuses like:
IdleStartingRunningWaiting for next passCompletedBlockedUnsafeStopped by userWorker errorSupervision stoppedCodex missingInterpretation:
Starting / Running: an active worker or supervision cycle is liveWaiting for next pass: the last pass requested continuationSupervision stopped: the app control plane or supervisor died or stoppedCodex missing: the worker PID is gone while the loop expected it to still be aliveWorker error: the worker failed or exited without a usable terminal contractRalphMumUI is unavailableMeaning:
Fix:
RalphMumUIMeaning:
.ralph/config.json is absent or invalidFix:
Meaning:
prompt_file is missing or blank in .ralph/config.jsonFix:
.ralph/config.json at prompt.txtprompt.txtMeaning:
WATCHDOG_STATUS: lineFix:
ralph-loop for the expected bounded-pass behaviorUse ralph-mum when you want:
Prefer the production app flow over repo-specific dev scaffolding unless you are actively developing ralph-mum itself.
Think of ralph-mum as the operator layer:
ralph-loop defines how the Ralph loop should behaveRalphMumUI supervises the reporalph-mum lets you inspect and control itThat split keeps setup and operations in one place, and keeps the Ralph loop guidance in the Ralph skill instead of duplicating it here.