DOCS · REFERENCE · COMMANDS · BUILD

loop/synthex:loop

Build

Native looping primitive — iterate any prompt until a completion promise fires or max-iterations hits.

Invocation

Run from inside Claude Code in any project where Synthex is installed:

/synthex:loop

Some commands accept parameters; see the source-of-truth file linked below for the full parameter list and workflow.

Lifecycle phase

Build. Parallel-executed, peer-reviewed task delivery.

  • Tech Lead · Full-stack orchestrator. Breaks tasks down, delegates to specialists, rolls up the result.
  • Lead Frontend Engineer · Coordinates frontend delivery, enforces UX quality, accessibility, and design-system fidelity.
  • Architect · System design, ADRs, plan-review feasibility, technology trade-offs.
  • Code Reviewer · Craftsmanship review — correctness, maintainability, reuse, conventions.
  • Security Reviewer · Mandatory gate. Secrets, injection, auth, supply chain, OWASP.
  • Quality Engineer · Test strategy, gap analysis, behavior-driven test authoring.
  • Design System · Token ownership, component governance, compliance audit.
  • Technical Writer · API docs, guides, migrations, changelogs verifiable against code.

Source

The command's parameters, workflow, and sub-agent invocations are defined in markdown at bluminal/lumenai/blob/main/plugins/synthex/commands/loop.md.

Last modified:

What it does, end-to-end

loop/synthex:loop is the generic native-looping primitive. It iterates an arbitrary prompt — literal text or the contents of a file — until the agent emits a configured completion promise or the iteration cap fires. The iteration framework is shared across every loop-bearing command and documented at the Native looping concept page; this reference covers only the command-specific bits.

Each iteration:

  1. Advances the loop with one script call. It checks the loop is still running (a cancelled or exhausted loop stops here), increments and persists the iteration counter in .synthex/loops/<loop-id>.json before doing work, and prints the iteration marker [loop <loop-id> iteration N/M]. That's the durability boundary — a crash costs one iteration of work, never the counter.
  2. Runs the prompt — either --prompt <string> (literal) or the contents of --prompt-file <path> — in the same agent thread (shared-context, the default) or in a fresh sub-agent (--loop-isolated).
  3. Scans the iteration's final response for the literal <promise>X</promise> XML tag. On match: marks completed, exits.
  4. Waits if the iteration had nothing to do. When the prompt is waiting on an external change, the loop blocks in place until a watched file changes, the loop is cancelled, or a backoff timeout passes (60s → 120s → 300s → 540s). The wait doesn't use up an iteration.
  5. Continues in the same turn back to step 1.

On Claude Code, native_looping.engine: workflow moves the "is it done?" decision to a read-only workflow run — see Workflow engines.

Parameters

ParameterDescriptionDefaultRequired
--prompt <string>Literal prompt text to loop. Mutually exclusive with --prompt-file.—One of --prompt / --prompt-file / --resume*
--prompt-file <path>Path to a file whose contents become the prompt. Mutually exclusive with --prompt.—One of --prompt / --prompt-file / --resume*
--completion-promise <string>Literal text the agent emits inside <promise>…</promise> to terminate the loop.ALLDONE<session_id> (falls back to ALLDONE<loop_id>)No
--max-iterations <int>Iteration cap. Hard ceiling 200.20No
--loop-isolatedSpawn a fresh sub-agent per iteration (no shared context). Slower, pricier, isolated.off (shared-context default)No
--name <slug>User-supplied loop-id (^[a-z0-9][a-z0-9-]{0,63}$).auto-generated loop-<4-char-hex>No
--resume <loop-id>Resume a running loop. Re-uses persisted prompt/promise/max-iterations.—No
--resume-lastResume the most-recent running loop in this project (FR-NL27 selection rules).—No

Examples

Loop an arbitrary prompt

/synthex:loop \
  --prompt "Audit the codebase for unused imports and fix any you find." \
  --completion-promise "AUDIT_CLEAN" \
  --max-iterations 10

Loop a prompt stored in a file

/synthex:loop \
  --prompt-file ./prompts/migrate-tests.md \
  --completion-promise "MIGRATED" \
  --name test-migration

Resume after closing Claude Code

/synthex:loop --resume test-migration
# or, if you don't remember the name:
/synthex:loop --resume-last

Run in isolation mode (fresh context per iteration)

/synthex:loop \
  --prompt-file ./prompts/sensitive-task.md \
  --completion-promise "DONE" \
  --loop-isolated

Use --loop-isolated when prior iterations' conversation actively interferes with subsequent ones — typically long-running prompts where context-bleed produces hallucinated references to earlier outputs.

Refusal paths

The command refuses (with a clear single-line error) for:

  • No prompt source AND no resume. Pass --prompt, --prompt-file, --resume <id>, or --resume-last.
  • --prompt and --prompt-file both supplied. Mutually exclusive.
  • --prompt-file <path> doesn't exist. Error names the path.
  • --max-iterations outside [1, 200] or non-integer. The 200 hard ceiling is a runaway-protection guarantee.
  • --resume <loop-id> for an unknown loop. Run list-loops/synthex:list-loops to see loops in this project.
  • --resume <loop-id> for a terminal-status loop (completed / cancelled / max-iterations-reached / crashed). Start a new loop instead.
  • --name <slug> that is already a running loop. The error tells you to --resume <slug> or cancel it.
  • --name <slug> violating the loop-id pattern (must match ^[a-z0-9][a-z0-9-]{0,63}$). The error names the offending characters.
  • --resume with a new prompt source supplied alongside. Resume re-uses the persisted prompt; do not pass --prompt or --prompt-file.

What it does not do

  • Bypass [H] user-input gates. If your prompt asks for human input mid-iteration, the loop waits for your answer before continuing.
  • Auto-create .synthex/. If the directory exists (because init/synthex:init has been run), the loop adds .synthex/loops/ lazily. If .synthex/ doesn't exist, the loop creates .synthex/loops/ directly — <SlashCommand verb="init" /> is not a prerequisite.

See also