LoopFlow

An open, natural-language DSL for loop engineering.
Describe a staged, self-correcting, human-gated agent workflow in plain English, press ▶, and it runs on Claude Code.

Stop babysitting the agent. Write the goal once — the loop plans, acts, reflects on red,
and stops only when the check is green, at the gates you set.

📖 Read the tutorial → loopflow.live

Tutorial · ⚡ Playground · 🛠️ Workshop · 🎮 Lab · Manual · Keywords · FAQ

Quickstart

Requires Node 18+ and the Claude Code CLI — full install options in the manual.

npx @loop-lang/loop init      # /loopflow skill + AGENTS.md + the loop-first default (add --cursor / --copilot for other agents)

That last piece means you usually don't type /loopflow at all: init drops a gated
default into CLAUDE.md, so when you ask for something repeatable and verifiable ("fix this
flaky test until it's reliably green"), Claude reaches for a .loop on its own — while
one-off questions and trivial edits are done directly, no loop ceremony. The gate is
AGENTS.md's four-condition test; /loopflow stays the explicit override in both directions:

/loopflow fix the failing test — done when the suite passes
/loopflow run examples/fix_test.loop   # name a .loop file and it runs natively in the session

Copy .claude/skills/loopflow/ to ~/.claude/skills/ to use the skill in any repo. Don't write your first loop from scratch — start from a template and edit the goal + done when. Full walkthrough at loopflow.live.

Why

AI writes the code now. But you're still the conductor — kicking off manual pass after manual pass: "fix the security issues", "now refactor", "now fix the UI." Even strong methods leave you iterating by hand, in layers, forever.

LoopFlow lets you describe that movement once. You don't type the app — you type the loop: the five decisions (objective, context, actions, verification, stopping) that today are buried in a prompt. LoopFlow makes them first-class, editable, and shareable; at run time they drive five phases — plan → act → observe → reflect → stop. The tutorial teaches the framing.

A taste

loop "fix billing apostrophe bug":
  goal: settings save when the company name has an apostrophe
  done when the test "billing.spec.ts::apostrophe" passes

  look at: billing/form.tsx, api/settings.ts, schema/settings.ts, and the last failure
  allow edits automatically, but ask me before migrations or pushes

  each cycle: plan, then act, then observe
  when it passes and the goal is met:  stop
  when it fails:                        reflect on which layer broke, then plan again
  when blocked:                         ask a human
  after 6 tries:                        stop and warn "thrashing"

Compose loops

Compose loops into pipelines (stages in order, fail-fast), chain whole files with flow, and fan out over a plan with for each — humans wired in where judgment lives. Full grammar with worked examples: the tutorial and the manual.

Verify like you mean it

done when is the loop's definition of reality. List several checks (all must pass), mix deterministic tests with LM-judged evals, and harden both against false greens:

• done when "pnpm test checkout" passes 3 times — flake guard: one lucky green isn't "done".
• done when the skill "code-review" approves by 3 judges — judge panel: majority of 3 independent verdicts; one wobbly LM judgment isn't "done" either.
• done when the skill "path-review" approves on the trajectory — trajectory eval: catches what a green test can't — an agent that gamed the check.

Taught with a worked example in the tutorial; full mechanics (working dir, shell env, exit codes) in How verification works.

Skills and memory

A loop can coordinate proven skills (use skills: check-weather, analyze-workout), let a review skill be the verdict (done when the skill "workout-review" approves), and keep cross-run memory in a markdown file (remember in "morning-run.memory.md"). With ctx attached as the skill source, use skills recommended by ctx provisions the right bundle before the first plan — opt-in, fail-closed, inert without ctx. Details: manual, integration guide, examples/skills_memory.loop, examples/ctx_capabilities.loop.

The vocabulary — learn it once

pipeline · stage · loop · flow · for each … in … · run … then … · each cycle · goal · done when · look at · allow…/ask me before… · also · use skills · remember in · when… · reflect · a human… · stop · use · schedule · git

Power comes from composition, not keyword count. Each word is documented at loopflow.live/keywords; the authoritative grammar is AGENTS.md.

Git strategy (safe by default)

Without a git: block, LoopFlow works on a branch and commits when the goal is met — it never pushes to main or master (unconditional, not configurable). A git: block opts into push and a pull request: all line forms and cascade rules in the manual, working file at examples/git_policy.loop.

Authoring: by hand or by agent

By hand: the LoopFlow VS Code extension (ext install Loop-Lang.loopflow) gives highlighting, completions, hover docs, and squiggles. By agent: drop AGENTS.md in your repo and any assistant authors .loop from a plain-English request — feature details in the manual.

Run it headless

The loop-run CLI ships with npm i -g @loop-lang/runtime:

loop-run run file.loop --live          # real-time browser dashboard of the run
loop-run run file.loop --log run.log   # NDJSON event log (secrets scrubbed)
loop-run run file.loop --resume run.log  # skip what the log proves done; pick up where it died
loop-run show file.loop                # sanity-check the shape as ASCII before spending tokens (explain = plain English)

In-session, the dashboard is opt-in: set live=true in loop.config (loop init writes it with live=false). Log format, redaction, resume semantics, and the LOOP_EVENTS_URL remote collector: Event log & telemetry.

Project layout

Is this just another <X>?

"Is this another LangChain?", "why not YAML?", "won't better models make this pointless?",
"doesn't it lock me into Claude Code?" — answered straight in the FAQ.

Status

Active — see the roadmap and open issues.

Roadmap

• Next — runner abstraction (run loops on your own local/API model), a GitHub Action
  (loops as CI quality gates), a community template registry (use someone/their-method).
• Later — visual graph editor (the loop-spec IR is built for it), async human nodes,
  reactive stages, scheduling.

Built with LoopFlow

LoopFlow ships real software. Forge — a ticket-driven implementation platform (hand it a ticket, agents implement it) — is built with LoopFlow, including its sandbox runner: isolated, network-less execution of agent-written code. The pipeline that built it is examples/forge-sandbox.loop; the walkthrough is the case study in the tutorial.

Contributing

This is a community project and an open standard. Good first issues: new presets, grammar edge cases, formatter rules. See CONTRIBUTING.md and the Code of Conduct.

License

Apache-2.0. The language and the loop-spec IR are an open standard — implement against them freely.

Maintainer

Idan Ayalon — creator & maintainer of LoopFlow. Built Forge with it.

📧 [email protected]
💼 linkedin.com/in/idan-ayalon