🪐 🔄 Prompt Queue Iterator

ComfyUI's queue is the iteration mechanism - there's no loop node you'd actually want to use for "run this workflow with prompt A, then B, then C." So the usual workaround is queueing the same workflow repeatedly and editing the prompt box between runs, which is exactly as error-prone as it sounds. This node turns one text box full of prompts into a queue pointer: every execution it hands out the next block, keeps the position on disk, and shows you Run 7 / 30 on the node.

If you're doing subject sweeps, batch character tests, or overnight prompt farming, this is the node that removes the manual step. It also just tells you exactly how many prompts you pasted, which is what you need to know before you set the queue count.

How it works

text is split into blocks by the separator you choose, the full text is hashed, and the current position is stored in a small JSON state file inside ComfyUI's user directory (user/default/SaturnNodes/prompt_iterator_state.json), keyed by the node id plus that text hash. So the pointer survives a restart - close ComfyUI mid-sweep and it picks up where it stopped.

Two behaviours are doing the heavy lifting:

The node re-executes every run. Its change check always reports "changed," which is the standard escape from ComfyUI's caching: nothing downstream of it gets to reuse a cached result, so your text encode genuinely re-runs and actually sees the new prompt. That's the point of the node - and also its cost, since anything expensive sitting downstream of it in the same branch re-runs for every prompt too.

Each queued prompt id is remembered. If the run is retried or recovered, the node hands back the same block rather than advancing the pointer again. It also trims its own state: only the three most recent text hashes per node are kept.

pop_mode decides what happens at the end of the list: Sequential (Loop on End) wraps to the top, Sequential (Stop on End) freezes on the last block once you run past the end, Random (Keep) picks a random block each run (duplicates allowed), and Random (Cycle) shuffles a full permutation and works through it before reshuffling.

separator sets what counts as a break: >1 Empty Line (the default - blank line between prompts), Newline (every line is a prompt, handy for short tags), >2 Empty Lines, or Custom Regex using the custom_regex box. That box only activates when the separator is set to custom regex - otherwise it's ignored.

Inputs and outputs

You set pop_mode, separator and text on the node. There's an optional custom_regex, and an optional prompt input for feeding a string in from elsewhere - note that text wins when it's non-empty, so if you've wired an external string and left the node's own box populated, you're iterating the node's box and wondering why your external text does nothing.

Outputs: prompt (the selected block - wire it into your CLIP text encode), remaining_text (everything after this block, joined by the same delimiter), and remaining_count (how many are left, as an INT). The last two are for progress readouts and for gating a branch on "am I nearly done."

Install

ComfyUI Manager → search SaturnNodes, or:

cd ComfyUI/custom_nodes
git clone https://github.com/KOFiblto/ComfyUI-SaturnNodes

Restart ComfyUI. Needs nothing beyond the pack's Pillow/numpy/piexif requirements; it writes its own state file on first use. Category: 🪐 SaturnNodes/Utils. The sibling Prompt Counter node does the counting half live as you type, which is how you decide what number to set the queue batch to.

Where people get burned

You fixed a typo and the sweep restarted. The pointer is keyed to a hash of the text, so editing the prompt block creates a fresh state entry starting at block one. That's deliberate - the alternative is resuming into text that no longer matches - but it's a surprise mid-batch.

It restarts from prompt one after every edit, every time. Same cause. Finish the sweep, then edit.

You queued 30 but got prompt 1 thirty times. The node advances per execution, and only per execution. Checking the count on the node (Run 3 / 30) after a couple of queue presses is the fastest way to confirm it's advancing at all.

The pointer is stuck or confusingly wrong. There's a Reset All Queues button in ComfyUI's settings under the pack's Prompt Iterator section, plus a "Clear State on Launch" privacy toggle that wipes the state file at startup. Both are in the gear menu, not on the node.

One bad prompt in the middle. With a custom regex separator, a malformed delimiter can swallow two prompts into one block - the count on the node is the tell. Check the count matches the number of prompts you pasted before you start the sweep.