paseo-loop

Original：🇺🇸 English

Translated

1 scripts

Run a task in a loop until an exit condition is met. Use when the user says "loop", "loop this", "keep trying until", "babysit", "poll", or wants iterative autonomous execution.

5installs

Sourcegetpaseo/paseo

Added on2026-03-15

NPX Install

npx skill4agent add getpaseo/paseo paseo-loop

SKILL.md Content

View Translation Comparison →

Loop Skill

You are setting up an autonomous loop. An agent runs repeatedly until an exit condition is met.

User's arguments: $ARGUMENTS

Prerequisites

Load the Paseo skill first — it contains the CLI reference for all agent commands.

What Is a Loop

A loop runs an agent repeatedly until it's done. There are two modes:

Self-terminating (no verifier)

A single worker agent runs each iteration. It returns

{ done: boolean, reason: string }

via structured output. The loop exits when

done

is true.

Worker + Verifier

A worker agent runs each iteration (detached, no structured output). After the worker finishes, a separate verifier agent evaluates the verification prompt and returns

{ done: boolean, reason: string }

. The loop exits when

done

is true.

Feedback between iterations

In both modes, the

reason

from the previous iteration is fed back to the next worker as

<previous-iteration-result>

. This gives the worker context about what happened last time.

Live Steering

Each loop run persists state in:

text

~/.paseo/loops/<loop-id>/
  worker-prompt.md     # worker prompt (live-editable)
  verifier-prompt.md   # verifier prompt (live-editable, only when verifier is used)
  last_reason.md       # latest iteration result
  history.log          # per-iteration records

Edits to prompt files are picked up on the next iteration without restarting the loop.

Parsing Arguments

Parse

$ARGUMENTS

to determine:

Worker prompt — what the worker does each iteration
Verifier prompt (optional) — what the verifier checks after each worker iteration
Worker — which agent does the work (default: Codex)
Verifier — which agent verifies (default: Claude sonnet)
Sleep (optional) — delay between iterations
Name — a short name for tracking
Max iterations — safety cap (default: unlimited)
Archive — whether to archive agents after each iteration
Worktree — whether to run in an isolated git worktree

Examples

/loop babysit PR #42 until CI is green, check every 5 minutes
→ worker-prompt: "Check the CI status of PR #42 using `gh pr checks 42`. Report done when ALL checks
  have passed (no pending, no failures). If any checks are still running or have failed, report not
  done and list which checks are pending or failing."
  No verifier (self-terminating: the worker inspects CI and reports done when green)
  sleep: 5m
  archive: yes
  name: babysit-pr-42

/loop implement the auth refactor from the plan in /tmp/plan.md
→ worker-prompt-file: /tmp/plan.md
  verifier-prompt: "Verify every step of the plan was implemented. Check file changes, types, and
  run `npm run typecheck` and `npm test`. Report each criterion individually with evidence."
  name: auth-refactor
  worktree: auth-refactor

/loop run the test suite until it passes
→ worker-prompt: "Run `npm test`. If any tests fail, read the failure output, investigate the root
  cause in the source code, and fix it. Report done when `npm test` exits with code 0 and all
  tests pass. Report not done if any test still fails, and explain which tests failed and why."
  No verifier (self-terminating: worker reports done when tests pass)
  name: fix-tests

/loop watch error rates after deploy, check every 10 minutes
→ worker-prompt: "Check the error rate for the canary deployment by running `./scripts/check-canary.sh`.
  Report done when the error rate has been below 0.1% for at least 2 consecutive checks. Report not
  done with the current error rate and trend."
  No verifier (self-terminating: worker reports done when error rate is stable)
  sleep: 10m
  max-iterations: 30
  archive: yes
  name: canary-watch

Using the Script

The loop is implemented as a bash script at

~/.claude/skills/paseo-loop/bin/loop.sh

bash

# Self-terminating: worker checks PR CI and reports done when all checks pass
~/.claude/skills/paseo-loop/bin/loop.sh \
  --worker-prompt "Check CI status of PR #42 using gh pr checks 42. Report done when ALL checks pass. Report not done with a list of pending/failing checks." \
  --name "babysit-pr" \
  --sleep 5m \
  --archive

# Worker + verifier: worker implements, verifier independently checks
~/.claude/skills/paseo-loop/bin/loop.sh \
  --worker-prompt "Implement the auth refactor: ..." \
  --verifier-prompt "Verify the auth refactor is complete. Run npm run typecheck and npm test. Check that all file changes match the plan. Report each criterion with evidence." \
  --name "auth-refactor" \
  --worktree "auth-refactor"

Arguments

Flag	Required	Default	Description
`--worker-prompt`	Yes*	—	Prompt given to the worker each iteration
`--worker-prompt-file`	Yes*	—	Read the worker prompt from a file
`--worker`	No	`codex`	Worker agent ( `provider/model` , e.g. `codex/gpt-5.4` , `claude/sonnet` )
`--verifier-prompt`	No*	—	Verification prompt for a separate verifier agent
`--verifier-prompt-file`	No*	—	Read the verifier prompt from a file
`--verifier`	No	`claude/sonnet`	Verifier agent ( `provider/model` )
`--name`	Yes	—	Name prefix for agents
`--sleep`	No	—	Delay between iterations (e.g. `30s` , `5m` , `1h` )
`--max-iterations`	No	unlimited	Safety cap on iterations
`--archive`	No	off	Archive agents after each iteration
`--worktree`	No	—	Worktree name. Created on first use, reused after.
`--thinking`	No	`medium`	Thinking level for worker

* Provide exactly one of

--worker-prompt

--worker-prompt-file

. Provide at most one of

--verifier-prompt

--verifier-prompt-file

Behavior by parameters

Parameters	Mode	Use case
`--worker-prompt` only	Self-terminating worker	Worker does work and decides when done
`--worker-prompt` + `--verifier-prompt`	Worker + verifier	Worker implements, verifier independently checks
`--worker-prompt` + `--sleep`	Polling with self-termination	Periodic check until a condition is met
`--worker-prompt` + `--verifier-prompt` + `--sleep`	Periodic work + verifier	Periodic work with independent verification

Agent Naming

Without verifier: agents are named

{name}-{N}

babysit-1     # First iteration
babysit-2     # Second iteration

With verifier: workers are

{name}-{N}

, verifiers are

{name}-verify-{N}

feat-1          # First worker
feat-verify-1   # First verifier
feat-2          # Second worker (with previous result context)
feat-verify-2   # Second verifier

Worktree Support

When

--worktree

is passed, all agents run in the same git worktree. The worktree is created on first launch and reused for all subsequent agents.

bash

~/.claude/skills/paseo-loop/bin/loop.sh \
  --worker-prompt "Implement the feature..." \
  --verifier-prompt "Verify the feature works and typecheck passes" \
  --name "feature-x" \
  --worktree "feature-x"

Your Job

Understand the task from the conversation context and
```
$ARGUMENTS
```
Decide the mode — does this need a separate verifier, or can the worker self-terminate?
Write the worker prompt — what the worker does each iteration. Must be self-contained (the agent has zero prior context).
Write the verifier prompt (if needed) — what the verifier checks. Should be factual and verifiable.
Choose sleep — if the task is polling/monitoring, add a sleep duration
Choose archive — use
```
--archive
```
for long-running or polling loops to keep the agent list clean
Choose agents — default:
```
codex
```
worker +
```
claude/sonnet
```
verifier
Choose a name — short, descriptive
Run the script — call
```
loop.sh
```
with all the arguments

When to use a verifier vs self-terminating

Use a verifier (

--verifier-prompt

) when:

The worker's job is to implement something and you want independent verification
You want the verification done by a different agent than the worker
The worker should focus on doing work, not on judging its own work

Use self-terminating (no verifier) when:

The worker is checking/polling an external condition (CI status, deployment health)
The worker can objectively determine when it's done (tests pass, file exists)
You want a single agent doing both the work and the evaluation

Writing a Good Worker Prompt

The worker prompt is what the agent receives each iteration. It must be:

Self-contained — The agent starts with zero context. Everything needed is in the prompt.
Specific — Name files, functions, types, URLs. Be concrete.
Action-oriented — Tell the agent what to do, not what to think about.

Writing a Good Verifier Prompt

The verifier prompt defines what the verifier checks after each worker iteration. It can range from strict factual checks to qualitative code review:

Factual / objective checks:

"Run
```
npm test
```
and
```
npm run typecheck
```
. Report done only if both pass with zero failures."
"Check that PR #42 has all CI checks green and no unresolved review comments."
"Verify the API responds to
```
GET /health
```
with status 200 within 500ms."

Code quality / style checks:

"Review the changes for DRY violations. Report done when there is no duplicated logic across files."
"Check that the implementation does not over-engineer. No unnecessary abstractions, no premature generalization, no feature flags for single-use code."
"Verify the code follows the project's conventions: functional style, no classes, explicit types, no
```
any
```
."

Performance / resource checks:

"Run the benchmark suite. Report done when p99 latency is under 100ms."
"Check bundle size. Report done when the production build is under 500KB gzipped."

Comprehensive verification:

"Verify every step of the plan was implemented. Check file changes, types, test output. Run
```
npm run typecheck
```
and
```
npm test
```
. Report each criterion individually with evidence."

The verifier should report facts with evidence, not suggest fixes.

Skill Stacking

You can instruct the worker to use other skills:

bash

~/.claude/skills/paseo-loop/bin/loop.sh \
  --worker-prompt "Use /committee to plan, then fix the provider list bug. The bug is..." \
  --verifier-prompt "The provider list renders correctly and npm run typecheck passes" \
  --name "provider-fix"

Composing with Handoff

A handoff can launch a loop:

/handoff a loop in a worktree to babysit PR #42

paseo-loop

NPX Install

Tags

SKILL.md Content

Loop Skill

Prerequisites

What Is a Loop

Self-terminating (no verifier)

Worker + Verifier

Feedback between iterations

Live Steering

Parsing Arguments

Examples

Using the Script

Arguments

Behavior by parameters

Agent Naming

Worktree Support

Your Job

When to use a verifier vs self-terminating

Writing a Good Worker Prompt

Writing a Good Verifier Prompt

Skill Stacking

Composing with Handoff