Superloopy
A lightweight loop harness that makes Codex and Claude Code prove "done" with real evidence instead of a confident status line.
- Source repo
- beefiker/superloopy
- Stars
- ★ 115
- Last updated
- 7d ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 55/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Engineers doing multi-step refactors in Codex or Claude Code who want every step backed by reproducible evidence
- Not a fit if
- Teams wanting a harness fully independent of Codex or Claude Code
- Teams expecting full project management beyond the evidence gate
- Teams unwilling to keep .superloopy state and evidence files in repos
- Source review
- 55/100 · Major gaps
What does this agent do, and when should you use it?
Superloopy is a loop harness for Codex, Claude Code, and Google Antigravity: you type a task with a leading loopy, and the agent plans it, proves each piece with a real artifact, and only then reports completion. It ships as thin plugins per host — on Codex through the plugin marketplace with a one-time SessionStart bootstrap that installs the superloopy command and six crew agents, and on Claude Code fully plugin-bundled with skills, agents/*.md, and hooks/hooks.json and no ~/.codex writes. Loop state and proof live under .superloopy/evidence/ inside the repository, and the CLI has zero runtime dependencies beyond Node.js. The strong guarantee is command-backed criteria: 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 rest on an evidence artifact plus auditor or human review. Optional specialist skills and a six-agent crew cover research, backend, frontend, cloning, slides, and Korean writing.
After install, typing loopy <task> in a host session starts a full loop: the agent produces a lightweight plan, executes the work, writes proof for each pass into .superloopy/evidence/, and ends with an evidence report. loopy team <task> (also loopy crew, loopycrew, or ultrawork <task>) fans work out in parallel to the optional subagents forge, sentinel, probe, arbiter, assayer, and pathfinder. loopywork, lpy, and $lpy inject starter guidance without mutating state, and structured SUPERLOOPY_STEER directives adjust an active loop. The CLI records crew lanes with superloopy loop handoff, inspects them with superloopy loop fleet --json, and submits JSON quality gate output via superloopy loop finish --artifact. Skills such as superloopy-loop, superloopy-doctor, superloopy-research, superloopy-backend, superloopy-clone, superloopy-frontend, superloopy-slides, humanize-korean, i-have-adhd, and say-it-straight each define when they activate, what the agent inspects, and what evidence must be left behind. superloopy doctor is a read-only health report that probes installed-plugin truth through codex plugin list --json and prints the exact repair command without rewriting agent files or resolution state. The packaged Stop hook keeps a session going only after a loopy loop is started or resumed.
- Engineers doing multi-step refactors in Codex or Claude Code who want every step backed by reproducible evidence
- Team leads who want "done" to be an auditable quality gate rather than the agent's own status sentence
- Teams splitting large tasks across parallel specialist subagents and collecting a single evidence trail
- Frontend developers doing authorized website cloning and pixel-focused recovery, validated with desktop and mobile browser captures
- Backend teams handling migrations and runtime database-agent work with the
superloopy-backendcommand-backed evidence rules - Korean content authors removing AI tone from product copy, or demo builders generating a single-file HTML deck with
superloopy-slides
How do you install or deploy this agent?
Requires Node.js ≥ 22. One command finds claude, codex, agy, and omp on your PATH, asks before installing into each, and uses each host's own plugin commands:
npx superloopy@latestNon-interactive setup, update, and health check:
npx superloopy@latest setup --host claude,codex --yes
npx superloopy@latest update
npx superloopy@latest doctorManual Codex install (Codex CLI ≥ 0.131.0 required); restart Codex afterward and approve hooks:
codex plugin marketplace add https://github.com/beefiker/superloopy
codex plugin add superloopy@beefikerManual Claude Code install (≥ 2.1.280 required); reload plugins and approve hooks afterward:
/plugin marketplace add beefiker/superloopy
/plugin install superloopy@beefikerInstalling from a checkout instead:
node src/cli.js install --jsonHow do you use this agent?
Once installed, type your task in the host session with a leading loopy; you do not run any commands yourself:
loopy add the payments moduleEscalate to parallel crew mode when the slices are independent:
loopy team <task>Proof and loop state live in .superloopy/evidence/ inside the repository. Command-backed criteria are re-run in-process by the completion gate, which accepts JSON quality gate output:
superloopy loop finish --artifact <gate.json>Diagnose install, wrapper, plugin cache, hook, or stale-version problems with the read-only doctor:
superloopy doctorOptional environment variables: SUPERLOOPY_STOP_HOOK=on|off controls Stop-hook continuation, SUPERLOOPY_SUPERPOWERS=on|off overrides Superpowers detection, and SUPERLOOPY_CALQUE_NUDGE=on adds an advisory note when a previous Korean reply carried an English calque.
What are this agent's strengths and limitations?
- Command-backed criteria are re-run in-process at completion, so stale or fabricated passes cannot reach "done"
- Zero runtime dependencies beyond Node.js, with state and evidence kept repo-local under
.superloopy/ - One repo supports Codex, Claude Code, and Google Antigravity via thin per-host manifests, hooks, and agent formats
- Explicit division of labor with Superpowers: it owns brainstorm, plan, and TDD, while Superloopy owns the final evidence gate
superloopy doctoris read-only, detects wrapper/plugin split-brain, and prints repair commands without rewriting state
- Manual (commandless) criteria cannot be deterministically re-run; their correctness depends on auditor or human review
- Repo-local
.superloopy/state and evidence artifacts leave extra files in the working tree - Codex installs need Codex CLI ≥ 0.131.0 and hook approval; older builds can fail on plugin and hook flows
- On omp, Claude-format
hooks.jsonis not executed, so there is no automatic Stop continuation, subagent receipt check, or SessionStart bootstrap - Without host attestation of
agent_typeand resolved model, the runtime staysmodel_unverifiedrather than a proven model gate
How does this agent compare with similar options?
Superpowers: Superloopy's README positions the two as different halves of the same job. Superpowers runs the front of the loop — brainstorming, planning, and its TDD and code-review methodology — while Superloopy runs the finish with command-backed criteria re-run at completion. When Superpowers is detected, Superloopy defers design, planning, and TDD to it and keeps itself as the outer evidence gate; SUPERLOOPY_SUPERPOWERS=on|off overrides detection.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Superloopy This agent | 55 · Major gaps | Agent plugin / skillFree + model costs | ★ 115 | 7d ago | JavaScript | Codex · Claude Code |
| Autoprompt Skill | 69 · Some gaps | CLIFree + model costs | ★ 1.2k | 1mo ago | JavaScript | Codex · Claude Code |
| Smart Ralph | 73 · Some gaps | Agent plugin / skillFree + model costs | ★ 566 | 8d ago | Shell | Codex · Claude Code |
| OSpec | 50 · Major gaps | CLIFree + model costs | ★ 391 | 2mo ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
SECURITY.md openly states evidence capture executes agent-chosen commands with caller privileges, no allowlist or sandbox, by design, so least_privilege is 1; user confirmation exists for hook approval and doctor repairs but not per-command prove execution, scoring 1; data_flow_transparency only notes evidence under .superloopy/ without systematic data-flow description, 1; sensitive_data_handling has no dedicated mechanism beyond advising reports avoid real secrets, 1; dependency_security has zero runtime deps, Node-only, and CI pins action SHAs, 2; external_effects (writes to ~/.codex, ~/.local/bin, npm global) are documented but unisolated, 1; rollback has uninstall steps and a tested failed-commit restore path, 2; source_attribution has author, repository, MIT but copyright year lacks a named holder and publisher is unverified, 1.
self_consistency: README, package.json, hook tests and CI agree, 2; dependency_availability: zero runtime deps with explicit Node>=22 engine, 2; failure_messages: doctor gives read-only health reports and exact repair commands, with tests covering many failure messages, 2.
audience_and_scenarios: targets Codex/Claude Code/Antigravity with a detailed skill table, 2; capability_boundaries: clearly distinguishes command-backed vs manual evidence guarantees, 2; trigger_precision: skill activation and exclusion rules are detailed and tested, 2; environment_fit: cross-OS/Node CI matrix and multi-host wiring checks, 2.
information_architecture: clear but very long and duplicated across languages, 2; install_notes: per-host install/update/uninstall/troubleshooting is thorough, 3; naming_stability: agents were renamed (franky→forge etc.) with legacy cleanup, so naming has shifted, 1; examples_and_faq: has Q&A and demos but no standalone FAQ section, 2; known_limitations: states manual evidence relies on human judgment and backend effect unmeasured, 2; license: full MIT, 2; versioning_changelog: version number, version-guard and release flow but no CHANGELOG file, 2; maintenance_responsibility: single individual author, publisher unverified, 1.
output_usability: evidence written to .superloopy/evidence with gate JSON, 2; marginal_value: provides evidence gating and multiple skills but some effects are self-asserted, 2; cost_benefit: backend skill self-reports 1.7–1.8x output tokens, a clear cost, 1.
claim_traceability: README cites docs and demo links but key effect numbers lack raw data, 1; cross_source_corroboration: tests and CI partly corroborate behavior but effect claims lack cross-source support, 1; fact_inference_separation: README separates measured effects from unmeasured guidance, 2.
- Evidence capture runs agent-chosen commands with caller privileges and no sandbox; use only where that risk is acceptable.
- Publisher identity is unverified; review source and hook behavior before installing.
- The backend skill self-reports notably higher output token cost; weigh against benefit.
- Agents were renamed, so upgrades may leave stale files requiring manual cleanup per docs.
FAQ
Does it need API keys or a separate paid plan?
Can I use it without Superpowers?
SUPERLOOPY_SUPERPOWERS=on|off forces either behavior.When is the "done" guarantee weaker?
Is functionality complete on omp or Antigravity?
hooks.json is not run, so there is no automatic Stop continuation, subagent receipt check, or SessionStart bootstrap; the superloopy loop finish completion gate still re-runs every command-backed proof. Antigravity is updated in its plugin directory and validated with agy plugin validate.Will doctor change my setup?
superloopy doctor is a read-only health report; it surfaces failing checks and the exact repair command, which you must approve and run yourself.