Loop until the North Star

loop() composes the runtime:

plan → record → observe → refine → repeat

Quick use

import { loop } from "unsurf/skills/loop";

const result = await loop({
  spec: "open coey.dev and visit the first project",
  northStar: "Did the browser land on a project page?",
  maxIterations: 3,
});

Or attach to an already-open browser:

unsurf loop "open coey.dev and visit the first project" \
  --north-star "Did the browser land on a project page?" \
  --max-iter 3 \
  --cdp-port 9222

A good North Star

Good North Stars are:

• yes/no
• visible in the recording
• specific enough to stop on

Examples:

• “Did the authenticated dashboard load?”
• “Did the page reach a project detail view?”
• “Did all three form fields contain non-empty values?”

Stop reasons

Reason	Meaning
met	The recording satisfied the North Star
abort	Refiner gave up
maxIterations	Budget exhausted
errorBudget	Too many consecutive failures

When to use loop

Use loop for browser-native work with a visual success condition. Use worker when a stable API seam has already been discovered and direct HTTP replay is the better interface.