LoopFlow

LoopFlow transforms the Claude Code framework into an efficient, self-sustaining system for software development. By allowing developers to articulate goals and create a structure involving various agents and verification processes, LoopFlow automates iterations to optimize coding tasks. In this architecture, a pipeline of agents operates autonomously, executing defined commands in a YAML file until the prescribed outcome is achieved, the budget is utilized, or the iteration limit is reached.

Core Features

• Automated Problem-Solving: LoopFlow eliminates the need for continuous prompting by enabling agents to independently manage inquiry requests and test validations. A unique framework allows the following cadence: one agent proposes a solution, a different agent evaluates it, and the entire process leverages a memory file that enriches performance over time.

Example Usage

The command below illustrates running a loop, emphasizing the structured approach:

$ loopflow run test-and-fix

Iteration 1/3
  ▸ fix …
    done · $0.31 · resume: claude --resume 072f1abb…
  ▸ review (gate) …
    gate FAIL · $0.12
    │ The date parser fix only handles ISO strings; the failing test
    │ also feeds epoch millis. Root cause not addressed.

Iteration 2/3
  ▸ fix …
    done · $0.28
  ▸ review (gate) …
    done · $0.11

✓ success · 2 iteration(s) · $0.82

Visual Representation

A video demonstration of the LoopFlow process shows how the release-check loop operates over multiple iterations:

LoopFlow demo — release-check loop, 2 iterations

Why LoopFlow?

Traditional usage of coding agents involved a repetitive cycle of prompts and responses, which is a cumbersome method. LoopFlow shifts this paradigm by integrating a systematic loop that continuously prompts the agent until it accomplishes specified objectives. However, it addresses key challenges:

• Self-Assessment: Prevent erroneous self-approvals through clearly defined gates requiring external verification from another agent before completion.
• Cost Management: Enforce budget caps directly within LoopFlow and via Claude Code, significantly reducing uncontrolled expenditure during automated loops.
• Knowledge Retention: Introduce a memory mechanism, logging outcomes and project evolution, ensuring the agent retains crucial context beyond individual tasks.

Anatomy of a Loop

Loops adhere to a defined structure, as exemplified in the following YAML configuration:

# .loopflow/loops/test-and-fix.yaml
name: test-and-fix
description: Run the test suite, fix failures, verify the fix.

budget:
  max_usd: 2.00        # Limit for the entire run
  max_iterations: 3    # Attempts for the gate acceptance

worktree: false        # Isolate processes in a separate git worktree

steps:
  - id: fix
    role: >            # Persona description for the agent
      You are a careful maintainer. You make the smallest change that fixes
      the problem, and you never weaken a test to make it pass.
    prompt: |
      Run this project's test suite. Diagnose and fix the root cause of any
      failure. Re-run to confirm. Summarize what you changed and why.

  - id: review
    gate: true         # Must affirmatively approve for loop success
    role: >
      You are a skeptical senior engineer reviewing a change you did not
      write. You trust nothing without evidence.
    prompt: |
      A previous agent claims to have fixed failing tests. Inspect the diff,
      re-run the suite yourself, and check no test was weakened or deleted.

Getting Started

Initiating your journey with LoopFlow is simple using the following command:

npm install -g @loopflow/cli   # or: npx @loopflow/cli

cd your-project
loopflow init             # Scaffold the base structure with starter loops
loopflow run test-and-fix --dry-run   # Preview agent prompts  
loopflow run test-and-fix             # Execute the loop for real

Come Build with LoopFlow

Contributions are welcomed, particularly in the form of loops that address practical challenges. Each addition enhances the resource and utility of LoopFlow, inviting a community-driven effort for continuous improvement.Visit contributing guidelines for more details.