Autonomous Loops

What Are Autonomous Loops?

An autonomous loop is Claude Code running a task without your input, finishing, and then picking up the next iteration automatically. You define the task, set the boundaries, and walk away. Claude Code keeps working until the job is done or you tell it to stop.

This is the most advanced pattern in the Claude Code toolkit. It's also the one that demands the most respect. Autonomous loops are powerful when bounded properly and dangerous when they're not.

The Core Pattern

The autonomous loop relies on three pieces:

1. A task template that defines what to do
2. A stop hook that re-feeds the task when Claude Code finishes a session
3. A safety mechanism to kill the loop when needed

Here's how the pieces fit together:

You start a session with a task template
  → Claude Code works on the task
  → Session ends (naturally or by token limit)
  → Stop hook detects the task file still exists
  → Stop hook starts a new session with the same task
  → Loop continues until task is complete or you intervene

Setting Up a Task Template

Task templates live in a dedicated directory. Each template is a markdown file with clear scope and exit conditions.

# Task: Fix Failing Tests

## Objective
Run the test suite and fix all failing tests until the suite is green.

## Boundaries
- Only modify test files and the source files they test
- Do not change any API contracts or public interfaces
- Do not modify configuration files
- Maximum 10 fix attempts per failing test before flagging for human review

## Process
1. Run `npm test` and capture output
2. Identify the first failing test
3. Read the test to understand intent
4. Read the implementation to find the bug
5. Fix the implementation (not the test, unless the test is wrong)
6. Re-run the test suite
7. Repeat until green or boundary hit

## Exit Conditions
- All tests pass: write a summary and delete this task file
- Hit 10 attempts on a single test: write a report and stop
- Encountered a boundary violation: stop and document why

Save this to ~/.claude/autonomous/tasks/fix-tests.md, then copy it to ~/.claude/autonomous/current-task.md to activate.

The Stop Hook

The stop hook is what creates the loop. When Claude Code finishes a session, the hook checks if current-task.md still exists. If it does, the hook re-launches Claude Code with the task.

#!/bin/bash
# ~/.claude/autonomous/stop-hook.sh

TASK_FILE="$HOME/.claude/autonomous/current-task.md"
STOP_FILE="$HOME/.claude/autonomous/STOP"

# Check for emergency stop
if [ -f "$STOP_FILE" ]; then
  echo "Emergency stop detected. Halting autonomous loop."
  rm -f "$TASK_FILE"
  exit 0
fi

# If task still exists, re-feed it
if [ -f "$TASK_FILE" ]; then
  echo "Task still active. Restarting session..."
  claude --task-file "$TASK_FILE"
fi

The Emergency Stop

This is non-negotiable. Every autonomous loop must have a kill switch.

# Stop the loop immediately
touch ~/.claude/autonomous/STOP

That single command halts the loop at the next session boundary. The stop hook checks for this file before restarting. No STOP file, the loop continues. STOP file exists, the loop dies.

Always test your emergency stop before running a long autonomous task. Start a loop, trigger the stop, and verify it actually halts.

Real-World Example: Autonomous PR Reviewer

# Task: Review Open Pull Requests

## Objective
Check for new open PRs every iteration. Review each unreviewed PR
and leave structured feedback.

## Boundaries
- Read-only on the repository (no pushes, no merges)
- Only review PRs opened in the last 24 hours
- Skip PRs already reviewed by this process
- Maximum 5 PRs per iteration

## Process
1. Run `gh pr list --state open --json number,title,createdAt`
2. Filter to PRs from the last 24 hours
3. For each unreviewed PR:
   a. Read the diff
   b. Check for common issues (security, performance, style)
   c. Write a review comment via `gh pr review`
4. Log reviewed PR numbers to avoid re-reviewing
5. Delete task file when no unreviewed PRs remain

When NOT to Use Autonomous Loops

External APIs with side effects. An autonomous loop that sends emails, creates Jira tickets, or posts to Slack can cause real damage if it misfires. Keep autonomous work read-heavy and write-light.

Production data. Never point an autonomous loop at a production database. One bad query in a loop that runs 50 iterations is 50 bad queries.

Unbounded scope. "Refactor the entire codebase" is not an autonomous task. "Fix the 12 ESLint errors in src/utils/" is.

Anything you haven't done manually first. If you haven't done the task by hand at least once, you don't know enough to write boundaries for it.

Tips

Start with read-only tasks. Your first autonomous loop should read code, analyze patterns, or generate reports. Nothing that writes to external systems.

Define exit conditions clearly. "Fix all tests" is bounded. "Improve code quality" is not. Every task needs a concrete finish line.

Check results before trusting. Review the output of your first 3-5 autonomous runs manually. Trust builds gradually.

Keep task files short. A good task template is 20-30 lines. If you need more, the task is too big. Break it into smaller autonomous steps.