Skip to main content

​
1. Scaffold

npm create @loop.js@latest my-loop
cd my-loop && npm install
This writes three things: a package.json depending on @loop.js/core (which provides the project-local loop bin), a loop.config.ts, and an empty workspace/ — the work tree the agents build in. Agents run on the Claude Agent SDK, so set your key: 
export ANTHROPIC_API_KEY=sk-ant-…

​
2. State the Goal

loop.config.ts is goal-only: goal is the field you edit; limits spells out the tight engine defaults, and every other knob is a commented line already carrying its default. 
import { Loop } from "@loop.js/core"

export default Loop.define({
  goal: "Build a playable 2D platformer in ./game.",

  limits: {
    rounds: 3, // runaway guard — Rounds across the whole Loop
    usd: 1,    // total $ across the whole Loop, step-granular cutoff
  },
})
Make the Goal judgeable: a testable end state beats a vibe. “The test suite passes and the README documents the new flag” gives Verify a bar; “improve the code” does not. When the bar deserves its own text, hand the judge one — verify takes a prompt exactly like goal (a string, { file: "./verify.md" }, or a function): 
verify: "`bun test` passes and the README documents the new flag",

​
3. Run

npx loop run
Rounds stream by until the Loop settles or a guard fires — the exit code says which. Check on it any time, from any shell: 
npx loop status          # human-readable snapshot
npx loop status --json   # for machines

​
4. Schedule it (optional)

Let a real scheduler re-trigger the loop instead of babysitting it: 
npx loop cron add "0 8 * * *" --until settled                  # local: crontab / launchd / Task Scheduler
npx loop cron add "0 8 * * *" --until settled --backend modal  # same, in the cloud — Modal fires a Runner per tick
The Entry runs loop run in this directory every morning and removes itself at the first settle — capped at 3 runs / 24 hours by default, in case it never does. With --backend modal, State lives on a Modal Volume and removing the Entry never deletes it — see loop cron.

​
Where things live

PathWhat it is
workspace/the work tree — everything the agents build
.loop/engine state: the Record, journal, lock
.handoff/the per-Round notes that carry memory across Rounds