Loops

A loop is one task prompt that the Background Runner re-runs in isolated agent lanes, up to a set number of iterations, until its exit checks pass. Use one for work that has a clear finish line, such as “iterate until the build is green” or “fix these until the tests pass”. Every iteration is a paid agent run.

Loops are available only where the deployment enables the Background Runner’s loop source. Where it is off, the Loop Designer tile is not listed, the loops.* MCP tools are not advertised, and the loops API refuses requests.

States

succeeded, failed and cancelled are final.

Exit checks

A loop has 1 to 8 exit checks. After each iteration the Runner evaluates all of them against that iteration’s committed output.

• Exit mode. ALL checks pass (all) or ANY check passes (any). Use all unless any single check really does mean done.
• consecutive (in a row). An nl-goal check passes only after the judge says the goal is met on this many judged iterations in a row, under the same config. The default is 1. Each extra pass costs a full iteration.
• Timeouts. A command or test check times out after 10 minutes by default. You can set up to 30 minutes.
• Who reports what. The Runner runs command and test checks itself, so the worker cannot game them. artifact and worklist come from the worker’s own .yolo-result.json, under loop.artifacts and loop.worklist. Pair them with a command, test or nl-goal check under all. Only values reported in the current iteration count.
• Results. Each check records pass, fail, no evidence (missing-evidence, which counts as a fail) or error. An error means the check could not run. It is not a verdict on the work, and it never passes.

Iterations and limits

Each iteration’s brief contains your prompt, the iteration number and cap, the exit checks in plain language, the previous iteration’s check results, and the carried worklist when there is one.

Pauses

A paused loop shows the reason and what clears it:

Resume is refused while the cause still holds. For example, a loop paused at its cap stays paused until you raise the cap.

How loops run

Loops are the Background Runner’s second work source, next to the Kanban board. A loop runs only when the loop source is on and the Runner is running. In the Background Runner tile, Sources lists Kanban and Loops. Toggling Loops first shows what will change and asks you to confirm:

• On: queued loops become eligible for Runner slots alongside Kanban cards.
• Off: no new loop iterations start. An iteration that is already running finishes and is checked. Queued and paused loops wait until the source is back on, and no loop is cancelled.

Loops and cards share the workspace’s worker capacity. The Runner admits one iteration of a loop at a time. Each iteration runs in its own lane, and the previous iteration’s lane is retired once the next iteration is admitted.

The Background Runner tile’s Loops section lists active loops, with Recently finished loops beneath it. Each row shows the loop’s iteration, its state and the output of the running agent, with Pause, Resume, Cancel and Designer actions.

Launching a loop from the Loop Designer, or with run: true from an agent, turns the loop source on and starts a stopped Runner. Two cases stop and ask first:

• If starting the Runner would also run cards from the Ready column on the Kanban board, the Designer asks Start the Background Runner? and waits for you to confirm. If you choose Not now, the loop stays queued.
• A Runner that you paused or stopped stays paused or stopped. The Designer offers Resume runner instead of starting it.

Launching a loop never changes the landing mode.

Output and landing

Only a succeeded loop’s accepted result, the commit that passed the exit checks, can land. Output from intermediate iterations, paused loops, failed loops and cancelled loops never lands. The target branch is the Runner’s pinned base branch or, if none is pinned, the repository’s default branch. An agent can choose a different branch with baseBranch.

Landing follows the Runner’s After success setting, just as it does for Kanban cards:

• Manual (Off): the branch is pushed, and the Designer shows waiting for you to merge.
• PR + review (Review): a PR is opened, and you review and merge it.
• Auto merge (Auto): a PR is opened and merged once the provider’s requirements pass. If Auto merge is limited to certain branches (Only into), a loop that targets any other branch gets a PR for you to review instead.

The landing mode is fixed when the loop succeeds. A later switch to a narrower mode applies to it; a later switch to Auto merge does not.

The Designer’s Landing section and the Runner’s loop row offer Open PR and Review PR / View PR, which opens the same in-Studio PR review that Kanban cards use. A merge conflict gets the same handling as a Kanban card’s. Under Auto merge, an automatic conflict repair may be queued. Otherwise, Resolve conflicts in the PR review queues one. A repair is a new attempt of the accepted iteration and must pass the loop’s exit checks again. If it passes, it becomes the accepted result, gets a new PR, and the conflicted PR is closed.

Loop Designer

Add a Loop Designer tile from the tile picker. It is listed only when loops are enabled. An agent can open one with studio.create_tile using type loop-designer, and can pass config.loopId to show an existing loop.

In design mode:

• Start from a template offers the curated YOLO Verified starters: Docs sweep, Production error sweep, Test coverage push, Repository cleanup, Flaky test stabilizer, Dependency CVE burndown, Fresh-clone onboarding check, and Accessibility repair. A template only fills in the form. Adapt its placeholder commands (for example npm test) to your project.
• Task is the prompt the agent reads again on every iteration.
• Suggest goals with AI proposes exit checks, a mode and a cap based on the task. The suggestion replaces the current checks, so review it before launching.
• Exit checks has Loop succeeds when, which is either ALL checks pass or ANY check passes, followed by the checks.
• Agent is Workspace default or a specific agent. Max iterations is the cap. Advanced holds Memory and When cap is hit.
• Loop Doctor is an advisory audit: a static lint plus one AI-traced iteration. Its findings never block launch.
• Launch loop creates the loop and starts it as described in How loops run.

A launched loop shows its state, a progress bar of iterations against the cap, attempts, spend, per-check results with their evidence, a history of verdicts, and landing. Its controls are:

• Pause: takes effect immediately on a queued loop. If an attempt is running, the attempt and its evaluation finish first.
• Resume and Raise cap. At the cap, the button reads Raise cap and resume.
• Edit: change the task, exit checks, When cap is hit and the budget (Max spend (USD), Max time (minutes)). Changes apply from the next iteration. An attempt that is already running keeps its brief. Memory, the agent and the target branch cannot be changed.
• Cancel loop: no new iteration starts. A running attempt is asked to stop, and the loop is cancelled once the worker confirms. This cannot be undone.
• Design new clears the tile for a new loop. A loop that is still queued gets a Start loop button.

Agent tools

When loops are enabled, agents in the workspace get these Workspace MCP Server tools:

Agents are instructed to create, start or steer a loop only when the operator explicitly asks, and never to confirm a Kanban backlog on the operator’s behalf.

Related pages

• Background Runner: the Kanban source, landing modes and capacity
• Workspace MCP Server: the full tool list
• Tiles