Aiwg ralph-external

Crash-resilient external loop with state persistence and CI/CD integration

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/agentic/code/addons/agent-loop/skills/ralph-external" ~/.claude/skills/jmagly-aiwg-ralph-external-541f63 && rm -rf "$T"

manifest: agentic/code/addons/agent-loop/skills/ralph-external/SKILL.md

source content

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.

/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

/ralph-external

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:

"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 (required)

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%"

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

Validate that
```
--completion
```
criteria are specified and verifiable
Check for an existing
```
.aiwg/ralph-external/
```
workspace; create if absent
Generate a unique
```
loop-id
```
(8-character hex) and create the loop state file at
```
.aiwg/ralph-external/loops/<loop-id>.json
```

Write the initial state:

{ objective, completionCriteria, maxIterations, timeout, provider, status: "pending", iteration: 0 }

If
```
--branch
```
is specified, create the git branch now
Invoke
```
tools/ralph-external/run.sh
```
with all parsed flags, passing the loop-id
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

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 iteration and learnings
On restart,
```
tools/ralph-external/run.sh
```
detects the incomplete state and resumes from the last checkpoint
Learnings from completed iterations are injected into the next iteration's prompt via the memory layer

State file schema (

.aiwg/ralph-external/loops/<id>.json

{
  "loopId": "abc123",
  "objective": "Fix all auth tests",
  "completionCriteria": "npm test passes with 0 failures",
  "maxIterations": 10,
  "timeout": 60,
  "provider": "claude",
  "status": "running",
  "iteration": 3,
  "startedAt": "2026-04-01T10:30:00Z",
  "lastCheckpoint": "2026-04-01T10:38:42Z",
  "logFile": ".aiwg/ralph-external/logs/abc123.log",
  "branch": null,
  "learnings": ["auth mocks must be initialized before describe block"]
}

CI/CD Integration

For use in pipelines, pass

--quiet

and read the exit code:

```
0
```
— loop completed successfully (completion criteria verified)
```
1
```
— loop failed (max iterations or timeout reached)
```
2
```
— configuration error (bad arguments)

GitHub Actions example:

- name: Auto-fix tests
  run: |
    aiwg ralph-external "Fix all failing unit tests" \
      --completion "npm test passes" \
      --max-iterations 5 \
      --timeout 30 \
      --quiet

Error Handling

Missing --completion:

Error: --completion is required for /ralph-external.

Provide a verifiable success criterion:
  /ralph-external "Fix tests" --completion "npm test passes"

External process launch failure:

Failed to launch external Al process.

Check:
1. tools/ralph-external/run.sh is executable
2. Node.js >= 18 is available
3. .aiwg/ directory is writable

Run with --verbose for diagnostics.

Loop already active for this objective:

An existing loop may be running for a similar objective.

Active loops:
  abc123 — Fix auth tests (running, iteration 3/10)

Options:
1. Attach to existing:  /ralph-attach --loop-id abc123
2. Start new anyway:    confirm and proceed
3. Abort existing:      /ralph-abort --loop-id abc123

Examples

Example 1: Fix failing tests

/ralph-external "Fix all failing tests in src/auth/" --completion "npm test -- --testPathPattern=auth passes"

Response: Starts external loop, prints loop ID, streams live output.

Example 2: Long-running migration with branch

/ralph-external "Migrate src/ to ESM" --completion "npx tsc --noEmit exits with code 0" --max-iterations 20 --timeout 120 --branch feat/esm-migration

Response: Creates branch

feat/esm-migration

, starts loop, streams output.

Example 3: CI/CD pipeline usage

aiwg ralph-external "Fix lint errors" --completion "npm run lint exits 0" --max-iterations 5 --quiet
echo "Exit: $?"

Response: Runs silently, exits 0 on success or 1 on failure.

Example 4: Alternative provider

/ralph-external "Refactor payment module" --completion "npm test passes" --provider codex --max-iterations 8

Response: Runs iterations using OpenAI Codex instead of Claude.

```
/ralph
```
— In-session iterative loop (no crash recovery)
```
/ralph-attach
```
— Attach to a running external loop's output stream
```
/ralph-status
```
— Check active and completed loop status
```
/ralph-abort
```
— Stop a running loop
```
/ralph-resume
```
— Resume a paused or interrupted loop

References

@$AIWG_ROOT/src/cli/handlers/ralph.ts — Al CLI handler
@$AIWG_ROOT/src/cli/handlers/ralph-launcher.ts — External loop launcher
@$AIWG_ROOT/tools/ralph-external/README.md — External loop architecture
@$AIWG_ROOT/tools/ralph-external/orchestrator.mjs — Loop orchestration engine
@$AIWG_ROOT/tools/ralph-external/state-manager.mjs — State persistence layer
@$AIWG_ROOT/tools/ralph-external/session-launcher.mjs — AI session launcher
@$AIWG_ROOT/agentic/code/addons/ralph/README.md — Al documentation