Example task prompt:
"Process all files in /Needs_Action.
When all items are processed and moved to /Done, output: <promise>TASK_COMPLETE</promise>"

Example: Start a loop watching for "TASK_20260223_inbox_sweep" in /Done
When the file appears in /Done, the loop exits naturally.

from ralph_loop import RalphLoop

loop = RalphLoop(vault_path="./vault")
state = loop.start(
    prompt="Process all pending items in /Needs_Action. "
           "For each item, create a plan and move to /Done. "
           "When ALL items are processed, output: <promise>TASK_COMPLETE</promise>",
    completion_promise="TASK_COMPLETE",
    max_iterations=10,
)
print(f"Loop started: {state.task_id}")

from ralph_loop import RalphLoop

loop = RalphLoop(vault_path="./vault")
state = loop.start(
    prompt="Generate this week's CEO briefing and save to vault/Briefings/. "
           "Move the trigger file to /Done when complete.",
    completion_file="TASK_briefing_trigger.md",
    max_iterations=5,
)

from ralph_loop import RalphLoop

loop = RalphLoop(vault_path="./vault")
active = loop.get_active_loops()
for state in active:
    print(f"Loop {state.task_id}: iteration {state.current_iteration}/{state.max_iterations}")

# In Claude Code settings (settings.json or CLAUDE.md):
# Add stop hook:
# python src/ralph_loop.py ./vault

/ralph-loop "Process all items in vault/Needs_Action in priority order (high → medium → low).
For each item:
1. Read the item's frontmatter
2. Create a Plan.md in vault/Plans/
3. If approval needed, create approval request in vault/Pending_Approval/
4. Otherwise, process and move to vault/Done/
When ALL items in vault/Needs_Action have been moved to vault/Done,
output: <promise>TASK_COMPLETE</promise>"
--max-iterations 15