Ralph Mum

If RalphMumUI is not running, those commands may fail because the control plane is unavailable.

Read-only commands work directly from the CLI:

• list
• status
• inspect
• log

CLI commands

Current 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>

What a managed repo needs

The operator-facing minimum is:

• AGENT.md
• fix_plan.md
• prompt.txt
• spec.md or specs/
• .ralph/config.json
• .ralph/state.json

Do 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.

Required .ralph/config.json shape

The 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 1
• worker.kind must be codex
• worker.prompt_mode must be file
• prompt_file must not be blank
• the referenced prompt file must exist
• worker.args must not be empty

Basic prompt.txt

Use 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.

Production setup flow

1. Prepare the repo artifacts

Make sure the target repo has:

• AGENT.md
• fix_plan.md
• prompt.txt
• spec.md or specs/
• .ralph/config.json
• .ralph/state.json

If those files do not exist yet, create them first.

2. Register the repo

ralph-mum register /absolute/path/to/repo

3. Inspect the registry

ralph-mum list
ralph-mum status --json

4. Start the loop through the app

ralph-mum start /absolute/path/to/repo

Use either the repo path or the registered project id in later commands.

Daily operator flow

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

Status model to expect

The current system can surface statuses like:

• Idle
• Starting
• Running
• Waiting for next pass
• Completed
• Blocked
• Unsafe
• Stopped by user
• Worker error
• Supervision stopped
• Codex missing

Interpretation:

• Starting / Running: an active worker or supervision cycle is live
• Waiting for next pass: the last pass requested continuation
• Supervision stopped: the app control plane or supervisor died or stopped
• Codex missing: the worker PID is gone while the loop expected it to still be alive
• Worker error: the worker failed or exited without a usable terminal contract

Common failure modes

RalphMumUI is unavailable

Meaning:

• you tried a mutating CLI command while the app was not running

Fix:

• launch RalphMumUI
• retry the command

Missing watchdog config

Meaning:

• .ralph/config.json is absent or invalid

Fix:

• create or repair the file
• ensure it matches the required v1 shape

Missing prompt

Meaning:

• prompt_file is missing or blank in .ralph/config.json
• the configured prompt file does not exist

Fix:

• point .ralph/config.json at prompt.txt
• create or repair prompt.txt

Worker exits without usable status

Meaning:

• the worker pass did not emit a valid final WATCHDOG_STATUS: line

Fix:

• fix the prompt and loop contract in the managed repo
• use ralph-loop for the expected bounded-pass behavior

Operational advice

Use ralph-mum when you want:

• one production control plane for multiple Ralph repos
• persisted status inspection across projects
• a menu bar supervisor plus CLI operator commands
• a cleaner path than ad-hoc dev watchdogs and local wrappers

Prefer the production app flow over repo-specific dev scaffolding unless you are actively developing ralph-mum itself.

Good usage pattern

Think of ralph-mum as the operator layer:

• repo files hold the loop's memory and steering
• ralph-loop defines how the Ralph loop should behave
• RalphMumUI supervises the repo
• ralph-mum lets you inspect and control it

That split keeps setup and operations in one place, and keeps the Ralph loop guidance in the Ralph skill instead of duplicating it here.