Autonomous Loops

What if you just walked away?

Here's something I've actually done. Friday evening, 7 tests failing, tired. I wrote a task template, set up a stop hook, and went to sleep. Saturday morning: green build, summary in the log.

That's an autonomous loop. Claude Code runs a task, the session ends, and a stop hook restarts it with the same task file. It keeps going until the job is done or you tell it to stop.

Long story short: this is the most powerful pattern in the Claude Code toolkit. It's also the one that demands the most respect. Bounded properly, it's magic. Unbounded, it will wreck your codebase at 2am while you sleep peacefully.

How it works (three pieces)

The loop itself is dead simple. Three things make it run:

1. A task template that defines the objective and hard limits
2. A stop hook that re-feeds the task when a session ends
3. A kill switch to stop everything immediately when needed

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

Writing a task template

Task templates are markdown files. The discipline isn't in the prose, it's in the exit conditions. If you write vague boundaries, you'll get vague behavior at 4am.

# 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 (what creates the loop)

When Claude Code finishes a session, this hook checks if current-task.md still exists. If it does, loop continues.

#!/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 kill switch (non-negotiable)

Every autonomous loop needs a way to die. This is not optional.

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

One command. The stop hook checks for this file before restarting. No file, loop continues. File exists, loop dies.

Always test your kill switch before running a long task. Start a loop, trigger the stop, verify it halts. Do this first. Not after you've let it run for 6 hours and it's rewritten your public API.

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 this

Some things should never run autonomously. Here's the deal.

External APIs with side effects. A loop that sends emails or posts to Slack causes real damage if it misfires 20 times. Keep autonomous work read-heavy and write-light.

Production data. One bad query in a loop that runs 50 iterations is 50 bad queries. Don't.

Unbounded scope. "Refactor the entire codebase" is not an autonomous task. "Fix the 12 ESLint errors in src/utils/" is. The difference is a concrete finish line.

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. Period. This rule has saved me multiple times.

Getting started safely

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.

Review your first 3-5 runs manually. Trust builds gradually. Don't set-and-forget until you've verified the output a few times.

Keep task files short. 20-30 lines is ideal. If you need more, the task is probably too big. Break it into smaller loops.