/synthex:loop/synthex:loop

#What it does, end-to-end

/synthex: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. Reads the prompt from either --prompt <string> (literal) or --prompt-file <path> (file contents).
2. Increments and persists the iteration counter in .synthex/loops/<loop-id>.json before doing work. That's the durability boundary — a crash here costs one iteration of work, never the counter.
3. Prints the iteration marker [loop <loop-id> iteration N/M] to stdout.
4. Runs the prompt in the same agent thread (shared-context, the default) or in a fresh sub-agent via the Task tool (--loop-isolated).
5. Scans the iteration's final response for the literal <promise>X</promise> XML tag (same convention as the Ralph Loop plugin). On match: marks completed, exits.
6. Re-reads the state file. If another session set status: cancelled, exits. Otherwise loops back to step 2.

#Parameters

#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 /synthex: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> 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 waits for human input mid-iteration, the loop just keeps re-running the prompt until the human responds.
• Mutate .claude/ralph-loop.local.md. The Ralph plugin's state file is owned by Ralph; native looping never touches it. See Coexistence with Ralph Loop.
• Auto-create .synthex/. If the directory exists (because /synthex: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

• Native looping — the full framework explainer.
• /synthex:list-loops/synthex:list-loops — enumerate loops in the project.
• /synthex:cancel-loop/synthex:cancel-loop — cancel a loop by id or --all.
• Upstream spec: plugins/synthex/docs/native-looping.md.