<div align="center">

🌀 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.

<p> <a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">中文(简体)</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a> </p>

<img src=".github/assets/franky.png" width="92" alt="franky" /> <img src=".github/assets/zoro.png" width="92" alt="zoro" /> <img src=".github/assets/usopp.png" width="92" alt="usopp" /> <img src=".github/assets/jinbe.png" width="92" alt="jinbe" /> <img src=".github/assets/robin.png" width="92" alt="robin" /> <img src=".github/assets/nami.png" width="92" alt="nami" />

_{<b>the crew</b> — optional subagents, one job each}

</div>

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/.

| Skill | Use it when | What it produces | | --- | --- | --- | | superloopy-loop | You type loopy <task> or loopy team <task> for a full loop; use loopywork, lpy, or $lpy for guidance-only context. | Full loops produce direct, concise, complete progress and final responses alongside a lightweight plan, proof, quality gate, and final evidence report. Exact English/Korean controls affect only the current incomplete loop; new loops reset enabled. Guidance aliases do not mutate state. | | superloopy-doctor | You diagnose install, wrapper, plugin cache, hook/bootstrap, agent, Codex/Claude Code host wiring, or stale-version problems. | A read-only health report with wrapper/cache/version evidence, failing checks, and the exact repair command to run only if approved. | | superloopy-research | You explicitly invoke Codex $superloopy:superloopy-research or Claude Code /superloopy:superloopy-research, or start the research task with a leading loopy/루피 (such as loopy research). Plain research, investigate, or summarize requests do not activate it. | Research axes, expansion waves, a verdict on every retrieval, graded and dated sources, a priced claim ledger, verification notes, and a cited synthesis artifact. | | superloopy-clone | You ask for loopy clone, authorized website cloning, rebuilding, migration, or pixel-focused page recovery. | Browser captures, page topology, design tokens, asset inventory, implementation notes, build output, and visual QA evidence. | | superloopy-frontend | You explicitly invoke Codex $superloopy:superloopy-frontend or Claude Code /superloopy:superloopy-frontend for supported screen-based application UI across browser-hosted Web (public, authenticated, private/internal, installed PWA, or extension), interactive deployed content-led Web (campaign, publication, or landing experiences with a user journey), desktop, mobile/tablet, embedded/hybrid clients, custom-rendered UI, Qt, or mixed targets, or start that work with a leading loopy/루피. Plain UI, platform, or framework terms do not activate it; TV, wearable, XR, automotive, game UI, TUI, static media/document artifacts, and non-UI work stay excluded. | One shared UX contract plus platform/composition routes. Evidence is proportional to changed claims and independently covers each browser, native target/shell, renderer, and mixed target. Standalone runs retain run-scoped receipts; active loops bind them to the goal and criterion. | | humanize-korean | Use when Korean users ask to remove AI tone, fix 번역투, or make Korean text sound human without changing facts. | Writes final.md, summary.md, and audit.json; in Superloopy loops it records evidence under .superloopy/evidence/humanize-korean/. | | i-have-adhd | You explicitly invoke Codex $superloopy:i-have-adhd or Claude Code /superloopy:i-have-adhd, or a leading loopy/루피 brief directly asks for ADHD-friendly, action-first, one-step, or easy-to-scan output. Writing style alone never activates it. | Shapes progress updates so the next action stays visible. It does not create a Superloopy evidence artifact or weaken planning, safety, validation, or completion gates. | | say-it-straight | Explicit Codex $superloopy:say-it-straight or Claude /superloopy:say-it-straight for direct, concise, natural prose and supplied task artifacts; never activates from writing style alone. Full Loopy progress/final output is direct by default, with exact English/Korean controls limited to the current incomplete loop. | Explicit artifact editing preserves facts, register, protected text, and required detail; file-backed edits use the audit. ADHD owns structure and Korean rewriting remains with humanize-korean. | | superloopy-slides | You ask for slides, a presentation, a deck, or a PPT/PPTX-to-web conversion. | A zero-dependency single-file HTML deck on a fixed 16:9 stage, three style previews to pick from, and a rendered-screenshot visual-QA artifact under .superloopy/evidence/slides/. |

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. Full-loop direct output never silently rewrites supplied prose or task artifacts: direct editing remains explicit-only. 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.

<table> <tr> <td align="center" width="33%"><img src=".github/assets/franky.png" width="190" alt="franky" /><br /><b>franky</b><br />_{builds it}</td> <td align="center" width="33%"><img src=".github/assets/zoro.png" width="190" alt="zoro" /><br /><b>zoro</b><br />_{reviews it}</td> <td align="center" width="33%"><img src=".github/assets/usopp.png" width="190" alt="usopp" /><br /><b>usopp</b><br />_{tests it}</td> </tr> <tr> <td align="center"><img src=".github/assets/jinbe.png" width="190" alt="jinbe" /><br /><b>jinbe</b><br />_{gates it}</td> <td align="center"><img src=".github/assets/robin.png" width="190" alt="robin" /><br /><b>robin</b><br />_{audits it}</td> <td align="center"><img src=".github/assets/nami.png" width="190" alt="nami" /><br /><b>nami</b><br />_{finds it}</td> </tr> </table>

Summon the crew with loopy team <task> — or `lo