🌀 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/.
| 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 a lightweight plan, guided next actions, command-backed proof, a quality gate, and a final evidence report. 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 ask for loopy research, deep research, exhaustive investigation, or a cited report. |
Research axes, expansion waves, a 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 build, style, or redesign any UI/page/component, or ask to make something look designed (auto-activates on visual work). | A DESIGN.md token contract, an anti-slop pre-flight result, and a real-browser visual-QA evidence artifact. |
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/. |
The loop skill is the default guardrail. loopy starts or resumes the evidence loop; loopy team escalates to crew mode. loopywork, lpy, and $lpy only inject starter guidance. Research and clone are opt-in specialist modes, and both still finish by recording Superloopy evidence instead of trusting a status sentence.
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.
The crew
For bigger work, Superloopy ships six optional subagents — each owns one lane (.codex/agents/*.toml on Codex, bundled agents/*.md on Claude Code). They come with the plugin (no command needed); on Codex, superloopy agents install just re-copies them if you ever need it. Their advisory model defaults are documented in docs/superloopy-model-policy.md (Codex) and docs/superloopy-model-policy-claude.md (Claude Code), and checked by superloopy doctor.
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 before the normal handoff or fleet status. It follows the user's language from the assignment or scoped brief when it matches the supported catalog, with English as the safe fallback. The line is personality only; the verdict, evidence artifact, outstanding list, and attention list stay authoritative.
Works with Superpowers
Superloopy sits well next to the Superpowers plugin. They handle different halves of the same job, so you don't have to choose one.
- Superpowers runs the front of the loop: brainstorming, planning, and its TDD and code-review methodology.
- Superloopy runs the finish: command-backed criteria that re-run at completion, so "done" is proven, not just claimed.
When Superpowers is installed (on Codex or Claude Code), Superloopy notices and steers its own guidance to match. It leaves design, planning, and TDD to Superpowers and keeps itself as the outer evidence gate. Detection is best-effort and only shapes advice; it never weakens a gate. Set SUPERLOOPY_SUPERPOWERS=off to opt out or on to force it, and run superloopy doctor to see what was found. More in docs/superloopy-interop-superpowers.md.
Q&A
- Do I need both? No. Superloopy works on its own. If Superpowers is there too, the two coordinate instead of overlapping.
- Which stage does each own? Superpowers owns brainstorm, plan, and build. Superloopy owns the proof at the end. Keep one driver per task: don't run
loopy teamand the Superpowers subagent flow on the same slices at once. - Who decides a task is done? Superloopy. Its check re-runs the real command at the end and blocks a false pass.
- How is Superpowers detected? By looking in your Codex and Claude Code plugin folders. You can always override with
SUPERLOOPY_SUPERPOWERS=on|off.
Install
Superloopy installs on both Codex and Claude Code from one repo. The core (loop state, evidence gates, doctor) is host-agnostic; each host gets its own thin plugin manifest, hook wiring, and agent format.
Codex
Needs Node.js ≥ 20 and Codex CLI ≥ 0.131.0 for codex plugin add. Superloopy is dependency-free — zero runtime dependencies, just Node.
codex plugin marketplace add https://github.com/beefiker/superloopy
codex plugin add superloopy@beefiker
Restart Codex after installing the plugin. If Codex asks you to review hooks, approve them; the next approved session runs a SessionStart hook that does a one-time bootstrap — it installs the superloopy command and the agents. If superloopy isn't found, its folder isn't on your PATH; the bootstrap prints the exact line to add. Check everything with superloopy doctor.
Installing from a checkout instead? Run node src/cli.js install --json.
Claude Code
Needs Node.js ≥ 20. From the same repo:
/plugin marketplace add beefiker/superloopy
/plugin install superloopy@beefiker
Reload plugins (or restart Claude Code) and approve the hooks when prompted. On Claude Code the skills, subagents (agents/*.md), and hooks (hooks/hooks.json) are plugin-bundled — there is no ~/.codex install step and no superloopy wrapper; the hooks invoke the CLI directly via ${CLAUDE_PLUGIN_ROOT}, and SessionStart is a clean no-op (nothing to boot