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.