prompts-gpt sweep

Multi-iteration execution engine that runs the same prompt N times, feeding each iteration's summary into the next for progressive refinement.

Usage

# Single file
prompts-gpt sweep [-f <path>] [-n <count>] [--agent <name>] [--model <name>]

# All sweep files
prompts-gpt sweep --all-sweeps [--sweep-strategy sequential|parallel] [-n <count>]

# Specific sweep files
prompts-gpt sweep --sweep-files <a,b,c> [--sweep-strategy sequential|parallel] [-n <count>]

When to Use

Use sweep for:

• Deep audits — Run a security or code quality audit multiple times, with each pass building on previous findings
• Progressive refinement — Each iteration receives a summary of what the last iteration accomplished
• Autonomous quality loops — Self-evaluation scoring can rate each iteration and stop early if quality thresholds are met
• Exhaustive checklists — Large audit files where one pass can't cover everything

Options

File Selection

Iteration Control

Provider & Model

Execution

Output & Safety

How Sweep Works

Iteration Lifecycle

Iteration 1:
  ┌─────────────────────────┐
  │ Original Prompt          │ → Agent executes → Output + Summary
  └─────────────────────────┘

Iteration 2:
  ┌─────────────────────────┐
  │ Original Prompt          │
  │ + "Previous iteration    │ → Agent executes → Output + Summary
  │   summary: ..."          │
  └─────────────────────────┘

Iteration 3:
  ┌─────────────────────────┐
  │ Original Prompt          │
  │ + "Previous iteration    │ → Agent executes → Output + Summary
  │   summary: ..."          │
  └─────────────────────────┘

Context Chaining

After each iteration, the sweep engine:

1. Extracts a summary from the agent's output (last N lines or structured summary)
2. Injects this summary into the next iteration's prompt
3. The agent sees what was accomplished and continues from there

Pre-Flight Checks

Before running, sweep validates:

• Provider CLI is installed and accessible
• No existing sweep lock (prevents concurrent sweeps on the same file)
• Prompt file exists and is readable
• Configuration is valid

Lock Management

• A .sweep.lock file prevents concurrent sweeps on the same prompt
• Locks include PID and timestamp for stale detection
• Use --force-unlock to release stale locks
• SIGTERM/SIGINT handlers automatically release locks

Self-Evaluation

Sweep files can include evaluation criteria in YAML frontmatter:

---
iterations: 3
eval:
  criteria:
    - correctness
    - completeness
    - code-quality
  passThreshold: 0.7
---

After each iteration, the engine can score the output against these criteria and include the score in the summary.

Examples

Interactive mode

prompts-gpt sweep

Presents file picker, iteration count, provider, and model selection.

Explicit file and iterations

prompts-gpt sweep -f .prompts-gpt/sweeps/security-audit.md -n 5

All sweeps sequentially

prompts-gpt sweep --all-sweeps --sweep-strategy sequential -n 3

All sweeps in parallel

prompts-gpt sweep --all-sweeps --sweep-strategy parallel -n 2

Specific sweeps by name

prompts-gpt sweep --sweep-files design,research,security -n 2

Parallel iterations (experimental)

prompts-gpt sweep -f .prompts-gpt/sweeps/audit.md -n 6 --parallel 3

Runs 6 iterations in batches of 3 concurrently.

With model override

prompts-gpt sweep --model claude-sonnet-4-20250514

Dry run preview

prompts-gpt sweep -f .prompts-gpt/sweeps/tests.md -n 3 --dry-run

Sweep File Format

Sweep files are Markdown files stored in .prompts-gpt/sweeps/:

---
iterations: 3
eval:
  criteria:
    - correctness
    - completeness
  passThreshold: 0.7
---

# Security Audit

Review the entire codebase for security vulnerabilities.
Fix every issue found — do not just report.

## Checklist
- [ ] SQL injection
- [ ] XSS vulnerabilities
- [ ] CSRF protection
- [ ] Authentication bypass

YAML Frontmatter Fields

Artifacts

.scripts/runs/
  agent-YYYYMMDDHHMMSS-PID-HASH/
    iteration-1/
      raw-output.log
      summary.md
      meta.json
    iteration-2/
      raw-output.log
      summary.md
      meta.json
    sweep-manifest.json   # Overall sweep results
    summary.md            # Final combined summary

Sweep Result

{
  ok: boolean;
  iterations: SweepIterationResult[];
  totalDurationMs: number;
  provider: string;
  model: string;
  iterationsCompleted: number;
  iterationsRequested: number;
  evalScores?: SweepEvalScore[];
}

See Also

• Sweep vs Prompts Guide — Deep comparison
• run — Single-shot execution
• orchestrate — Multi-agent orchestration