> ## Documentation Index
> Fetch the complete documentation index at: https://loop-js.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From empty directory to a settled Goal

## 1. Scaffold

```sh theme={null}
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:

```sh theme={null}
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.

```ts theme={null}
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):

```ts theme={null}
verify: "`bun test` passes and the README documents the new flag",
```

## 3. Run

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
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](/cli/cron#modal---backend-modal).

## 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 |