Ultra Loop is a portable skill for running complex work through a durable, multi-agent protocol. It keeps requirements discovery, planning, implementation, independent criticism, and final verification separate so a task closes only when the evidence supports it.
Complex work often fails at the handoffs: an incomplete request becomes an invented plan, a worker reviews its own result, or a reassuring summary is mistaken for proof. Ultra Loop makes those handoffs explicit and persists enough state to resume a run honestly.
It adds verified completion, interrogation, planning clarification, durable state, capability-aware roles, and independent critic gates. It is not a promise that every task can complete: a missing capability, permission, input, or check is reported as a blocker.
- The Interrogator turns the request into a versioned requirements specification and identifies remaining unknowns.
- The Orchestrator creates a dependency-aware implementation plan or returns a clarification packet; it does not invent missing inputs.
- Workers execute disjoint assignments. A fresh, independent Critic reviews each artifact and its evidence. Workers cannot approve their own work.
- The supervisor integrates only currently approved artifact/evidence versions, then performs final verification.
flowchart TB
U[User task] --> I["Lead Interrogator<br/>Higher-cost lead model"]
I --> R[Clear requirements]
R --> O["Lead Orchestrator<br/>Higher-cost lead model"]
subgraph P["Parallel task lanes — scale as needed"]
direction LR
W1["Worker 1<br/>Economical capable model"] --> C1["Critic 1<br/>Economical capable model"]
W2["Worker 2<br/>Economical capable model"] --> C2["Critic 2<br/>Economical capable model"]
WN["Worker N<br/>Economical capable model"] --> CN["Critic N<br/>Economical capable model"]
end
O --> W1
O --> W2
O --> WN
C1 -.->|REVISE| W1
C2 -.->|REVISE| W2
CN -.->|REVISE| WN
C1 -->|APPROVE| G["Lead Orchestrator integrates approved work<br/>Higher-cost lead model"]
C2 -->|APPROVE| G
CN -->|APPROVE| G
O -->|Missing information| I
G --> F{"Final verification<br/>Higher-cost lead model"}
F -->|Every gate passes| V[VERIFIED]
F -->|A required gate cannot complete| B[BLOCKED]
classDef lead fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
classDef economy fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef neutral fill:#f8fafc,stroke:#64748b,stroke-width:1px,color:#0f172a
class I,O,G,F lead
class W1,W2,WN,C1,C2,CN economy
class U,R,V,B neutral
The terminal verdict is exactly VERIFIED when every required gate has direct evidence, or BLOCKED when a required gate cannot be completed. Neither a partial test run nor an unavailable check is an approval.
Interrogation is the normal place for user questions. Once the requirements are complete, Ultra Loop enters an autonomy lock: it plans, implements, debugs, revises, integrates, and verifies independently. It does not ask for routine preferences or confirmation. It returns to the user only for a material stopper: a critical-path decision or action that cannot be safely inferred, cannot be resolved through authorized discovery or reasonable alternatives, and would otherwise risk a materially different outcome, an authorization/safety violation, irreversible impact, unapproved external commitment, or an unavailable dependency only the user can unlock.
Ultra Loop installs as a portable skill for three hosts:
- Claude Code — invoked explicitly as
/ultra-loop <task>through the installed command shim. - Codex — invoked explicitly as
$ultra-loop <task>. - Hermes — invoked explicitly by asking for Ultra Loop by name (for example,
use ultra-loop for <task>). Hermes is provider-agnostic and runs any model, so on Hermes Ultra Loop resolves two model tiers: a lead tier (high-reasoning, higher-cost model for the interrogator, orchestrator, integration, and final verification) and a worker tier (economical, lower-cost model for workers and critics). See Model selection.
Paste the following request into either Codex or Claude Code. It installs Ultra Loop globally for both Codex and Claude Code using the repository's validated installer:
Install Ultra Loop globally for both Codex and Claude Code from
https://github.com/jperezduerto/ultra-loop.
Confirm Git and Python 3.11 or newer are available. Clone the repository into
a new temporary directory, read its README, and inspect the platform-appropriate
installer before running it. Do not pipe a remote script into a shell.
Run the documented dry run first. If and only if validation succeeds, run the
installer with its default global destinations. Do not bypass validation,
permission boundaries, or make unrelated configuration changes.
Verify the installed Claude command and skill and the installed Codex skill.
Report their exact locations, any backups created, and these invocation forms:
/ultra-loop <task> for Claude Code and $ultra-loop <task> for Codex.
Stop and explain any dependency, validation, permission, or platform failure.
After successful verification, remove only the temporary checkout created for
this installation. If either host does not discover the new skill immediately,
tell me to restart it or open a new session.
The request authorizes only the documented installation and its temporary checkout cleanup. Review the agent's dry-run output before it proceeds if you want to inspect the destination paths yourself.
The installer requires Python 3.11 or newer available as python, python3, or the Windows py -3 launcher. Clone this repository, then use PowerShell from its root. The dry run semantically validates the source package and prints the destinations without copying anything:
.\install.ps1 -SourceRoot $PWD -DryRunTo install, run:
.\install.ps1 -SourceRoot $PWDThe installer validates strict skill metadata, direct package references, host metadata, the command shim, and Python helper interfaces. It then stages and semantically validates each copy before any backup or promotion, installs the Claude command and skill plus the Codex skill, and creates timestamped backups before replacing an existing installation. You can choose isolated or non-default locations with -ClaudeConfigDir and -CodexHome; use -WhatIf to have PowerShell preview the actual install action. To also install the Hermes skill, pass -HermesHome (for example -HermesHome (Join-Path $HOME ".hermes"), or your $HERMES_HOME when set).
The installer requires Python 3.11 or newer available as python3 or python. From the repository root, first preview the destinations:
./install.sh --source-root "$PWD" --dry-runThen install:
./install.sh --source-root "$PWD"Use --claude-dir PATH and --codex-dir PATH to select non-default host homes. The installer performs the same source and staged-copy semantic validation before promotion, and backs up an existing destination before replacement. To also install the Hermes skill, pass --hermes-dir PATH (for example --hermes-dir "$HOME/.hermes", or your $HERMES_HOME when set).
After installation, invoke the Claude command explicitly:
/ultra-loop <task>
Claude Code uses the installed command shim and the skill at ~/.claude/skills/ultra-loop/. The command is deliberately explicit: do not assume that ordinary conversation has activated the protocol.
After installation, invoke the Codex skill explicitly:
$ultra-loop <task>
Codex loads the skill from $CODEX_HOME/skills/ultra-loop/ (or ~/.codex/skills/ultra-loop/ when CODEX_HOME is unset). Codex does not use the Claude /ultra-loop command shim.
After installing with -HermesHome / --hermes-dir, Hermes loads the skill from $HERMES_HOME/skills/ultra-loop/ (or ~/.hermes/skills/ultra-loop/ when HERMES_HOME is unset). Invoke it explicitly by asking for Ultra Loop by name:
use ultra-loop for <task>
Hermes runs agents through its delegation toolset: the current session stays the supervisor, and the interrogator, orchestrator, workers, and critics run as distinct delegated subagents. Because Hermes is provider-agnostic, choose a lead tier and a worker tier from your configured models before or during the run; see Model selection.
Ultra Loop uses the host-visible model inventory as the authority. When exact inventory is visible, it selects only exact exposed identifiers. It records requested and selected models, fallbacks, rationales, and uncertainty, and never claims that a hidden identifier or rolling alias is a confirmed underlying model.
When Claude's inventory is opaque, Ultra Loop may use the rolling opus alias for lead roles and the rolling sonnet alias for worker and critic roles. It records those aliases, their fallback rationale, and uncertainty: true; it does not infer a dated model behind either alias. When a known inventory has no available capable model, Ultra Loop uses the host default with uncertainty: true. For Codex, that same fallback also applies when inventory is absent: it omits an explicit model override and uses the Codex host default. host-default is not a model identifier and is never passed as an override.
On Hermes, Ultra Loop resolves two explicit model tiers from the configured inventory instead of assuming one fixed model. It honors explicit overrides; otherwise it selects deterministically without interrupting the run for a preference:
- The lead tier (high-reasoning, higher-cost model) runs the lead interrogator, lead orchestrator, integration, and final verification.
- The worker tier (economical, lower-cost capable model) runs workers and critics.
You can pin either tier with an explicit per-run override, as long as the exact model is exposed, available, and capable of the role. When the Hermes inventory is absent or insufficient, Ultra Loop omits the override, uses the Hermes delegation default, and records uncertainty: true; Hermes has no rolling alias fallback.
A truthful uncertain fallback is valid. A run is BLOCKED only when a required capability is genuinely insufficient—for example, the host cannot create an independent critic while retaining supervision—not merely because the precise model identity is unobservable.
Run state is durable under .ultra-loop/runs/, with each run retaining its manifest, requirements, plans, task ledgers, artifacts, evidence, critic verdicts, and state transitions. It is excluded from Git by default; it is not encrypted or access-controlled. Resume only after validating the manifest, artifact versions, ownership, approval coverage, and the last complete transition. Publish only suitably derived material that you have explicitly reviewed and approved.
Ultra Loop follows the host's authorization, permission, sandbox, and approval boundaries; it never bypasses them. Run artifacts are excluded from Git by default; they are not encrypted or access-controlled, and may remain visible to local administrators, backups, or indexers. Do not place credentials, tokens, private keys, browser profiles, credential-manager data, or unrelated personal data in run artifacts. Treat summaries as navigation rather than proof, and publish only reviewed, derived material with sensitive information removed.
Ultra Loop requires a host that can create multiple independent agent contexts and a fresh critic context separate from each worker. It cannot manufacture unavailable tools, permissions, connectivity, models, user answers, or verification evidence. Model identifiers and runtime capabilities vary by host and may change. Long-running work can be resumed only from complete, internally consistent durable state; otherwise it is BLOCKED until the missing evidence or setup condition is resolved.
Run the public-package checks from the repository root:
python -m unittest discover -s tests -v
bash -n install.sh
& powershell.exe -NoProfile -Command '[void][scriptblock]::Create((Get-Content -Raw ./install.ps1))'The test suite exercises the installers only against temporary host homes. Do not run an installer against your real configuration while testing.
Ultra Loop is licensed under the MIT License. It was inspired by Gauntlet Loop; this project credits that upstream only for inspiration and any adapted wording actually present here. See THIRD_PARTY_NOTICES.md for the preserved upstream notice.