Confirm ComfyUI is up and reachable (loop step 0).

Returns the installed-node count and device/VRAM. If this fails, ComfyUI isn't running or is on another port — do not start guessing node names.

Search installed nodes by keyword (loop step: discover, don't guess).

Matches the keyword against BOTH the class name and the display name, so a node found by its UI label ("Load Image") still turns up. Returns class_name -> display_name. Class names are case-sensitive and differ from display names — use the class_name in workflow JSON. Omit keyword to get the total count only (the full list is large).

List the real model files a loader offers (loop step: never hallucinate a checkpoint/LoRA/VAE filename).

Reads the loader's enum from object_info (handles both the legacy list and the newer COMBO encoding). If input_name is omitted, reports every enum-typed input on the node. Pick ONLY from the returned list.

Search the downloadable model catalog — find checkpoints/LoRAs/VAEs/ controlnets/upscalers you may NOT have installed yet (the local equivalent of the cloud's model search). Reads ComfyUI-Manager's model list; each result shows whether it's already installed on THIS box.

Filter by keyword (name/filename/base/description) and optional model_type (checkpoint, lora, vae, controlnet, upscale, clip, diffusion_model, ...). Install one with install_model(name). Requires ComfyUI-Manager on the host.

This is a catalog of known models; list_models shows what a specific loader currently offers on disk (ground truth). Discover here, then verify against list_models after installing.

Search known-good workflow templates to adapt (few-shot beats zero-shot).

source="online" (default): the OFFICIAL open catalog on GitHub (Comfy-Org/workflow_templates) — the same ~550-template set the Cloud MCP's search is built from. You do NOT need these installed; they're browsed straight from the repo. Matches keyword against name + title + description.

source="installed": only templates on THIS ComfyUI right now (/api/workflow_templates — every installed pack's example workflows). Smaller, but guaranteed runnable on your install without adding anything.

Then fetch one with get_template. Note an online template may reference nodes/ models you haven't installed — reconcile against object_info before running.

Fetch one workflow template as a known-good starting point.

source="online" (default): from the official GitHub catalog — no install needed; pack is ignored. source="installed": from this ComfyUI (pack required).

fmt="flowzip" (default): compact FlowZip text — ~72% fewer tokens than the raw litegraph JSON (median), enough to read/adapt the graph. fmt="json": the full litegraph. Either way it's litegraph, NOT the API/prompt format submit_workflow needs — adapt to API (resolve passthroughs, widgets_values -> named inputs via get_node), or inflate a FlowZip with inflate_workflow. If from the online catalog, first confirm you have its nodes/models — run find_missing_nodes then install_node_pack, or verify with list_nodes/list_models.

Expand FlowZip text back into a full litegraph workflow JSON.

Reverse of the FlowZip that get_template returns. Structure (nodes, types, links, widget values) is preserved; cosmetic fields are not. To RUN it, still adapt the litegraph to API/prompt format for submit_workflow.

Convert FlowZip (or litegraph) into API/prompt format ready for submit_workflow.

Inflates FlowZip if needed, then maps the litegraph to the flat API graph using the live object_info (resolves links, maps widget values to named inputs). This is the bridge for authoring/adapting graphs compactly and running them.

Best-effort: subgraph instances and unknown nodes are skipped and reported; widget drift between an old template and a newer node shows up as a node_errors when you submit_workflow the result — read it, fix that node, re-submit. Review the API graph before running.

List a template's overridable inputs WITHOUT loading the full graph JSON.

Converts the template to API format and reports each node's literal (non-wired) inputs and current values — the curated parameter list you can change with run_template. Far smaller than the raw graph. Subgraph/unknown nodes can't be expanded and are reported (their inputs aren't overridable this way).

Run a known-good template with input overrides — WITHOUT loading the graph into context. Fetches the template, converts to API format, applies overrides, and submits. Use template_slots first to see what you can override.

overrides: {node_id: {input_name: value}} (node ids and inputs from template_slots). After it runs, call get_result then get_image and LOOK — a green run is valid, not correct.

Limitation: subgraph templates can't be expanded (converter coverage ~88% of non-subgraph nodes); if nodes are skipped it's reported and the run may be incomplete. Confirm the template's nodes/models exist first (find_missing_nodes).

Diff a template's nodes against what's installed, and resolve each missing node to the pack that provides it (via ComfyUI-Manager's registry mapping).

Fetches the template (same args as get_template), lists the node classes it uses, subtracts what /object_info already has, and for each missing class reports the installable pack id to pass to install_node_pack. Read-only.

Install a custom-node pack by its ComfyUI-Manager registry id (from find_missing_nodes) — trusted registry only, no arbitrary code.

Queues the install, starts the queue, and polls until done. A ComfyUI RESTART is required afterward before /object_info reflects the new nodes — call restart_comfyui, then re-query. Fails clearly if Manager's security level blocks API installs.

Download a model from the catalog by its exact name (from search_models), into the correct models// folder, via ComfyUI-Manager.

Trusted catalog only — Manager whitelists the source. Unlike nodes, models do NOT need a ComfyUI restart (loaders re-scan the folder); once it completes, verify with list_models. Large models can take a while — the download continues server-side even if this call's poll window ends.

Restart ComfyUI (via ComfyUI-Manager) so newly installed nodes register in /object_info. The server is briefly unavailable; poll check_comfyui after.

Queue an API-format workflow for execution (loop step 2: RUN).

workflow is the flat API/prompt-format dict: {node_id: {class_type, inputs}}. Do NOT pass litegraph/UI format here.

On success: returns the prompt_id — then call get_result to fetch outputs and get_image to LOOK at them. Running with zero errors means the graph is VALID, not CORRECT — you still have to inspect the pixels. On failure: returns node_errors keyed by node id. That is NOT an iteration — read the error, fix that specific node, and re-submit until it executes.

Poll /history for a submitted prompt and return its output files (loop step 3: LOOK — part 1, find what was produced).

Blocks up to timeout_s for the run to finish. Returns each output's filename / subfolder / type — feed those to get_image to view the pixels.

Fetch a rendered output so you can LOOK at it (loop step 3: LOOK — part 2).

Returns the actual image to the model. This is the step that makes the loop work: don't declare a workflow done off a green run — view the pixels, judge them against the brief, then change one thing and re-run.

Upload a local image into ComfyUI's input/ dir so a LoadImage node can use it.

Returns the name to reference in the workflow. (Video nodes like VHS_LoadVideo* read files you place directly in ComfyUI's input/ dir instead.)

Report device / VRAM usage — useful when tuning resolution/batch or after an OOM.

Show what's running and pending in ComfyUI's execution queue.

Cancel the currently executing prompt.

See what changed between two passes (loop step 3: LOOK — the comparison).

mode="side_by_side": both outputs on one canvas — what moved, at a glance. mode="difference": 0.5 + 0.5*(a-b) — identical regions read FLAT MID-GRAY and only real changes pop. This is how you answer "did the background actually stay put?", which the eye is bad at. Raise amplify (e.g. 4.0) to surface subtle drift.

Use it every pass against your best-so-far: a change that altered more than you intended is a regression even if the new bit looks nice.

Quantify the change between two passes — the 'I changed only what I meant to' gate.

Returns mean/max absolute difference and the % of pixels that moved. Pair it with compare_images: the picture tells you WHAT changed, this tells you HOW MUCH — and catches the case where a 'small tweak' quietly rewrote the frame.

Score an output objectively, for the ratchet (metric: sharpness | tile_seam | brightness).

Use ONLY where the brief has an objective test — then feed the score to loop_record so the ratchet can't be fooled by a model that wants to be done:

tile_seam "seamless texture" — compares the wrap-around join to an interior join. ~1.0 = genuinely tiles; >2 = a real seam. The eye waves this through. sharpness "upscale/restore, add detail" — edge energy. Rises with real detail, falls when a pass just softened the image. Compare ACROSS passes. brightness mean / stddev / p99 — exposure and blown-highlight checks.

A score is not the judgement. A graph with a great number can still look wrong — gate on the metric, decide with your eyes.

Open a loop run — do this BEFORE the first submit (loop step 0).

brief is what "right" means, in the user's words; you'll be judged against it. gate is the objective test IF the brief has one ("must tile seamlessly", "exactly 3 apples", "identity preserved") — leave empty for purely aesthetic work.

Returns a run_id. Pass it to loop_record every pass. This is what makes the ratchet real: your best graph is stored HERE, not in your context, so it survives compaction and can actually be reverted to.

Record a pass and apply the ratchet (loop step 5: DECIDE).

change the ONE thing you changed this pass ("denoise 0.6 -> 0.45"). outcome your verdict vs the best-so-far: "better" | "worse" | "same". graph the API graph you just ran — REQUIRED when outcome is "better", because that's what gets stored as the new best and handed back on a revert. score an objective score from measure_image, when the brief has a gate. If both this pass and the best have one, the NUMBER decides — not your verdict. (A model that wants to be finished will call a regression "better".) outputs this pass's output files, straight from get_result — pass them through so loop_report can show what each pass actually looked like.

On "worse"/"same" you get the best graph back: revert to it and try a DIFFERENT change. Never build on a regression — that's how a loop wanders instead of converging.

Fetch the best-so-far graph — to revert to it, or to deliver it as the final.

Use this after a compaction, or any time you're unsure the graph in your context is still the best one. It is the source of truth; your memory is not.

The append-only loop log: every pass, what changed, what it did.

Read it after a context compaction to recover the thread — what the brief was, what's already been tried (so you don't retry a dead end), and which pass is best. This is also the log you hand the user at sign-off; it's the story of how the result got good.

Close the loop at the convergence checkpoint — you can't name a defect anymore.

Marks the run converged and returns the final ledger + the best graph, ready to present. Then STOP and ask the user to approve or request changes; don't keep inventing variations to avoid stopping.

Render the whole run as ONE self-contained HTML page — every pass, what changed, what was kept, what was reverted, and the final.

This is the artifact worth keeping. The final image alone proves nothing; the evidence of convergence — the passes you threw away — is what shows the loop actually worked. Hand it over at the sign-off checkpoint alongside the result.

Images are downscaled and base64-inlined, so the page renders with ComfyUI off, on someone else's machine, or emailed. Writes next to the run state by default; set out_path to put it anywhere.

Convert an API graph to UI/litegraph format so a human can open and edit it.

The loop builds API format because that's what /prompt runs — it is NOT the file you drag onto the ComfyUI canvas. Call this when the user asks for the editable workflow.

The result is VERIFIED by converting it back to API format and diffing against what you passed in; any mismatch is reported. widgets_values is positional and a silent off-by-one shifts parameters — a plausible-but-wrong file is worse than none, so if the round-trip doesn't match, fix it before shipping it.

With save=True and a name, it's written to ComfyUI's workflows dir so it shows up in the UI's workflow list.