Quickstart

From empty directory to a settled Goal

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

Path	What 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