autonomous-loops

name: autonomous-loops description: "Patterns and architectures for autonomous Claude Code loops — from simple sequential pipelines to RFC-driven multi-agent DAG systems."

Autonomous Loops Skill

Patterns, architectures, and reference implementations for running Claude Code autonomously in loops. Covers everything from simple claude -p pipelines to full RFC-driven multi-agent DAG orchestration.

When to Use

• Setting up autonomous development workflows that run without human intervention
• Choosing the right loop architecture for your problem (simple vs complex)
• Building CI/CD-style continuous development pipelines
• Running parallel agents with merge coordination
• Implementing context persistence across loop iterations
• Adding quality gates and cleanup passes to autonomous workflows

Loop Pattern Spectrum

From simplest to most sophisticated:

⚠️ Anti-pattern: Loop of Death — An unconstrained autonomous loop that runs indefinitely, consuming tokens without progress. Always define a max iteration count, budget cap, or convergence condition. See Loop of Death below.

0. Native /loop & /bg Commands

The simplest starting point. Claude Code's built-in loop mechanisms handle most autonomous iteration needs without any external tooling.

/loop — Iterative Task Execution

/loop "Run tests, fix failures, repeat until all pass" --max-turns 10

The agent iterates autonomously until the condition is met or max turns reached.

/bg — Background Agents

/bg "Research all usages of deprecated API v2 and list them in a report"

Runs an agent in the background while you continue interactive work. Monitor with the Monitor tool.

When to Use Native vs Custom Loops

1. Sequential Pipeline (claude -p)

The simplest loop. Break daily development into a sequence of non-interactive claude -p calls. Each call is a focused step with a clear prompt.

Core Insight

If you can't figure out a loop like this, it means you can't even drive the LLM to fix your code in interactive mode.

The claude -p flag runs Claude Code non-interactively with a prompt, exits when done. Chain calls to build a pipeline:

#!/bin/bash
# daily-dev.sh — Sequential pipeline for a feature branch

set -e

# Step 1: Implement the feature
claude -p "Read the spec in docs/auth-spec.md. Implement OAuth2 login in src/auth/. Write tests first (TDD). Do NOT create any new documentation files."

# Step 2: De-sloppify (cleanup pass)
claude -p "Review all files changed by the previous commit. Remove any unnecessary type tests, overly defensive checks, or testing of language features (e.g., testing that TypeScript generics work). Keep real business logic tests. Run the test suite after cleanup."

# Step 3: Verify
claude -p "Run the full build, lint, type check, and test suite. Fix any failures. Do not add new features."

# Step 4: Commit
claude -p "Create a conventional commit for all staged changes. Use 'feat: add OAuth2 login flow' as the message."

Key Design Principles

1. Each step is isolated — A fresh context window per claude -p call means no context bleed between steps.
2. Order matters — Steps execute sequentially. Each builds on the filesystem state left by the previous.
3. Prefer cleanup passes over negative instructions — Instead of "don't test type systems," add a separate cleanup step (see De-Sloppify Pattern).
4. Exit codes propagate — set -e stops the pipeline on failure.

Variations

With model routing:

# Research with Opus (deep reasoning)
claude -p --model opus "Analyze the codebase architecture and write a plan for adding caching..."

# Implement with Sonnet (fast, capable)
claude -p "Implement the caching layer according to the plan in docs/caching-plan.md..."

# Review with Opus (thorough)
claude -p --model opus "Review all changes for security issues, race conditions, and edge cases..."

With environment context:

# Pass context via files, not prompt length
echo "Focus areas: auth module, API rate limiting" > .claude-context.md
claude -p "Read .claude-context.md for priorities. Work through them in order."
rm .claude-context.md

With --allowedTools restrictions:

# Read-only analysis pass
claude -p --allowedTools "Read,Grep,Glob" "Audit this codebase for security vulnerabilities..."

# Write-only implementation pass
claude -p --allowedTools "Read,Write,Edit,Bash" "Implement the fixes from security-audit.md..."

2. Infinite Agentic Loop

A two-prompt system that orchestrates parallel sub-agents for specification-driven generation. Developed by disler (credit: @disler).

Architecture: Two-Prompt System

PROMPT 1 (Orchestrator)              PROMPT 2 (Sub-Agents)
┌─────────────────────┐             ┌──────────────────────┐
│ Parse spec file      │             │ Receive full context  │
│ Scan output dir      │  deploys   │ Read assigned number  │
│ Plan iteration       │────────────│ Follow spec exactly   │
│ Assign creative dirs │  N agents  │ Generate unique output │
│ Manage waves         │             │ Save to output dir    │
└─────────────────────┘             └──────────────────────┘

The Pattern

1. Spec Analysis — Orchestrator reads a specification file (Markdown) defining what to generate
2. Directory Recon — Scans existing output to find the highest iteration number
3. Parallel Deployment — Launches N sub-agents, each with:
   • The full spec
   • A unique creative direction
   • A specific iteration number (no conflicts)
   • A snapshot of existing iterations (for uniqueness)
4. Wave Management — For infinite mode, deploys waves of 3-5 agents until context is exhausted

Implementation via Claude Code Commands

Create .claude/commands/infinite.md:

Parse the following arguments from $ARGUMENTS:
1. spec_file — path to the specification markdown
2. output_dir — where iterations are saved
3. count — integer 1-N or "infinite"

PHASE 1: Read and deeply understand the specification.
PHASE 2: List output_dir, find highest iteration number. Start at N+1.
PHASE 3: Plan creative directions — each agent gets a DIFFERENT theme/approach.
PHASE 4: Deploy sub-agents in parallel (Task tool). Each receives:
  - Full spec text
  - Current directory snapshot
  - Their assigned iteration number
  - Their unique creative direction
PHASE 5 (infinite mode): Loop in waves of 3-5 until context is low.

Invoke:

/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infinite

Batching Strategy

Key Insight: Uniqueness via Assignment

The orchestrator assigns each agent a specific creative direction and iteration number rather than relying on agents to self-differentiate. This prevents duplicate concepts across parallel agents.

3. Continuous Claude PR Loop

A production-grade shell script that runs Claude Code in a continuous loop, creating PRs, waiting for CI, and merging automatically. Created by AnandChowdhary (credit: @AnandChowdhary).

Core Loop

┌─────────────────────────────────────────────────────┐
│  CONTINUOUS CLAUDE ITERATION                        │
│                                                     │
│  1. Create branch (continuous-claude/iteration-N)   │
│  2. Run claude -p with enhanced prompt              │
│  3. (Optional) Reviewer pass — separate claude -p   │
│  4. Commit changes (claude generates message)       │
│  5. Push + create PR (gh pr create)                 │
│  6. Wait for CI checks (poll gh pr checks)          │
│  7. CI failure? → Auto-fix pass (claude -p)         │
│  8. Merge PR (squash/merge/rebase)                  │
│  9. Return to main → repeat                         │
│                                                     │
│  Limit by: --max-runs N | --max-cost $X             │
│            --max-duration 2h | completion signal     │
└─────────────────────────────────────────────────────┘

Installation

curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | bash

Usage

# Basic: 10 iterations
continuous-claude --prompt "Add unit tests for all untested functions" --max-runs 10

# Cost-limited
continuous-claude --prompt "Fix all linter errors" --max-cost 5.00

# Time-boxed
continuous-claude --prompt "Improve test coverage" --max-duration 8h

# With code review pass
continuous-claude \
  --prompt "Add authentication feature" \
  --max-runs 10 \
  --review-prompt "Run npm test && npm run lint, fix any failures"

# Parallel via worktrees
continuous-claude --prompt "Add tests" --max-runs 5 --worktree tests-worker &
continuous-claude --prompt "Refactor code" --max-runs 5 --worktree refactor-worker &
wait

Cross-Iteration Context: SHARED_TASK_NOTES.md

The critical innovation: a SHARED_TASK_NOTES.md file persists across iterations:

## Progress
- [x] Added tests for auth module (iteration 1)
- [x] Fixed edge case in token refresh (iteration 2)
- [ ] Still need: rate limiting tests, error boundary tests

## Next Steps
- Focus on rate limiting module next
- The mock setup in tests/helpers.ts can be reused

Claude reads this file at iteration start and updates it at iteration end. This bridges the context gap between independent claude -p invocations.

CI Failure Recovery

When PR checks fail, Continuous Claude automatically:

1. Fetches the failed run ID via gh run list
2. Spawns a new claude -p with CI fix context
3. Claude inspects logs via gh run view, fixes code, commits, pushes
4. Re-waits for checks (up to --ci-retry-max attempts)

Completion Signal

Claude can signal "I'm done" by outputting a magic phrase:

continuous-claude \
  --prompt "Fix all bugs in the issue tracker" \
  --completion-signal "CONTINUOUS_CLAUDE_PROJECT_COMPLETE" \
  --completion-threshold 3  # Stops after 3 consecutive signals

Three consecutive iterations signaling completion stops the loop, preventing wasted runs on finished work.

Key Configuration

4. The De-Sloppify Pattern

An add-on pattern for any loop. Add a dedicated cleanup/refactor step after each Implementer step.

The Problem

When you ask an LLM to implement with TDD, it takes "write tests" too literally:

• Tests that verify TypeScript's type system works (testing typeof x === 'string')
• Overly defensive runtime checks for things the type system already guarantees
• Tests for framework behavior rather than business logic
• Excessive error handling that obscures the actual code

Why a Separate Pass Works Better

Adding constraints like "avoid testing type systems" to the Implementer prompt has downstream effects:

• The model becomes hesitant about all testing
• It skips legitimate edge case tests
• Quality degrades unpredictably

Instead of constraining the Implementer, let it be thorough. Then add a focused cleanup agent:

# Step 1: Implement (let it be thorough)
claude -p "Implement the feature with full TDD. Be thorough with tests."

# Step 2: De-sloppify (separate context, focused cleanup)
claude -p "Review all changes in the working tree. Remove:
- Tests that verify language/framework behavior rather than business logic
- Redundant type checks that the type system already enforces
- Over-defensive error handling for impossible states
- Console.log statements
- Commented-out code

Keep all business logic tests. Run the test suite after cleanup to ensure nothing breaks."

In a Loop Context

for feature in "${features[@]}"; do
  # Implement
  claude -p "Implement $feature with TDD."

  # De-sloppify
  claude -p "Cleanup pass: review changes, remove test/code slop, run tests."

  # Verify
  claude -p "Run build + lint + tests. Fix any failures."

  # Commit
  claude -p "Commit with message: feat: add $feature"
done

Key Insight

Rather than adding negative instructions which have downstream quality effects, add a separate de-sloppify pass. Two focused agents outperform one constrained agent.

5. Ralphinho / RFC-Driven DAG Orchestration

The most sophisticated pattern. An RFC-driven, multi-agent pipeline that decomposes a spec into a dependency DAG, runs each unit through a tiered quality pipeline, and lands them via an agent-driven merge queue. Created by enitrat (credit: @enitrat).

Key concepts:

• RFC Decomposition — AI reads the spec and produces typed work units with dependency graphs
• Complexity Tiers — trivial/small/medium/large units get proportional pipeline depth
• Separate Context Windows — each stage (research, plan, implement, test, review) runs in its own agent to eliminate author bias
• Merge Queue with Eviction — failed merges capture conflict context for intelligent re-runs
• Worktree Isolation — each unit runs in an isolated worktree, shared across pipeline stages
• Resumable Workflows — full state persisted to SQLite; resume from any point

See references/ralphinho-dag-orchestration.md for the full architecture, data flow, and implementation details.

When to Use Ralphinho vs Simpler Patterns

Choosing the Right Pattern

Decision Matrix

Is the task a single focused change?
├─ Yes → Sequential Pipeline or interactive session
└─ No → Is there a written spec/RFC?
         ├─ Yes → Do you need parallel implementation?
         │        ├─ Yes → Ralphinho (DAG orchestration)
         │        └─ No → Continuous Claude (iterative PR loop)
         └─ No → Do you need many variations of the same thing?
                  ├─ Yes → Infinite Agentic Loop (spec-driven generation)
                  └─ No → Sequential Pipeline with de-sloppify

Combining Patterns

These patterns compose well:

1. Sequential Pipeline + De-Sloppify — The most common combination. Every implement step gets a cleanup pass.

2. Continuous Claude + De-Sloppify — Add --review-prompt with a de-sloppify directive to each iteration.

3. Ralphinho's tiered approach in simpler loops — Even in a sequential pipeline, route simple tasks to Haiku and complex tasks to Opus:

   # Simple formatting fix
   claude -p --model haiku "Fix the import ordering in src/utils.ts"
   
   # Complex architectural change
   claude -p --model opus "Refactor the auth module to use the strategy pattern"
   

Best Practices

1. Set exit conditions — Use max-runs, max-cost, max-duration, or a completion signal for every loop.

2. Bridge context between iterations — Each claude -p call starts fresh. Use SHARED_TASK_NOTES.md or filesystem state to carry knowledge forward.

3. Enrich retries with failure context — When an iteration fails, capture the error output and feed it to the next attempt.

4. Prefer cleanup passes over negative instructions — Instead of constraining the implementer ("avoid X"), add a separate de-sloppify pass that removes unwanted artifacts.

5. Separate concerns into distinct agent processes — For complex workflows, give each stage its own context window. Keep reviewers and authors separate.

6. Plan for file overlap in parallel work — When parallel agents may edit the same file, use a merge strategy (sequential landing, rebase, or conflict resolution).

Loop of Death Anti-Pattern

An autonomous loop that runs indefinitely without making progress, consuming tokens and budget.

Symptoms:

• Agent repeats the same fix/undo cycle
• Token consumption spikes without corresponding code changes
• Same test failures appear in consecutive iterations

Mitigations:

• Max iterations: Hard cap (e.g., MAX_ITERATIONS=10)
• Budget cap: Stop when cumulative API cost exceeds threshold
• Convergence detection: Track test pass count — if no improvement in 3 iterations, stop
• Diff-size check: If an iteration produces zero meaningful diff, break

# Example: convergence check in a loop
PREV_FAILURES=999
for i in $(seq 1 $MAX_ITERATIONS); do
    claude -p "$PROMPT"
    FAILURES=$(npm test 2>&1 | grep -c "FAIL" || true)
    if [ "$FAILURES" -eq 0 ]; then break; fi
    if [ "$FAILURES" -ge "$PREV_FAILURES" ]; then
        echo "No progress after iteration $i — stopping"
        break
    fi
    PREV_FAILURES=$FAILURES
done

Higher-Level Alternatives (2026)

• Claude Agent Teams: Native multi-agent orchestration built into Claude Code — managed team creation with role assignment
• DevFleet MCP: Project-level orchestration with mission dispatch and monitoring
• continuous-claude v3: Updated with skills system, better orchestration, and improved context management

References