ComfyUI-Smart-Metadata-Reader is a Python-only ComfyUI custom node. Its main node, Smart Metadata Reader, works as an image loader: it lets you select or upload an image, reads the AI generation metadata already stored inside that image, and outputs the image, mask, real positive/negative prompts, and common generation settings.

Overview

This node is not an image captioning or prompt guessing tool. It does not look at pixels and infer a prompt. It reads metadata that already exists in the image file, especially the prompt and workflow JSON saved by ComfyUI PNG outputs.

The core goal is to support complex ComfyUI workflows. The parser starts from the final selected sampler, walks backward through its positive and negative conditioning chains, and extracts the prompts and settings that actually reached the final generation step.

What Problem It Solves

Many prompt readers can parse simple A1111 settings or basic ComfyUI images where CLIPTextEncode.inputs.text is a plain string. In complex workflows, that field may be a graph link to upstream string functions, cached ShowText nodes, translator nodes, ControlNet conditioning, detailers, or other custom node chains.

This project parses ComfyUI metadata as a graph instead of scanning every text field in the workflow.

Difference From Regular Prompt Readers

It selects the sampler connected to the final image output when possible.
It resolves positive and negative prompts only from the selected sampler's conditioning chain.
It does not scan every text field in the workflow.
It does not mix ControlNet parameters such as image, strength, control_net, or model_name into the prompt.
It does not treat Gemini / OpenAI / ChatGPT / Claude / LLM fields such as system_instruction, system_prompt, prompt, instruction, or messages as final prompts.
When ShowText|pysssss has a text_0 cached display result, that cached result is preferred.
It does not filter LoRA trigger words, character tags, style tags, NSFW tags, quality tags, translated text, or user-written tags.

Installation

From your ComfyUI installation:

cd ComfyUI/custom_nodes
git clone https://github.com/CyberShadowX/ComfyUI-Smart-Metadata-Reader.git
cd ComfyUI-Smart-Metadata-Reader
pip install -r requirements.txt

Restart ComfyUI after installing.

Usage

Add the Smart Metadata Reader node in ComfyUI.
Select an image from the ComfyUI input directory, or upload one through the image widget.
Use the node outputs in your workflow, or inspect the text outputs directly.

Node Options

parameter_index: Selects which parameter block to use when falling back to multi-parameter A1111 / Forge metadata. Keep this at 0 for normal use.
prefer_cached_text: Prefer cached outputs from nodes such as ShowText, which helps avoid treating Gemini / OpenAI system_instruction or prompt templates as final prompts. Keep this true for normal use.
include_raw_json: Keeps the original prompt / workflow JSON in the internal parse result. Keep this true for normal use.
max_depth: Maximum reverse graph traversal depth, used to prevent cycles. Keep this at 40 for normal use; increase it only for very complex workflows.

Outputs

The main node outputs:

image
mask
positive
negative
seed
steps
cfg
width
height
model_name
filename
setting

setting is human-readable text containing filename, source, model, VAE, LoRA list, seed, steps, CFG, sampler, scheduler, size, status, confidence, and unresolved information when available.

Supported Metadata

ComfyUI prompt metadata is preferred because it is closest to the executed graph.
ComfyUI workflow metadata is used for UI cache and fallback values, such as ShowText|pysssss display cache.
A1111 / Forge parameters metadata is used as fallback when ComfyUI graph parsing cannot start.
PNG, JPEG, and WEBP metadata are read through Pillow.

If an image was compressed, forwarded through a chat app, or processed by a hosting platform that stripped metadata, this node cannot recover the original prompt. In that case, you need a separate image captioning or prompt inference tool.

Supported Node Types

Initial Phase 1 support includes:

KSampler
KSamplerAdvanced
SamplerCustom
SamplerCustomAdvanced
CLIPTextEncode
CLIPTextEncodeSDXL
StringFunction|pysssss
ShowText|pysssss
DeepTranslatorTextNode
ControlNetApply
ControlNetApplyAdvanced
ConditioningCombine
ConditioningConcat
InpaintModelConditioning
FaceDetailer and common detailer passthrough patterns
CheckpointLoaderSimple
CheckpointLoader
VAELoader
LoraLoader
LoraLoaderModelOnly

Important Rules

positive must come from the selected sampler's positive conditioning chain.
negative must come from the selected sampler's negative conditioning chain.
The parser does not scan every text node in the workflow.
Unconnected Gemini, ShowText, StringFunction, PrimitiveString, note text, or old CLIPTextEncode nodes do not contaminate the result.
ControlNet, Detailer, Inpaint, ConditioningCombine, and ConditioningConcat are treated as passthrough or branch nodes only when they are on the final conditioning chain.
LoRA loader file names and strengths are extracted separately for settings; LoRA trigger words remain in the prompt if they entered the text chain.
The parser does not perform content moderation, prompt optimization, or token deletion.

LLM / ShowText Cache Notes

For Gemini / OpenAI / ChatGPT / Claude / LLM prompt-generation workflows, the plugin can only recover runtime results that were written into metadata and are on the final selected sampler/generator positive / negative chain.

Recoverable:

ShowText|pysssss cache on the final chain, such as inputs.text_0 in prompt JSON or widgets_values[0] on the same node id in workflow JSON.
Recursive SmartMetadataReader positive / negative output results on the final chain.
StringFunction, text concatenation, ConditioningCombine, and ConditioningConcat branch results on the final chain.

Not recoverable:

Runtime LLM output that exists only inside an LLM runtime node and was not embedded into ShowText cache.
ShowText caches from other workflow branches that are not connected to the final selected generator, even if they look like prompts.
Gemini / OpenAI node prompt, system_instruction, system_prompt, messages, templates, or API parameters.

In these cases the node returns PARTIAL / unresolved. This avoids reading stale branches, fallback branches, UI-only display branches, or LLM instruction templates as final prompts.

Verified Scenarios

Phase 1 real-world validation and regression tests cover:

Regular ComfyUI prompt / workflow metadata.
Comfyroll CR Apply ControlNet positive conditioning passthrough.
ShowText|pysssss cached text.
StringFunction|pysssss prompt concatenation.
DeepTranslatorTextNode text source.
A1111 / Forge parameters fallback.
PNG / JPEG / WEBP metadata reading.
UltimateSDUpscale / USDU sampler-like metadata parsing.
Nested SmartMetadataReader output resolution.
CLIPTextEncode.text -> ShowText -> SmartMetadataReader positive/negative output.
JPEG EXIF UserComment / Civitai metadata fallback.

Current Limitations

Phase 1 is Python-only. In-node large text boxes and a richer SD Prompt Reader style preview UI are planned for the Phase 2 JavaScript enhancement.
Some unknown custom conditioning nodes may return PARTIAL / unresolved instead of guessing.
If a custom node did not save its generated result into metadata cache, the parser may not be able to recover it.
If an upscaled image references its source image, such as 003.png, and that source image is not present in a resolvable path, the parser returns PARTIAL / unresolved; it cannot recover runtime outputs from nowhere.
The plugin does not globally scan all ShowText / widgets_values / text fields in the workflow. It only resolves the final selected sampler/generator positive / negative chain.
Images with stripped metadata cannot provide original generation settings.

Roadmap

Phase 2: JS frontend enhancement to show positive / negative / setting text boxes inside the node.
Phase 3: More sampler adapters, such as Efficient / Impact / custom samplers, added from real failure samples.
Phase 4: More metadata format compatibility.

Local Verification

Run these from the plugin directory:

python -m pytest -q
python -m compileall .

The tests/ directory is for development and regression testing. Regular ComfyUI users do not need to run it manually; it is kept in the repository to prevent future custom node compatibility work from breaking existing behavior.

Manual ComfyUI Verification

Restart ComfyUI.
Search for and add Smart Metadata Reader.
Select or upload an image with metadata.
Confirm the node outputs image, mask, positive, negative, and setting.
If the status is PARTIAL, inspect unresolved information in setting to identify unsupported custom nodes.