shenxingy/iloop

iloop — In-Session Iterative Loop

Runs Claude in a self-contained loop within the current session — no background processes, no worktrees. Each iteration, Claude reads the last output, checks progress, makes changes, and verifies. The loop continues until the task is done or max iterations is reached.

How it works

User: /iloop "Fix all failing tests"
          ↓
Claude starts → works on task → tries to exit
          ↓
Stop hook detects .claude/iloop.local.md
          ↓
Feeds task prompt back → Claude continues
          ↓
Repeat until: <promise>DONE</promise> | <loop-abort> | max iterations

This is different from /loop (which uses background workers + worktrees). Use /iloop when:

• You want to stay in the current session and watch progress
• The task needs iterative self-correction within one context
• You want Claude to autonomously debug/fix until passing

Usage

/iloop "Fix all failing pytest tests"
/iloop "Implement the auth feature" --max-iterations 25
/iloop "Get CI green" --completion-promise "ALL TESTS PASSING" --max-iterations 30

Signals (output anywhere in response to control the loop)

| Signal | Effect | |--------|--------| | <loop-abort>reason</loop-abort> | Terminate immediately (e.g. impossible task, needs human decision) | | <loop-pause>what needed</loop-pause> | Pause — state saved, resume by reopening session | | <promise>TEXT</promise> | Signal completion (only when --completion-promise set and genuinely true) |

Startup

When /iloop is invoked:

Step 1: Run the setup script:

bash ~/.claude/scripts/setup-iloop.sh "$ARGUMENTS" --max-iterations 20 --completion-promise "LOOP_DONE"

Adjust --max-iterations and --completion-promise based on the task:

• Simple fix: 10-15 iterations
• Feature build: 25-30 iterations
• Open-ended improvement: omit --completion-promise, use --max-iterations

Step 2: Tell the user:

▸ iloop started — iterating until done (max 20 iterations)
▸ Cancel: rm .claude/iloop.local.md
▸ Monitor: head -8 .claude/iloop.local.md

Step 3: Begin working on the task immediately. Per-iteration protocol:

1. Read git log and key files to understand what was done last iteration
2. Run verification (tests / build / lint) to check current state
3. Make focused progress — fix one thing at a time, not multiple things
4. Run verification again after changes — evidence required before marking done
5. Scan for related issues (fix A → check B and C)
6. Only output <promise>LOOP_DONE</promise> when ALL criteria are genuinely met

Cancelling

rm .claude/iloop.local.md    # Immediate cancel

Or output <loop-abort>reason</loop-abort> from within the session.

Difference from /loop

| | /loop | /iloop | |--|---------|----------| | Execution | Background process, parallel workers | Current session, sequential | | Worktrees | Yes, isolated per worker | No, works on main tree | | Visibility | Progress via --status | Real-time in session | | Use case | Large parallel improvements | Focused iterative fixing | | Context | Each worker starts fresh | Same context across iterations |