Symbiotica Refs Folder

Sometimes you don't want a file picker - you want "everything in this folder, in a deterministic order, loaded, done." Symbiotica Refs Folder is that. It takes an absolute folder path and nothing else: no browsing, no picking, so a dispatcher can bind the path and run the graph headless over the API. That headless angle is the whole point. When a render server takes a job by path, a node that opens a dialog box is a node that breaks the automation.

How it works

On execution it lists the folder's images, sorts by filename, decodes each, and emits them as a list - one image per file, index-aligned with the filenames. A file that won't decode is skipped (a half-written render doesn't take the whole run down), but a missing folder - or a folder where nothing decodes - raises instead of silently handing the graph zero references. That last part is deliberate: zero references looks like a successful empty load, and in a pipeline that's how renders get made with the wrong inputs.

The inputs

• refs_dir (required) - absolute path to the folder of reference images. Absolute is the contract - relative paths aren't "helpful", they're ambiguity, and headless dispatchers don't have a cwd to reason about.
• max_count - keep at most this many images, 0 = all of them. The cap exists because a reference pipeline can hit a folder with two hundred files and pay for all of them.

The outputs

• images - one IMAGE per file, in filename order.
• names - the filename of image i, index-aligned with images.
• count - how many came back.

Install

Standard pack install - search Symbiotica in ComfyUI Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/symbiotica-ai/comfyui-nodes.git symbiotica
pip install -r symbiotica/requirements.txt

Restart after. No API key, no model download.

Gotchas

Two behaviors surprise people. First, "skips undecodable files" is permissive by design, but if a run renders with a visibly missing reference, check the folder for a corrupted file - the node won't tell you it skipped one. Second, the raise-on-missing-folder: it's a feature, but it means a typo in refs_dir fails loudly at queue time, not silently at delivery time. If you're wiring this into an automated runner, make the path a graph input so the dispatcher sets it per job rather than baking it into the workflow. And mind max_count: it takes the first N in filename order, so a folder named ref_01..ref_10 plus ref_11 caps exactly as you'd expect, but ref_1, ref_10, ref_2 sorts the way strings do.