paseo-loop

getpaseo/paseo

Run an agent loop until an exit condition is met for iterative autonomous execution.

What is paseo-loop?

Paseo Loop runs a worker/verifier cycle repeatedly until a goal is reached or limits are hit. Use it when you need an agent to keep trying, babysit a process, check something repeatedly, or drive toward a completion criterion autonomously.

Execute a worker agent each iteration with a concrete task
Verify progress with shell checks, verifier prompts, or both
Repeat until done condition, max iterations, or max time is reached
Manage loops with CLI commands: list, inspect, view logs, and stop
Archive agents after each iteration for inspection and debugging
Configure worker and verifier providers independently for cross-provider validation

How to install paseo-loop

npx skills add https://github.com/getpaseo/paseo --skill paseo-loop

Prerequisites

Install the paseo skill first
Read ~/.paseo/orchestration-preferences.json to understand available worker and verifier providers unless explicitly specified by the user

Claude Code

Cursor

Windsurf

Cline

How to use paseo-loop

1.Define a concrete worker prompt describing what the agent should do each iteration
2.Choose a verification strategy: shell check (objective criteria), verifier prompt (judgment-based), or both
3.Select worker and verifier providers from orchestration preferences or as specified
4.Set sensible limits: --max-iterations and/or --max-time to prevent runaway loops
5.Run the loop with `paseo loop run` and monitor with `paseo loop ls`, `paseo loop inspect <id>`, or `paseo loop logs <id>`

Use cases

Good for

Babysit a pull request: worker fixes issues, shell check validates PR status, repeats until checks pass
Drive tests to green: worker investigates test failures and fixes code, verifier confirms all tests pass
Cross-provider implementation: worker on one provider, verifier on another to catch each other's blind spots
Monitor external systems: poll an API or service state until a condition is met
Iterative code refinement: worker improves code quality, verifier checks coherence and test results

Who it's for

Developers automating repetitive verification tasks
Teams managing continuous integration and testing workflows
Engineers implementing features that require multiple refinement cycles
Anyone needing autonomous babysitting of long-running processes

paseo-loop FAQ

When should I use a loop vs. a cron heartbeat?

Use a loop when each iteration needs a full worker/verifier lifecycle with state carried forward. Use a cron heartbeat (create_heartbeat/delete_heartbeat) for lightweight recurring checks that return to the same conversation, where each firing should be independent.

How do I prevent infinite loops?

Always set --max-iterations and/or --max-time. Open-ended loops without limits are how runaway executions happen.

Can I use different providers for the worker and verifier?

Yes, and it's recommended for implementation loops. Pair them on different providers so each catches the other's blind spots. Use --provider for the worker and --verify-provider for the verifier.

What's the difference between --verify-check and --verify?

--verify-check runs a shell command for objective criteria (e.g., `npm test`). --verify uses a verifier prompt for judgment-based decisions. Use both when shell rules out obvious failures and the verifier judges the rest.

How do I inspect what happened in each iteration?

Use `paseo loop inspect <id>` to see loop details, `paseo loop logs <id>` for output, and set --archive to keep agents after each iteration for full inspection.

Full instructions (SKILL.md)

Source of truth, from getpaseo/paseo.

name: paseo-loop description: Run an agent loop until an exit condition is met. Use when the user says "loop", "babysit", "keep trying until", "check every X", "watch", or wants iterative autonomous execution. user-invocable: true

Paseo Loop Skill

A loop is a worker/verifier cycle: launch a worker → check verification → repeat until done or limits hit. Use for "keep trying", "babysit", or "watch this until X."

For lightweight recurring checks that should return to this same conversation, prefer a cron heartbeat (create_heartbeat, then delete_heartbeat when finished). To change it, delete and recreate it. Use a loop when each iteration needs a worker/verifier lifecycle; use a schedule when each firing should create a fresh independent agent and workspace.

User's arguments: $ARGUMENTS

Prerequisites

Read the paseo skill. Before choosing worker or verifier providers, read ~/.paseo/orchestration-preferences.json unless the user explicitly named providers in this request. Do not start the loop until you have read it.

Loops are a CLI primitive: paseo loop run. Manage with paseo loop ls, paseo loop inspect <id>, paseo loop logs <id>, paseo loop stop <id>.

Your job

Understand the user's intent from $ARGUMENTS and the conversation.
Worker prompt — self-contained, concrete about what to do this iteration, explicit about what counts as progress.
Verification — pick the right shape:
- Shell check (--verify-check) for objective criteria a command can answer (gh pr checks --fail-fast, npm test).
- Verifier prompt (--verify) for judgment ("Return done=true only if all tests pass and the changed files are coherent. Cite the command and the outcome.").
- Both, when shell rules out the obvious failures and the verifier judges the rest.
Providers — --provider for the worker, --verify-provider for the verifier. From preferences unless the user named them. For implementation loops, pair worker and verifier on different providers — each catches the other's blind spots.
Sleep — --sleep only when polling something external. Otherwise let it run as fast as the loop completes.
Stops — set a sensible --max-iterations and/or --max-time. Open-ended loops are how runaways happen.
Archive — --archive keeps agents after each iteration for inspection.
Launch with paseo loop run.

Common shapes

Babysit a PR — worker checks PR state and fixes issues; shell check is gh pr checks <n> --fail-fast; sleep 2m; max-time 1h.

Drive tests to green — worker investigates failures and fixes code; shell check is the test command; verifier confirms all tests pass; max-iterations 10.

Cross-provider implementation — worker on impl provider, verifier on a different provider; verifier checks changed files, runs typecheck and tests; max-iterations and max-time both bounded; archive on so iterations can be inspected.