🌀 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 acceptance fixture built through the superloopy-frontend Qt route. 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).

Summon the crew with loopy team <task> — or loopy crew, the one-word loopycrew, or just ultrawork <task>. Superloopy fans the work out across the lanes in parallel and still proves every piece before it calls it done. A plain loopy <task> stays solo and only delegates when the slices are clearly independent.

For full crew runs, the parent records each lane with superloopy loop handoff, checks superloopy loop fleet --json, and keeps the human final gate report separate from the machine gate JSON. A gate report can be Markdown evidence; superloopy loop finish --artifact is for .json quality gate output.

When a tracked crew handoff finishes, Superloopy can print one original crew line