ULC Loop

Start an autonomous improvement loop powered by Ralph Wiggum.

Setup

Parse arguments from: $ARGUMENTS

Defaults:

• --budget: 5 (USD)
• --max-iterations: 20

Workflow

Step 1: Pre-flight Checks

1. Verify Ralph Wiggum plugin is installed:

   ls .Codex/plugins/cache/Codex-plugins/ralph-wiggum/ 2>/dev/null || echo "NOT INSTALLED"

If not installed, tell the user to run: Codex plugin install ralph-wiggum@Codex-plugins

1. Check for existing Ralph loop:

   cat .Codex/ralph-loop.local.md 2>/dev/null && echo "ACTIVE" || echo "INACTIVE"

If ACTIVE, warn: "A Ralph loop is already running. Run /cancel-ralph first."

1. Check git state is clean:

   git status --porcelain

If dirty, warn and suggest committing first.

Step 2: Read the ULC Prompt

Read the ULC decision procedure from .Codex/skills/ulc-loop/ulc-prompt.md.

Step 3: Initialize ULC State

Create the initial ULC state file if it doesn't exist:

cat > .Codex/ulc-state.local.json << 'EOF'
{
  "iteration": 0,
  "cumulative_cost_usd": 0,
  "budget_usd": <BUDGET>,
  "actions": [],
  "exploration_misses": 0,
  "started_at": "<ISO timestamp>"
}
EOF

Replace <BUDGET> with the parsed budget value.

Step 4: Create Ralph State File

Write .Codex/ralph-loop.local.md with YAML frontmatter and the ULC prompt as the body:

---
active: true
iteration: 1
max_iterations: <MAX_ITERATIONS>
completion_promise: "BUDGET EXHAUSTED OR ALL WORK COMPLETE"
started_at: "<ISO timestamp>"
---

<contents of ulc-prompt.md>

Step 5: Confirm and Start

Output:

ULC Loop activated via Ralph Wiggum.

Budget: $<budget> USD
Max iterations: <max_iterations>
Completion promise: "BUDGET EXHAUSTED OR ALL WORK COMPLETE"

The loop will:
1. Check backlog for ready work
2. Dispatch sub-agents for substantial tasks
3. Explore via QD when backlog is empty
4. Stop when budget is exhausted or all work is complete

State file: .Codex/ulc-state.local.json
Ralph state: .Codex/ralph-loop.local.md

Starting first OODA cycle...

Then immediately begin executing the ULC prompt — perform the first OODA cycle (Observe → Orient → Decide → Act).

Notes

• The ULC prompt is re-fed by Ralph's stop hook on each iteration
• Inter-iteration continuity is via .Codex/ulc-state.local.json and git
• Sub-agents are dispatched via Task tool with subagent_type: "general-purpose"
• Cost tracking is approximate — the agent estimates based on model and turns
• The loop does NOT push to remote — human reviews and pushes