Worker Loop

---
description: Start a persistent worker loop (Ralph-style)
argument-hint: <agent> [--max-idle 10] | stop
---

# Worker Loop Command

Start a persistent worker loop for the specified agent. The worker will:
1. Check for assigned tasks
2. Work on tasks until complete
3. Loop back and check for more tasks
4. Only exit after N idle checks with no work found

## Activation Modes

Worker Loop can be activated in two ways:

### 1. Config-based (Recommended)

Enable during `forge init` or toggle anytime:

```bash
forge config worker-loop on     # Enable for all workers
forge config worker-loop off    # Disable
forge config worker-loop        # Check status

When enabled, ALL workers will automatically stay running and check for new tasks.

2. Runtime (Per-session)

Use this command for fine-grained control:

/worker-loop anvil              # Start Anvil in persistent loop
/worker-loop furnace --max-idle 20  # Custom idle limit
/worker-loop stop               # Stop the current loop

Arguments

• $1 - Agent name (anvil, furnace, crucible, etc.) or "stop"
• --max-idle N - Exit after N checks with no tasks (default: 10)

Implementation

Based on $ARGUMENTS:

If first argument is "stop"

Remove the worker loop state file and confirm:

rm -f "${CLAUDE_LOCAL_DIR:-$HOME/.claude}/forge-worker-loop.json"

Output: "Worker loop stopped."

Otherwise, start a loop

1. Resolve the agent name to canonical form
2. Create state file at ${CLAUDE_LOCAL_DIR}/forge-worker-loop.json:

{
  "agent": "<resolved-agent>",
  "max_idle_checks": 10,
  "idle_count": 0,
  "poll_interval": 5,
  "started_at": "<ISO timestamp>"
}

3. Load the agent's personality file
4. Start working with this system prompt addition:

You are in PERSISTENT WORKER MODE. After completing each task:
1. Check for more tasks assigned to you in tasks/pending/ and tasks/needs-changes/
2. If tasks found, immediately begin working
3. If no tasks, announce you are idle and waiting

Do NOT ask permission to continue - work autonomously until no tasks remain.

5. The stop hook (hooks/worker-loop.js) will intercept exit attempts and:
   • If tasks exist: feed prompt to continue working
   • If no tasks: increment idle counter
   • If max idle reached: allow exit

How It Works

The Worker Loop uses Claude Code's Stop Hook feature:

1. When a worker tries to exit, the hook script runs
2. It checks for pending tasks in tasks/pending/ and tasks/needs-changes/
3. If tasks found: blocks exit and feeds a prompt to continue working
4. If no tasks: allows exit (or waits, depending on config)

Benefits

• Workers stay active and pick up new tasks automatically
• No need to manually respawn workers
• Tasks can be added to pending/ and workers will find them
• Config-based mode requires zero per-session setup
• Configurable idle timeout prevents infinite waiting