jmagly/ralph-attach

Al Attach

Attach to a running external agent loop and tail its output log in real time. Press Ctrl+C to detach without interrupting the loop.

Natural Language Triggers

Users may say:

• "ralph attach"
• "attach to ralph"
• "follow ralph"
• "watch ralph output"
• "tail the agent loop"
• "stream ralph progress"

Parameters

--loop-id (optional)

The ID of the loop to attach to. If omitted, attaches to the most recently started active loop.

/ralph-attach --loop-id abc123

When multiple loops are active, you must specify --loop-id. Run /ralph-status first to list active loop IDs.

Behavior

When triggered:

1. Read .aiwg/ralph-external/loops/ to find active loop state files
2. If --loop-id is not provided, select the loop with the most recent startedAt timestamp that has status: "running"
3. If no active loop is found, report clearly and exit
4. If multiple loops are active and no --loop-id is given, list them and prompt the user to specify
5. Resolve the loop's logFile path from its state JSON (typically .aiwg/ralph-external/logs/<loop-id>.log)
6. Begin reading the log file from the current end, streaming new lines as they are appended
7. Display each new line to the user as it arrives, prefixed with a timestamp
8. Continue until the user presses Ctrl+C or the loop reaches a terminal state (succeeded, failed, aborted)
9. On loop completion, print a final status banner and exit cleanly

Output format while tailing:

[10:42:01] Agent loop abc123 — ACTIVE (iteration 3/10)
[10:42:01] Running verification: npm test
[10:42:03] PASS src/auth/auth.test.ts
[10:42:03] Tests: 12 passed, 0 failed
[10:42:04] Iteration 3: VERIFIED — criteria met
[10:42:04] Agent loop: SUCCESS

On loop completion:

═══════════════════════════════════════════
Agent Loop Completed: SUCCESS
Loop ID: abc123
Iterations: 3
Duration: 4m 12s
Report: .aiwg/ralph-external/reports/abc123.md
═══════════════════════════════════════════

Detached from loop abc123.

Error Handling

No active loops:

No active agent loops found.

Start one with:
  aiwg ralph "your task" --completion "criteria"

Or check completed loops with:
  /ralph-status --all

Loop ID not found:

Loop 'xyz999' not found in .aiwg/ralph-external/loops/.

Active loops:
  abc123 — Fix auth tests (running, iteration 2/10)
  def456 — Migrate to ESM (running, iteration 5/20)

Attach with: /ralph-attach --loop-id abc123

Log file missing or unreadable:

Cannot read log for loop abc123.

Expected: .aiwg/ralph-external/logs/abc123.log
Check that the loop process is still running and has write access to the log directory.

Multiple loops active (no --loop-id):

Multiple active agent loops. Specify which to attach to:

  abc123 — Fix auth tests (running, iteration 2/10, started 10:38)
  def456 — Migrate to ESM (running, iteration 5/20, started 09:15)

Usage: /ralph-attach --loop-id <id>

State File Location

• Loop states: .aiwg/ralph-external/loops/<loop-id>.json
• Loop logs: .aiwg/ralph-external/logs/<loop-id>.log
• Reports: .aiwg/ralph-external/reports/<loop-id>.md

Examples

Example 1: Attach to the only active loop

/ralph-attach

Response: Streams live output from the single running agent loop.

Example 2: Attach to a specific loop by ID

/ralph-attach --loop-id abc123

Response: Streams output only from loop abc123.

Example 3: Detach without stopping

Press Ctrl+C while attached. Response: Returns to normal prompt; the agent loop continues running unaffected.

Related

• /ralph-status — Check loop IDs and current iteration progress
• /ralph-abort — Stop a loop entirely
• /ralph-resume — Resume a paused loop
• /ralph-external — Start a new crash-resilient external loop

References

• @$AIWG_ROOT/src/cli/handlers/ralph.ts — Al handler (attachToLoopOutput)
• @$AIWG_ROOT/src/cli/handlers/ralph-launcher.ts — Loop launcher and state management
• @$AIWG_ROOT/agentic/code/addons/ralph/README.md — Al documentation
• @$AIWG_ROOT/tools/ralph-external/README.md — External loop architecture