Sweep vs Prompts: Understanding the Difference

This guide explains the fundamental difference between prompt execution (run / run-batch) and sweep execution (sweep) — when to use each, how they differ architecturally, and which approach suits different use cases.

Quick Comparison

Prompt Execution (run / run-batch)

What It Does

Prompt execution is a single-shot model. You provide a prompt file, the CLI invokes the configured AI agent, and the agent processes the prompt once. The result is captured as a log file and summary.

run — Single Prompt

prompts-gpt run .prompts-gpt/code-review.md --provider codex

One prompt → one agent invocation → one result.

run-batch — Multiple Prompts

prompts-gpt run-batch .prompts-gpt/review.md .prompts-gpt/tests.md --provider codex

Multiple prompts → sequential agent invocations → one result per prompt. Each prompt runs independently; there is no context sharing between prompts.

When to Use

• Quick tasks: Code review, test generation, documentation
• CI/CD integration: Run a fixed set of checks on every PR
• Batch automation: Process many independent prompts
• One-off operations: Generate a report, fix a bug

Characteristics

1. Stateless: Each execution starts with a clean context
2. Fast: No iteration overhead, lock management, or pre-flight
3. Simple: Straightforward input/output model
4. Independent: Prompts in a batch don't share context

Sweep Execution (sweep)

What It Does

A sweep runs the same prompt multiple times with context chaining. Each iteration receives the previous iteration's summary as additional context, enabling the agent to progressively refine its work.

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

One prompt → five sequential iterations → each iteration aware of previous work.

How Context Chaining Works

Iteration 1: Original prompt → Agent output → Summary extracted
                                                    ↓
Iteration 2: Original prompt + "Previous: ..." → Agent output → Summary
                                                    ↓
Iteration 3: Original prompt + "Previous: ..." → Agent output → Summary
                                                    ↓
...and so on

When to Use

• Deep audits: Security, performance, accessibility reviews
• Progressive refinement: Iteratively improve code quality
• Comprehensive coverage: Ensure all aspects of a task are addressed
• Self-evaluating tasks: Score agent output and iterate until quality threshold is met

Characteristics

1. Stateful: Each iteration carries context from previous ones
2. Thorough: Multiple passes cover more ground
3. Self-correcting: Agent can fix issues from previous iterations
4. Guarded: Lock files prevent concurrent execution
5. Observable: Progress events and per-iteration metrics

Architectural Differences

Execution Flow

Prompt (run):

Input → Provider CLI → Output → Artifacts

Sweep:

Pre-flight → Acquire Lock → 
  [Iteration 1] → Summary → 
  [Iteration 2 + context] → Summary → 
  ... → 
  [Iteration N + context] → Summary → 
  [Optional: Self-eval] → 
Release Lock → Final Artifacts

Artifact Structure

Prompt (run):

.scripts/runs/
└── agent-20260521-abc123/
    ├── output.log          # Raw agent output
    └── summary.md          # Extracted summary

Sweep:

.scripts/runs/
└── sweep-20260521-abc123/
    ├── iteration-1/
    │   ├── output.log
    │   └── summary.md
    ├── iteration-2/
    │   ├── output.log
    │   └── summary.md
    ├── iteration-3/
    │   ├── output.log
    │   └── summary.md
    ├── sweep-manifest.json  # Sweep metadata
    └── eval-scores.json     # Self-eval results (optional)

Lock Semantics

• Prompt: No locking. Multiple run commands can execute concurrently.
• Sweep: Lock file created at sweep start; released on completion. Prevents concurrent sweeps on the same file. Stale locks auto-expire.

Pre-Flight Checks

• Prompt: Validates provider availability only.
• Sweep: Full pre-flight: provider availability, disk space, git state, existing lock check, prompt file validation, YAML frontmatter parsing.

Decision Matrix

Combining Approaches

You can combine prompt and sweep execution in workflows:

# Step 1: Quick scan with run
prompts-gpt run .prompts-gpt/quick-scan.md --provider codex

# Step 2: Deep dive with sweep on findings
prompts-gpt sweep .prompts-gpt/sweeps/deep-security.md -n 5 --provider codex

# Step 3: Batch verification
prompts-gpt run-batch .prompts-gpt/verify-*.md --provider codex

Programmatic Example

import { runPrompt, runBatch, sweepPrompt } from "prompts-gpt";

// Single quick check
const quickResult = await runPrompt({
  promptFile: ".prompts-gpt/lint-check.md",
  provider: "codex",
});

// Batch of independent tasks
const batchResult = await runBatch({
  promptFiles: [".prompts-gpt/review.md", ".prompts-gpt/docs.md"],
  provider: "codex",
});

// Deep iterative audit
const sweepResult = await sweepPrompt({
  promptFile: ".prompts-gpt/sweeps/security.md",
  iterations: 5,
  provider: "codex",
  eval: {
    criteria: ["correctness", "completeness"],
    passThreshold: 0.8,
  },
});

Summary

• run: One prompt, one shot, one result. Fast and stateless.
• run-batch: Multiple prompts, sequential, independent. Good for CI.
• sweep: One prompt, many iterations, context-chained. Deep and thorough.

Choose run for speed, run-batch for breadth, and sweep for depth.

See Also

• Run CLI
• Run-Batch CLI
• Sweep CLI
• Runtime API
• Sweep API