Superloop

superloop is a host-agnostic harness for iterative agent work.

The core idea is simple:

• the user acts as CEO
• the coding agent acts as the execution worker
• the mission, scope, budget, and stop rule are made explicit
• the harness keeps iterating through execution rounds until the goal is achieved or the agreed round or time budget is spent

This repo includes one ready-to-run implementation for local skill environments today, but the operating model itself is tool-agnostic.

What is in this repo

• SKILL.md: the main operating contract
• agents/openai.yaml: Codex/OpenAI-host metadata for the skill picker
• docs/index.md: the main docs entry point
• docs/: host-specific install notes, core concepts, and CLI reference
• references/: deeper operating-model notes for mission contracts, loop protocol, finish standards, and workstream gates
• src/superloop/: importable harness implementation
• scripts/superloop_cli.sh: shell entrypoint for the harness
• scripts/superloop_cli.ps1: native PowerShell entrypoint for Windows
• scripts/superloop_harness.py: compatibility wrapper for older commands
• scripts/install.sh: host-aware install/sync wrapper
• scripts/install.ps1: native PowerShell install/sync wrapper for Windows

Architecture

Generated with GPT Image for a README-friendly overview of the runtime flow.

The runtime split is intentional:

• SKILL.md and references/* define the operating contract
• superloop_cli.sh is the stable shell entrypoint
• src/superloop/cli.py owns persisted state, round recording, budget tracking, status cards, and stop-audit decisions
• scripts/superloop_harness.py keeps the old command path working by importing the package
• the target workspace stays separate from the harness state file

Install

Choose the host you want to use:

# Codex
./scripts/install.sh --host codex

# Claude Code
./scripts/install.sh --host claude-code

# Generic CLI copy under ~/.superloop/superloop
./scripts/install.sh --host generic

On Windows PowerShell, use the native wrappers:

# Codex
.\scripts\install.ps1 --host codex

# Claude Code
.\scripts\install.ps1 --host claude-code

# Generic CLI copy under $env:USERPROFILE\.superloop\superloop
.\scripts\install.ps1 --host generic

The installed copy can be checked later:

./scripts/superloop_cli.sh doctor --host codex
./scripts/superloop_cli.sh doctor --host claude-code
./scripts/superloop_cli.sh doctor --host generic

.\scripts\superloop_cli.ps1 doctor --host codex
.\scripts\superloop_cli.ps1 doctor --host claude-code
.\scripts\superloop_cli.ps1 doctor --host generic

Start with docs/index.md. Host-specific notes live in:

• docs/install-codex.md
• docs/install-claude-code.md
• docs/install-generic-cli.md
• docs/install-windows.md
• docs/host-adapters.md
• docs/reference/cli.md

Quick start

Run the harness directly from the source checkout or from the installed host path:

export SUPERLOOP_HARNESS="$(pwd)/scripts/superloop_cli.sh"

Windows PowerShell:

$env:SUPERLOOP_HARNESS = Join-Path $PWD "scripts\superloop_cli.ps1"

Resume an existing run:

"$SUPERLOOP_HARNESS" resume --workspace /path/to/repo

& $env:SUPERLOOP_HARNESS resume --workspace C:\path\to\repo

If the ask changed in the same workspace, do not silently continue the loaded run. Call init without --continue-existing and Superloop will archive the previous run before it starts a fresh mission.

Render the next-round runtime context:

"$SUPERLOOP_HARNESS" context --workspace /path/to/repo

context converts the stored contract, budget, active round, remaining gaps, and completion audit checklist into a prompt-shaped handoff for the next agent turn.

Initialize a new run:

"$SUPERLOOP_HARNESS" init \
  --workspace /path/to/repo \
  --goal "Ship the first usable version of this workflow" \
  --workstream "repo workflow" \
  --finish-standard workflow-ready \
  --scope "code, docs, smoke checks" \
  --required-evidence check \
  --max-rounds 5 \
  --timebox-minutes 90

Intentionally keep the same mission and merge updated contract fields:

"$SUPERLOOP_HARNESS" init \
  --workspace /path/to/repo \
  --goal "Tighten the current mission without resetting history" \
  --continue-existing

Preflight a risky stage:

"$SUPERLOOP_HARNESS" preflight \
  --workspace /path/to/repo \
  --stage deploy \
  --require-env VERCEL_TOKEN \
  --require-env VERCEL_PROJECT_ID \
  --optional-env SENTRY_AUTH_TOKEN

Record a round:

"$SUPERLOOP_HARNESS" start-round \
  --workspace /path/to/repo \
  --hypothesis "Simplifying setup will unblock the main path" \
  --change "remove one blocking step and update the smoke check" \
  --round-gate "A fresh run completes once without manual rescue"

"$SUPERLOOP_HARNESS" verify \
  --workspace /path/to/repo \
  --name check \
  -- npm run check

"$SUPERLOOP_HARNESS" record \
  --workspace /path/to/repo \
  --round-gate-result hard-pass \
  --gate-status gate-complete \
  --require-evidence check \
  --next-round "tighten the fallback path and verify it"

Render the visible run ledger:

"$SUPERLOOP_HARNESS" timeline --workspace /path/to/repo
"$SUPERLOOP_HARNESS" report --workspace /path/to/repo --format json

Render a deploy or workflow status card and optionally sync it to GitHub:

"$SUPERLOOP_HARNESS" status-card \
  --workspace /path/to/repo \
  --stage deploy \
  --platform cloudflare \
  --require-env CLOUDFLARE_API_TOKEN \
  --github-repo owner/repo \
  --github-pr 12

Blocked rounds also carry a failure classification, stable failure signature, and repeat count so the loop can summarize repeated blockers instead of spending more budget on identical retries.

For terminal rounds, omit --remaining-gap or use a no-gap sentinel such as none. The harness now normalizes common values like none and no remaining gaps so a completed run stops cleanly instead of asking for another round.

For mission-complete rounds, include explicit --completion-evidence entries. This keeps the stop decision tied to proof instead of intent or partial progress. For gates that depend on tests or smoke checks, use verify and then require the result with record --require-evidence; otherwise the harness cannot distinguish between a real command run and an agent merely claiming it ran.

Contract model

The harness contract centers on:

• Goal
• Finish Standard
• Success Signal
• Success Direction
• Current Gate
• Scope
• Constraints
• Required Evidence
• Stop Rule
• Max Rounds
• Timebox Minutes

That contract is what lets the agent behave like an accountable execution worker instead of a one-shot assistant.

In practice, this behaves more like an auto research or vibe coding harness than a one-shot coding command: the CEO keeps the mission and constraints stable, the coding agent keeps shipping rounds, and the harness keeps the loop honest.

State model

By default, the harness stores state outside the target workspace. The path is host-aware:

SUPERLOOP_STATE_HOME/<workspace-key>.json
SUPERLOOP_HOME/state/<workspace-key>.json
Codex: ~/.codex/state/superloop/<workspace-key>.json
Claude Code: ~/.claude/state/superloop/<workspace-key>.json
Generic CLI: ~/.superloop/state/<workspace-key>.json

Archived prior runs for the same workspace live under:

~/.codex/state/superloop/history/<workspace-key>/

That lets the loop resume across turns, start a safe new mission in the same repo, and keep old runs audit-friendly without dirtying the repo it is working on.

When to use Superloop

Use superloop when you want the agent to:

• keep a mission stable across rounds
• separate Round Gate, Current Gate, and Stop Rule
• spend a visible round or time budget
• verify each round mechanically
• keep or discard changes based on evidence
• stop for either success, stop rule, or budget exhaustion
• classify blocked rounds and preflight required environment variables

Do not use it for:

• narrow one-off fixes
• pure brainstorming with no execution loop
• tasks where every round still depends on repeated human intervention

Development

Useful checks while editing this repo:

python3 -m py_compile scripts/superloop_harness.py
python3 -m py_compile src/superloop/cli.py
./scripts/superloop_cli.sh resume --workspace "$(pwd)"
./scripts/superloop_cli.sh doctor --host codex --source "$(pwd)"
./scripts/superloop_cli.sh doctor --host claude-code --source "$(pwd)"

On Windows PowerShell:

python -m py_compile scripts\superloop_harness.py
python -m py_compile src\superloop\cli.py
.\scripts\superloop_cli.ps1 resume --workspace $PWD
.\scripts\superloop_cli.ps1 doctor --host generic --source $PWD

If the second command returns a warning about missing state, that is expected for a fresh workspace.