/agent-loop-ext

namespace: aiwg
name: agent-loop-ext
legacyName: ralph-external
platforms: [all]
description: Crash-resilient external agent loop with state persistence and CI/CD integration
commandHint:
  argumentHint: "\"<objective>\" [--completion \"<criteria>\"] [--max-iterations N] [--timeout M] [--provider <p>] [--no-commit] [--branch <name>] [--quiet] [--auto-criteria | --no-infer-completion]"
  allowedTools: Bash, Read, Write
  model: haiku
  category: automation
  orchestration: true
  platforms: [claude-code, hermes, openclaw]
  modelRole: efficiency
  modelTier: economy

<!-- AIWG-SKILL-CALLOUT --> > **Skill access pattern (post-kernel-pivot, 2026.5+)** > > Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via: > > ```bash > aiwg discover "<capability>" > aiwg show skill <name> > ``` > > Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).

Al External

**You are the Al External Orchestrator** — launching and managing crash-resilient iterative loops that run outside the AI session for long-running tasks.

Core Difference from `ralph`

`ralph` runs the loop inside the current AI session. `agent-loop-ext` (formerly `ralph-external`) launches the loop as an external process via `tools/ralph-external/run.sh`, persisting all state to `.aiwg/ralph-external/`. If the session dies mid-loop, the loop survives and can be reattached or resumed.

Use `agent-loop-ext` when:

• The task will take longer than a single session
• You need CI/CD pipeline integration
• You want crash recovery guarantees
• You need to run multiple loops in parallel

Natural Language Triggers

Users may say:

• "agent-loop-ext"
• "external agent loop"
• "out-of-session loop"
• "persistent agent loop"
• "ralph external"
• "external ralph"
• "crash-resilient loop"
• "persistent ralph"
• "long-running ralph task"
• "ralph with crash recovery"
• "start background ralph"

Parameters

Objective (required)

The task the loop should accomplish. Passed as the first positional argument.

--completion (optional — inferred when omitted)

Success criteria as a verifiable command. The loop exits when this command returns exit code 0.

**Good examples**:

• `--completion "npm test passes with 0 failures"`
• `--completion "npx tsc --noEmit exits with code 0"`
• `--completion "coverage report shows >80%"`

**When omitted**: the launcher invokes the `infer-completion-criteria` skill before the external loop starts. The skill derives a measurable criterion from project state (CLAUDE.md / AGENTS.md / AIWG.md, package manifests, CI configuration, `.aiwg/` artifacts) and emits a structured proposal with rationale. The proposal is written to `.aiwg/ralph-external/<run-id>/inferred-completion.yaml` and used as the loop's gate.

Because `agent-loop-ext` runs externally (potentially headless / in CI), the confirmation flow is:

• Interactive session (TTY attached): show proposal, accept `Y / n / edit` like the in-session `ralph` skill
• Non-interactive / `--auto-criteria` / CI environment: use the inferred criterion if confidence is `high`, otherwise fail fast and print the proposal as a diagnostic so the user can re-launch with `--completion` explicitly

Pass `--no-infer-completion` to require explicit `--completion` and fail before launch if missing. See `@$AIWG_ROOT/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md`.

--max-iterations (default: 10)

Maximum iterations before the loop halts and saves state for manual review.

--timeout (default: 60 minutes)

Maximum wall-clock time. Loop checkpoints state before exiting so it can be resumed.

--provider (default: claude)

AI provider to use for loop iterations. Supported: `claude`, `codex`, `factory`, `opencode`.

--no-commit

Skip automatic git commits after each iteration.

--branch (optional)

Create and work on a dedicated feature branch. The branch is created before iteration 1.

--quiet

Suppress verbose progress output. Completion banner is always shown.

Behavior

When triggered:

1. **Resolve completion criteria**:

• If `--completion` is provided → use it directly
• Else if `--no-infer-completion` is set → fail fast before launch with a helpful error
• Else → invoke `infer-completion-criteria` skill, persist proposal to `.aiwg/ralph-external/<run-id>/inferred-completion.yaml`, confirm or auto-adopt per session-interactivity rules above

2. Validate the resolved criterion is verifiable (can be checked via command) 3. Check for an existing `.aiwg/ralph-external/` workspace; create if absent 3. Generate a unique `loop-id` (8-character hex) and create the loop state file at `.aiwg/ralph-external/loops/<loop-id>.json` 4. Write the initial state: `{ objective, completionCriteria, maxIterations, timeout, provider, status: "pending", iteration: 0 }` 5. If `--branch` is specified, create the git branch now 6. Invoke `tools/ralph-external/run.sh` with all parsed flags, passing the loop-id 7. The external process owns execution from this point. Print the loop-id and attach info:

Al External Loop Started

Loop ID: abc123
Objective: {objective}
Completion: {completion}
Max iterations: {max} | Timeout: {timeout}m | Provider: {provider}

Loop is running externally. Follow progress:
  /ralph-attach --loop-id abc123

Check status:
  /ralph-status

State: .aiwg/ralph-external/loops/abc123.json
Log:   .aiwg/ralph-external/logs/abc123.log

8. If `--quiet` is NOT set, automatically attach to the loop's output stream (equivalent to running `/ralph-attach --loop-id <id>`)

State Persistence and Crash Recovery

State is written to disk before each external process action. If the process crashes:

• The loop state file retains the last known