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