🌀 Superloopy

Loop engineering for Codex and Claude Code. Type loopy <task> — an agent does the work, proves each piece with real evidence, and only then says it's done.

the crew — optional subagents, one job each

Use it

After installing, type your task in Codex or Claude Code with a leading loopy:

loopy add the payments module

The agent plans it, proves each piece with a real file, and reports back — you don't run any commands yourself. The packaged Stop hook stays quiet unless SUPERLOOPY_STOP_HOOK=on.

Why Superloopy?

Superloopy is for Codex and Claude Code work where "done" needs to mean more than a confident status sentence.

• Evidence-first: every pass points at a real artifact under .superloopy/evidence/.
• Lightweight by default: one small CLI, repo-local state, zero runtime dependencies.
• Agent-friendly: skills, hooks, and optional crew lanes guide the agent without hiding the final gate.

Guarantee scope. Command-backed criteria are the strong guarantee: at completion Superloopy re-runs each command in-process and requires it to reproduce, so a stale or fabricated pass cannot reach "done". Manual (commandless) criteria are verified as a non-empty evidence artifact plus auditor/human judgment — their correctness rests on review, not the deterministic re-run.

Skills

Superloopy keeps the command layer small. Skills carry the specialist workflow: when to use it, what the agent should inspect, and what proof must be left under .superloopy/evidence/.

The loop skill is the default guardrail. A complete leading loopy token starts or resumes the evidence loop; loopy team escalates to crew mode. Leading loopywork, lpy, and $lpy tokens only inject starter guidance. Structured SUPERLOOPY_STEER directives can adjust an active loop. The prompt hook does not infer frontend or Korean-writing modes from ordinary text; invoke specialist skills explicitly or let an already-active loop route a real specialist subtask.

Clone Demo

superloopy-clone reproduced Transferloom.com locally and passed desktop/mobile browser validation. The reference run preserved the sticky nav, animated hero, app preview sections, comparison table, security panel, sister app banner, footer, local assets, and Superloopy evidence trail.

Slides Demo

superloopy-slides generated this live multilingual deck → — a zero-dependency single-file HTML presentation on a fixed 16:9 stage in English · 한국어 · 中文 · 日本語 · Español. It passed real-browser visual-QA (standalone, phone letterbox, and iframe embed) recorded under .superloopy/evidence/slides/.

Qt Kanban Demo

The Northstar Qt Kanban demo is a runnable Qt Quick prototype acceptance fixture built through the superloopy-frontend Qt route, not production-editor proof. Board, search, filters, cards, drawers, and task creation are exercised; Timeline and Inbox are visibly passive demo-only context, Settings and Help are absent, and persistence and Undo remain out of scope. With Qt 6.11.1, CMake, and Ninja available, configure, build, and launch it from the repository root:

qt-cmake -S examples/qt-kanban -B build/qt-kanban -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build/qt-kanban --parallel
build/qt-kanban/src/app/qtkanban --window-size 1600x1000

# macOS: verify the exported native accessibility contract
examples/qt-kanban/scripts/audit-macos-accessibility.sh \
  build/qt-kanban/src/app/qtkanban

The crew

For bigger work, Superloopy ships six optional subagents — each owns one lane. Claude Code uses the plugin-bundled agents/*.md. On Codex, bootstrap, superloopy install, and superloopy agents install materialize personal TOMLs under $CODEX_HOME/agents; model routing is resolved during that installation step.

Codex calls the stable model/list method only when resolution state is missing, the policy version or target changed, the cache is at least 24 hours old, or --refresh-models is supplied. When fresh state still matches the managed files, it reuses the exact manifest without a query or state rewrite. Profiles select the first supported complete model/effort/tier tuple: gpt-5.6-terra / high / priority for standard, gpt-5.6-sol / xhigh / priority for deep, and gpt-5.6-luna / low / fast for fast. If a preferred model is unavailable, that profile uses its explicit gpt-5.5 compatibility tuple. An unknown first probe conservatively selects policy compatibility; an unknown refresh preserves a valid existing resolution. --compat makes the compatibility choice deterministically without querying.

Upgrades from pre-managed Superloopy releases are hash-bound: a complete exact legacy fleet is adopted and upgraded without --force, while one edit, symlink, missing file, or unknown hash keeps the whole fleet in conflict. Changed agent definitions require a Codex restart; an unchanged fresh manifest does not. superloopy doctor --refresh-models can report preferred availability before managed state exists, detects a wrapper/plugin split-brain, and never rewrites resolution state or agent files.

Resolution finishes before launch, with no post-launch retry or model switch. The TOML pins configure routing, but a host that does not expose agent_type plus resolved-model attestation remains model_unverified; Superloopy never presents that as a proven GPT-5.6 runtime gate. The policy details are in docs/superloopy-model-policy.md (Codex) and docs/superloopy-model-policy-claude.md (Claude Code).

Installed-plugin truth. installedPluginTruth runs the read-only codex plugin list --json authority probe. A confirmed superloopy@beefiker version mismatch is informational in source scope, but fails installed scope. Missing Codex, no registered plugin, and invalid authority output stay informational and do not fail doctor. Never infer the installed version from cache directory names or repair without approval.