Stop babysitting the agent.

A loop is the work you already do around an AI agent: ask it to change something, check the result, give it the failure, and repeat until the work is actually done.

LoopFlow makes that cycle explicit: plan → act → observe → reflect, with a real done when check, human gates for risky steps, and a retry limit.

If the check fails, LoopFlow feeds the failure back into the next plan.

each cycle: plan, then act, then observe
when it fails: reflect, then plan again
when it passes and the goal is met: stop

The last line should usually be a guard: after 6 tries: stop and warn "stuck".

Built-in agent commands help in one session. LoopFlow gives you a portable file: runnable by people, agents, CI, and future you.

In Claude Code, ask LoopFlow for an example:

/loopflow example

It gives you a runnable .loop file like this:

loop "fix checkout tax":
  goal: checkout shows the right tax
  done when "pnpm test checkout" passes

  look at: src/checkout/, tests/checkout/, and the last failure
  allow edits automatically, but ask me before migrations

  each cycle: plan, then act, then observe
  when it fails: reflect, then plan again
  after 6 tries: stop and warn "stuck"

Save it as fix-checkout.loop, then run:

/loopflow run fix-checkout.loop

Prefer the terminal? Install once with npm i -g @loop-lang/loop @loop-lang/runtime, then use loop init, loop-run show file.loop, and loop-run run file.loop.

done when is the finish line. Prefer a fast command that can pass or fail.

done when "pnpm test checkout" passes
done when "semgrep --severity=high" finds nothing
done when the test "billing.spec.ts::apostrophe" passes
done when a human confirms "looks right on mobile"

Multiple done when lines all must pass.

The loop does not decide by vibes. It runs your check in the shell, reads the exit code or output, and only stops on success.

Add an eval when the “how” matters:

done when "pnpm test" passes
done when the skill "code-review" approves on the trajectory
  the bar: did not weaken tests or write outside src/

look at: keeps the agent close to your architecture.

look at: src/billing/, tests/billing/, docs/api.md, and the last failure
knowledge: docs/security-rules.md
examples: examples/good-handler.ts

Always include and the last failure when the loop reflects.

The normal cycle is simple:

1. plan the smallest change
2. act by editing files
3. observe by running the check
4. reflect on failure

each cycle: plan, then act, then observe
when it fails: reflect on the failing layer, then plan again

A loop has two memory layers. Inside one run, reflect turns a failed check into a lesson, and and the last failure passes that lesson into the next plan.

Across runs, remember in saves outcomes to a markdown file so the next run starts with what the loop learned last time.

loop "fix checkout":
  goal: checkout is correct
  done when "pnpm test checkout" passes

  look at: src/checkout/, tests/checkout/, and the last failure
  remember in "checkout.memory.md"

  each cycle: plan, then act, then observe
  when it fails: reflect on what the test proved, then plan again
  after 6 tries: stop and warn "stuck"

reflect is short-term memory. remember in is long-term memory.

Let the agent work. Pause it where judgment or risk lives.

allow edits automatically, but ask me before migrations or pushes
a human approves the plan first
a human reviews before stopping
a human approves before deploy

pipeline "checkout v2":
  stage "cart totals":
    goal: totals include tax
    done when "pnpm test cart" passes
    look at: src/cart/, tests/cart/, and the last failure

  stage "submit order":
    goal: orders submit safely
    done when "pnpm test checkout" passes
    a human approves before charging a card

Use LoopFlow alone for small, checkable work. For real product work, we recommend pairing LoopFlow with a method like BMAD: BMAD gives you discovery, PRD or tech-spec, architecture, epics, and story slicing; LoopFlow turns each story into a verifiable agent process.

Tiny BMAD crash course

1. Brief — optional discovery: define the problem, user, constraints, and success.
2. PRD or tech spec — turn the brief into requirements and acceptance criteria. Simple work may use a tech spec instead of a PRD.
3. Architecture — for larger BMAD tracks, decide the technical shape, boundaries, risks, and dependencies.
4. Epics — after architecture, break the PRD and technical decisions into large deliverable chunks.
5. Stories — break each epic into small, testable units of work.

The handoff to LoopFlow

• One story → one stage.
• One epic → one pipeline.
• One sprint/backlog → one flow with for each.
• Story acceptance criteria become done when.
• Architecture notes go into look at: or knowledge:.
• Risky steps become human gates.
• Failed checks feed reflect.
• Repeated lessons go into remember in.

BMAD decides the plan. LoopFlow runs the plan until verified.

Ask Claude or Pi to write the loop

You do not have to hand-write the .loop first. After BMAD gives you a story, paste it into your agent and ask LoopFlow to turn it into a verifiable process.

# Claude Code
/loopflow Create a LoopFlow file for this BMAD story.

Story:
<paste story>

Use the architecture notes as context.
Done when the story acceptance tests pass.
Ask me before migrations, dependencies, or pushes.

# Pi
/skill:loopflow Create a LoopFlow file for this BMAD story.

Story:
<paste story>

Use the architecture notes as context.
Done when the story acceptance tests pass.
Ask me before migrations, dependencies, or pushes.

Then run the file:

# Claude Code
/loopflow run story-login.loop

# Pi
/skill:loopflow run story-login.loop

flow "bmad sprint":
  for each story in "sprint.yaml":
    run "story-template.loop"

story-template.loop contains the pipeline each story runs:

pipeline "bmad story":
  stage "implement":
    goal: implement the BMAD story from the provided context
    look at: src, docs, and the last failure
    allow edits automatically, but ask me before dependencies, migrations or pushes
    each cycle: plan, then act, then observe
    done when "pnpm test" passes
    when it fails: reflect on the failed acceptance criteria, then plan again
    after 6 tries: stop and warn "story is not converging"

  stage "human QA":
    goal: human accepts the completed story
    each cycle: observe
    a human reviews before stopping

Do not port all of BMAD into LoopFlow. Let BMAD decide what to build and in what order; use LoopFlow to make each repeatable story execution verifiable.

LoopFlow keywords fall into a few jobs. Learn the groups first; use the keyword reference when you need exact syntax.

Shape

Contract

Context

Control

Safety

Capabilities

Use templates when the shape is common. Fill the TODOs, then run loop-run show.

• templates/bugfix.loop
• templates/feature.loop
• templates/load-spec.loop
• templates/cicd-check.loop

loop-run show file.loop   # parse + preview
loop-run run file.loop    # execute
loop-run ls               # list loops

VS Code: install “LoopFlow” for syntax, diagnostics, completions, and Run CodeLens.

Live dashboard: set live=true in loop.config, or run loop-run run file.loop --live.

Save useful loops in ~/.Codex/loopflow/. Then reuse them in any repo.

# examples: security.loop, bugfix.loop, release.loop

Tests prove behavior. Evals judge quality.

done when "pnpm test" passes
done when the skill "api-review" scores 8 or more on the output
  the bar: simple API, no secrets, clear errors

skills: controls how the loop uses reusable capabilities while it plans and acts.

skills: auto                         # discover/add useful skills with minimum friction
skills: ask                          # recommend additions, ask before adding
skills: fixed, seo-audit             # use only these explicit baseline skills
skills: none                         # use no skills
skills: auto, seo-audit              # start with seo-audit, auto-add more if useful

auto runs an early capability check and may add safe, useful skills. ask does the same analysis but asks first. fixed never adds skills beyond the listed baseline. Legacy use skills: loops still work, but skills: is the preferred form.

Put shared settings in loop.config so every loop inherits them.

each cycle: plan, then act, then observe
models: fast haiku, strong opus
git:
  work on a branch
  commit when the goal is met
  do not push

Use these when a loop runs unattended or touches sensitive systems.

rigor: agentic engineering
mode: orchestrator
runs as: release-bot
observe:
  meter tokens and cost
  stop and warn if cost exceeds "$5"
sandbox:
  no network access

Hooks run commands at lifecycle points and block on failure.

hooks:
  before each cycle: "pnpm lint" passes
  on stop: "pnpm test" passes

Observation is about safety: trace cycles, meter cost, and restrict execution when needed.

LoopFlow accepts helpful shorthands.

check: "pnpm test" passes
files: src/, tests/, and the last failure
when it breaks: reflect, then plan again

• Bug fix: one loop until a failing test passes.
• Feature: a pipeline, one stage per story.
• Release: tests, security scan, human approval, push.
• A-to-Z: discover → design → build each story.

See examples, Loop market, and the manual.

• Keyword reference
• Full manual
• Blog
• Playground

Idan Ayalon — creator and maintainer. bar.idan@gmail.com · LinkedIn

What is an AI coding loop?

A workflow where an agent plans, edits, checks, and retries until a real check passes.

How do I make an agent self-correct?

Give it a goal, a real done when check, a reflect step, and a try limit.

How is this different from prompting?

A prompt asks once. A loop keeps going until verified, with human gates for risk.

What tools does it work with?

Claude Code via /loopflow, headless via loop-run, and plain text anywhere.