ComfyUI-ThinkingLLM Introduction
ComfyUI-ThinkingLLM is a collection of ComfyUI nodes that brings language and multimodal models into your creative workflows. You can use it to describe an image, examine video, transcribe speech, improve a prompt, analyze supported audio, or let a model choose which branch of a workflow should run.
For example, you could ask a model what is visible in a reference image and use its answer to draft a generation prompt. Or you could classify each incoming image as a product photo, portrait, or something else, then send it to the appropriate workflow branch. The extension supports models running on your computer through Transformers or GGUF/llama.cpp, as well as approved remote providers through its API nodes.
How ComfyUI-ThinkingLLM Works
Think of a ThinkingLLM node as an assistant you place between an input and the next step of your workflow. You give it a task in words, connect the material it should examine, and use its output elsewhere in ComfyUI.
- Choose a task and node. Use an understanding node to ask about an image or video, a prompt enhancer to develop a text prompt, or a decision node to make a choice your workflow can act on.
- Choose how the model runs. Transformers/Hugging Face nodes are the recommended starting point for the simplest setup. GGUF nodes use quantized llama.cpp models. Supported API nodes send requests to an approved remote provider.
- Connect the result. Send a
RESPONSEorENHANCED_OUTPUTto a text display or another node’s prompt input. Decision nodes provide outputs designed for branching and structured results.
A Decision Router is like a labeled sorting desk: you define routes such as “portrait,” “landscape,” and “other,” and the node selects one for each input. A Decision Fields node is more like a checklist: it can answer separate questions such as “Is a person visible?” and “How many people are visible?” for the same input. These are model judgments, so check important results rather than treating them as guaranteed facts.
Example of an image routed to named branches
ComfyUI-ThinkingLLM Features
Image and Video Understanding
The ThinkingLLM and ThinkingLLM (GGUF) nodes let a supported model examine images and video and respond to your instructions. Their Advanced versions add more controls and a MASK_PREVIEW output. A mask can help focus analysis on a selected part of an image when your task calls for it.
For instance, instead of asking “What is in this image?”, you might ask “Describe the clothing and pose of the person in the masked area.” Resizing very large images before analysis can reduce memory and context demands. See Features and workflows for guidance on masks and image-focused tasks.
Prompt Enhancement
ThinkingLLM Prompt Enhancer and ThinkingLLM Prompt Enhancer (GGUF) develop text prompts for image or video workflows. You can connect ENHANCED_OUTPUT to a downstream prompt input, then review whether the added detail fits your artistic intent. The documentation also covers duration-aware video prompts and video preset settings.
Audio and Speech
ThinkingLLM Whisper ASR turns speech into text. ThinkingLLM Gemma 4 Audio (GGUF) handles supported audio-understanding tasks. Use these dedicated nodes instead of assuming that an image or video model can also process audio. For straightforward transcription, start with enable_thinking=false where that control is available.
Thinking, Streaming, and Traces
Where available, thinking mode controls whether the model uses a more deliberative generation process. A direct response is often a useful starting point for short answers or transcription. stream_tokens_to_terminal displays generation as it happens in the terminal, which can help you investigate a slow or unhelpful result. Connect RAW_TRACE when you need generation diagnostics; it is separate from the response intended for your creative workflow. The features guide explains these outputs in more detail.
Decision Routing
ThinkingLLM Decision Router (Image) and ThinkingLLM Decision Router (Text) each send an input to one named route. You provide route names and descriptions, plus a system prompt explaining the classification task. The selected route’s output can feed its own workflow branch; empty route outputs block their downstream branches.
The routers support up to 52 configured route sockets. route_index reports the selected socket as a 1-based number: route_01 is 1, route_02 is 2, and so on. decision_json contains each item’s decision and normalized route probabilities. The optional include_reason setting adds a short explanation without changing the choice or scores. With keep_model_loaded, you can choose whether the local model remains loaded between runs; it is off by default.
For a batch, keep every decision paired with its original image or text item. Use a list-aware Switch that preserves input order, or unbatch the items before routing. The Decision Router API guide describes the remote decision options.
Decision Fields
ThinkingLLM Decision Fields (Image) and ThinkingLLM Decision Fields (Text) answer independent questions rather than choosing one route. Each node can expose up to eight Boolean (true/false) fields and eight bounded Integer (whole-number) fields. Add a field by entering its name and question, such as is_fox with “Is a fox visibly present?” or person_count with “How many people are visible?”
Boolean fields use an adjustable probability threshold, set to 0.5 by default. Because the questions are independent, more than one Boolean answer can be true. Integer fields return a value within the range you configure, with at most 52 choices in that range. A valid bounded number does not guarantee an accurate count, so test counting tasks against representative images before automating decisions.
The decision output gives a readable summary; decision_json provides structured results and available probabilities or confidence information. Outputs appear as you configure fields. If you clear a field that is already connected, its connection remains but execution is blocked until you configure it again. Local fields are currently evaluated sequentially, so adding fields or larger image batches can increase processing time.
Reusable Prompts and Remote Providers
ThinkingLLM System Prompt Preset supplies a reusable system prompt as a STRING, helping you keep instructions consistent across nodes. ThinkingLLM API (OpenAI Compatible) connects to approved remote providers while keeping provider credentials in server-side profiles or environment variables, rather than in workflow files. Review API setup and security and API image inputs before using remote services.
ComfyUI-ThinkingLLM Models
The extension offers curated entries across several model families. The appropriate choice depends on both your task and the node’s backend.
| Model family or option | What to consider |
|---|---|
| Qwen3.8, Qwen3.5, Qwen3-VL, Qwen2.5-VL, and Qwen3 | Curated Qwen entries span the extension’s text and multimodal workflows. Select a model compatible with the node and input you plan to use. |
| Gemma 4 | The curated entries include vision, text, and audio-capable GGUF variants. Use the dedicated Gemma 4 Audio node for its supported audio tasks. |
| Whisper | The speech-to-text node offers models from tiny through large-v3, plus distil-large-v3. These are for transcription rather than visual analysis. |
| Clef-Flash 9B, Clef 27B, and OpenJev 27B GGUF | Local Decision Router choices for classifying image or text inputs. Image routing also uses a matching vision projector. |
| Compatible local checkpoints and GGUF/mmproj pairs | Existing compatible models can be discovered, avoiding a duplicate download. A GGUF vision model needs its matching projector. |
The author recommends Transformers/Hugging Face nodes as the default when you want the simplest setup. Choose GGUF when you specifically want quantized llama.cpp models or Gemma 4 audio. Decision Router models have additional native runtime requirements: Clef uses decision-batch APIs, OpenJev uses final-position logits APIs, and image routing also needs MTMD vision APIs. OpenJev is licensed CC BY-NC 4.0 and is hidden in commercial builds; the Clef models are Apache-2.0.
For exact model entries, locations, compatibility, and platform guidance, consult Models and backends. The Decision Router runtime guide explains its model-specific requirements.
Troubleshooting ComfyUI-ThinkingLLM
A Node Cannot Use the Selected Model
- Check that the model matches the node’s task and backend. An audio task, for example, needs a supported audio node and model.
- For GGUF vision, check that the matching vision projector is available.
- Review Models and backends for compatibility and model locations.
A Decision Router Reports Missing Runtime Capabilities
- Read the missing-symbol message reported by the node.
- Check the requirements for your selected model in the Decision Router runtime guide.
- Verify that your installed
llama-cpp-pythonbuild provides the required native APIs. The node checks compatibility but does not replace an installed native runtime.
Generation Is Slow or Uses Too Much Memory
- Resize very large images before sending them to the model.
- Try a shorter, more direct task and disable thinking mode when a brief answer is sufficient.
- For Decision Fields, test fewer fields or a smaller batch: local fields are evaluated one after another.
- Where available, turn on
stream_tokens_to_terminalto see generation progress.
A Decision or Count Seems Wrong
- Make the route descriptions or field questions specific. For example, ask whether a fox is visibly present, rather than whether an image is “about foxes.”
- Inspect
decision_jsonfor the available probabilities and decision details. - Test the model with representative, labeled examples before relying on its answers to control an automated workflow. A bounded Integer output is valid for its configured range, but its count may still be inaccurate.
A Connected Decision Field Blocks Execution
Check whether that field’s name and question have been cleared. Configure the field again, or remove a connection you no longer need. Clearing a field does not automatically remove its connected output.
Frequently Asked Questions
Which node should I try first for an image?
Start with ThinkingLLM if you want the recommended Transformers/Hugging Face path. Use an Advanced node when you need its additional controls or MASK_PREVIEW.
Can I run a decision on several images at once?
Yes. Batched decisions preserve input order. Keep each route_index paired with its corresponding image, using a list-aware Switch or unbatching when needed.
Can two Decision Fields both return true?
Yes. Boolean fields are independent questions, unlike a router that selects one named route.
Where should I look for a readable decision result?
Use the decision output for a multiline summary. Use decision_json when another node needs structured results. ComfyUI’s built-in Save Text node can save valid JSON as an indented .json file when its format is set to json; saving does not reformat the string passed to downstream nodes.
Are API keys saved in a shared workflow?
The extension’s approved remote-provider setup keeps credentials in server-side profiles or environment variables, not in workflow files. See API setup and security.
Learn More about ComfyUI-ThinkingLLM
- Features and workflows: thinking mode, streaming, traces, audio, masks, and practical workflow behavior.
- Models and backends: supported model families, local model discovery, and backend selection.
- Duration-aware video prompts and video preset settings: guidance for video-prompt workflows.
- Decision Router API guide: supported remote decision options and their limits.
- API image inputs: using images with the OpenAI-compatible API node.
- ComfyUI: the application in which these nodes run.
ComfyUI-ThinkingLLM is a GPL-3.0 fork. See the license for its terms.
