ruminar-ComfyUI-CheckpointHandpickerSuite/doc/HOW_TO_USE.md

How to use

Installation

cd ComfyUI/custom_nodes
git clone https://github.com/ruminar/ComfyUI-CheckpointHandpickerSuite.git

Start or restart ComfyUI.

Basic idea

ComfyUI-CheckpointHandpickerSuite is designed for checkpoint-heavy workflows.

The suite helps you:

1. rotate checkpoints during generation,
2. collect checkpoint-aware output images,
3. review each checkpoint from its own generated images,
4. tag checkpoints as god, favorite, nice, keep, or delete,
5. set a good generated image as the checkpoint thumbnail,
6. delete failed generated images while reviewing, and
7. export a confirmation script for deleting checkpoints marked for deletion.

You do not need to rebuild your entire workflow around this suite.
In many cases, you can add Checkpoint Name Cycler in front of your checkpoint loader, then build the review UI in another browser tab.

Back up or migrate checkpoint tags

Add the standalone Checkpoint Tag Export / Import node anywhere on the canvas. It has no inputs or outputs and never uses the ComfyUI queue.

• Click Export to write the currently evaluated tags to output/CheckpointHandpickerSuite/.
• Leave Tag Transfer Directory blank to use that default. Enter an existing full local path or UNC/network path to share exports between PCs; custom directories are never created automatically.
• Copy an exported JSON file into the same directory on another ComfyUI installation, then click Import.
• Import matches checkpoints by file name and file size. Directories, drives, and file timestamps may differ.
• Existing tags are never overwritten. Untagged matches are imported, equal tags are unchanged, and different tags are reported as conflicts.
• Missing or ambiguous matches are skipped. Import never moves or deletes checkpoint files.
• The HandpickerSuite UI refreshes automatically when Import finishes.

Imported delete tags are logical tags only and do not create deletion reservations. To reserve one of those checkpoints for deletion later, toggle its delete tag OFF and ON in Checkpoint Status Tagger.

Import chooses the export whose matching filename has the greatest timestamp string. It does not validate whether the timestamp is a real or future date. The chosen latest file must be valid; Import does not silently fall back to an older JSON file.

Recommended image saving setup

The review tools work best when generated images include checkpoint-aware names or folders.

The simplest setup is:

1. Connect Checkpoint Name Cycler.ckpt_name to your checkpoint loader.
2. Connect Checkpoint Name Cycler.ckpt_name_safe to the filename or label used by your image saver.

You can use ComfyUI's standard SaveImage by including ckpt_name_safe in filename_prefix.

For a cleaner checkpoint-review workflow, the recommended companion saver nodes are:

• ComfyUI-GMImageSaver
• ComfyUI-PillowImageSaver

For these saver nodes, connect:

CheckpointNameCycler.ckpt_name_safe -> saver.label

This makes it much easier for ImageDir Preview to find images generated by each checkpoint later.

The simplest workflow

Checkpoint cycling mode

You can add checkpoint cycling to your existing workflow with a small change: place Checkpoint Name Cycler in front of your checkpoint loader.

1. Open the image generation workflow you already use.
2. Add a Checkpoint Name Cycler node to the canvas.
3. Connect the Cycler's ckpt_name output to the ckpt_name input of CheckpointLoaderSimple or your checkpoint loading node.
4. Connect the Cycler's ckpt_name_safe output to your image saver filename/label path.
5. Set the Cycler's mode to shuffle_once.
6. Queue as many jobs as you like, such as 100 or 500 jobs.

The Cycler will automatically rotate checkpoints, and generated images will be saved with checkpoint-aware names or directories.

A slightly more convenient workflow

Checkpoint monitoring mode

• Add a Checkpoint Name Cycler node as described above.
• Add a Checkpoint List Selector node.

The Selector provides a list of checkpoints and a context-sensitive action button.

Selector action button

The Selector action button changes depending on what is connected to ckpt_name_str.

No review node connected

🏹 Push to Local List

This sends the selected checkpoint to the Cycler's Local List.

When a Cycler has entries in its Local List, normal cycling is temporarily paused and Local List entries are processed first.

Connected to ImageDir Preview

🎯 Sync Checkpoint

This sends the selected checkpoint to connected review nodes, such as ImageDir Preview and Checkpoint Status Tagger.

Sync Checkpoint does not queue or execute the workflow.

Connected directly to Tagger only

🌑 DirectLink OFF
🌕 DirectLink ON

This is DirectLink mode.

DirectLink is for reviewing images outside ComfyUI, for example on a tablet, shared folder, or external image viewer.

Use this connection:

CheckpointListSelector.ckpt_name_str -> CheckpointStatusTagger.ckpt_name_str

Do not connect ImageDir Preview in this mode.

DirectLink is OFF by default.
While DirectLink is OFF, selecting a checkpoint in the Selector does not update the Tagger target.

When you turn DirectLink ON, a confirmation dialog is shown once per browser page load:

Enable DirectLink?

Use this mode only while checking generated images on a tablet, shared folder, or external viewer.

Otherwise, connect ImageDirPreview and use Sync mode.

Tagger will label the checkpoint selected in ListSelector.

After DirectLink is ON, the Tagger labels the checkpoint currently selected in the Selector.

Use DirectLink when you want to browse generated images freely outside the small ComfyUI preview area, then tag only the checkpoints you care about.

Local List

Local List is a per-Cycler temporary checkpoint list.

• Local List is isolated by browser tab and Cycler node.
• Push to Local List updates only Cyclers in the current tab.
• Local List has priority over all normal selection modes, including fixed mode.
• Local List entries are used as-is and are not affected by Filter.
• Local List ignores change_every.
• Each Local List entry is consumed once per Cycler execution.
• Duplicate entries are allowed. Push the same checkpoint multiple times if you want to run it multiple times.
• While Local List is active, normal index, hold count, and Shuffle Once deck are not advanced.
• If the list becomes too large or is no longer needed, use Clear Local List.

Advanced workflow

In-job checkpoint review mode

This mode lets you tag checkpoints while a job is running, based on a preview image generated by that checkpoint.

This feature is intended for users with advanced multi-stage workflows.

For example, it is useful when your workflow generates an intermediate image, then performs additional steps such as hand correction, face correction, upscaling, or post-processing.

If your workflow is a simple one-pass generation workflow, the next job may start immediately after the preview appears. In that case, this mode may not be useful, and you can skip this section.

1. Add Checkpoint Name Cycler and Checkpoint List Selector as described above.
2. Add an Ephemeral Preview node.
   • Connect it to the IMAGE output of a VAE Decode node in the middle of your workflow.
3. Add a Checkpoint Status Tagger node.
   • Connect the Tagger's ckpt_name_str input to the Cycler's ckpt_name_str output.

Now, while a job is running, you can check the preview image and tag the checkpoint as god, favorite, nice, keep, or delete.

Status changes are immediately shared with the Checkpoint Handpicker Suite UI, including the Checkpoint List Selector.

Checkpoint Name Cycler can also use checkpoint status as a filter when cycling.

For details about how this works, see the Checkpoint Name Cycler documentation.

Output-folder checkpoint review mode

This mode lets you keep the main generation workflow running while reviewing generated images in another browser tab.

In this tab, you do not execute jobs.

This mode only uses the ComfyUI user interface as a review screen. To avoid accidentally queueing jobs from the review tab, it is a good idea to move the queue control panel away from your main working area.

1. Keep your main generation workflow running.
2. Open ComfyUI in another browser tab.
3. Add a Checkpoint List Selector node.
4. Add a Checkpoint Status Tagger node.
   • Connect the Tagger's ckpt_name_str input to the Selector's ckpt_name_str output.
5. Add an ImageDir Preview node.
   • Connect its ckpt_name_str input to the Selector's ckpt_name_str output.
   • By default, it searches images in the ComfyUI output folder.
   • If you want to use another directory, provide a full path string to search_directory.
   • It searches subdirectories and prioritizes newer files.
   • It supports common image formats such as PNG and JPEG.

When ImageDir Preview is connected, the Selector action button becomes:

🎯 Sync Checkpoint

Select a checkpoint in the Selector and press 🎯 Sync Checkpoint.

The selected checkpoint will be sent to the connected Tagger and Preview nodes, and preview images will be displayed.

When you tag a checkpoint using the Tagger, the status is shared immediately. Other tabs can refresh or update their own Suite UI, and Cycler filters can use the updated status.

For details about how this works, see the Checkpoint List Selector documentation.

ImageDir Preview image actions

ImageDir Preview can be used not only to view images, but also to organize them.

Hovering over an image tile highlights it.

Left-click a live image tile to open the action menu:

Delete image
Set as checkpoint thumbnail

Delete image

Delete image deletes the generated image file directly from disk after confirmation.

After deletion:

• the tile position is preserved,
• a NO IMAGE overlay is drawn over the tile,
• the deleted tile no longer shows a hover frame,
• clicking the deleted tile does nothing.

This is intended for quickly removing failed generated images during checkpoint review.

Set as checkpoint thumbnail

Set as checkpoint thumbnail sets the selected generated image as the sidecar thumbnail for the checkpoint.

This is useful because the best image generated by your own workflow is often more meaningful than a generic model sample image.

If a checkpoint already has a thumbnail, it may be overwritten.

External review with DirectLink

Use DirectLink when you want to review images outside ComfyUI.

Example workflow:

1. Save generated images into checkpoint-aware folders or filenames.
2. Open those images on a tablet, shared folder, or external image viewer.
3. In ComfyUI, place:
   • Checkpoint List Selector
   • Checkpoint Status Tagger
4. Connect:

CheckpointListSelector.ckpt_name_str -> CheckpointStatusTagger.ckpt_name_str

5. Turn 🌕 DirectLink ON.
6. Select checkpoints in the Selector while checking images externally.
7. Tag them with the Tagger.

DirectLink is not a replacement for ImageDir Preview.

Use the two modes for different purposes:

Mode	Best for
ImageDir Preview + 🎯 Sync Checkpoint	ComfyUI-internal review, thumbnail setup, deleting generated images
🌕 DirectLink ON	External review on a tablet, shared folder, or image viewer

Tagger statuses

Checkpoint Status Tagger has five status buttons:

• 👑 god!
• 💛 favorite
• 👍 nice
• ✔ keep
• 🗑 delete

There is no none button.
Pressing the active status toggles it off to none.

delete can only be set from none; pressing active delete toggles it back to none.

delete is a reservation only. It never deletes checkpoints immediately.

Suggested meanings:

Status	Suggested meaning
👑 god!	Hall of fame / absolute keep
💛 favorite	Favorite / recommended / frequently used
👍 nice	Good candidate
✔ keep	Keep
🗑 delete	Marked for deletion
none	Unclassified

Deleting checkpoints marked for deletion

Checkpoints are not deleted immediately when you press the delete tag.

Deletion is always handled by a generated script, so you can review and confirm the final cleanup manually.

A deletion script is generated under:

ComfyUI/output/CheckpointHandpickerSuite/delete_scripts/

Run the generated script from a terminal when you are ready.

Example:

python delete_reserved_checkpoints.py

The generated script asks for confirmation before deleting:

[y/N]

Because the script is stored under the ComfyUI output folder, it remains easier to find than a temporary file.

Cycler modes

fixed

Fixed mode is compatible with a normal checkpoint selector.

• The selected checkpoint is always used.
• Filter is not applied to fixed mode.
• If the selected checkpoint disappears after refresh, the Cycler falls back to a valid checkpoint.
• Local List can still temporarily override fixed mode.

increment

• Uses the ordered checkpoint list.
• Filter acts as a pass condition.
• Non-matching checkpoints are skipped and the index advances.
• Changing Filter does not reset the index.

randomize

• Chooses randomly from the current Filter-matching set.
• Repeats are allowed.
• There is no skip/deck behavior.

shuffle_once

• Builds a shuffled deck from all checkpoints, independent of Filter.
• Filter is applied only at selection time.
• Non-matching checkpoints are skipped and removed from the current deck.
• The selected checkpoint is also removed from the deck.
• When the deck becomes empty, a new unfiltered deck is created.

Checkpoint review as a workflow

Checkpoints are not just files.

Each model has its own strengths, weaknesses, habits, and moments where it works unexpectedly well.

However, checkpoint review often tends to be vague:

• generate a few images,
• remember a rough impression,
• search for outputs later by filename,
• hesitate to delete anything because the decision feels risky.

ComfyUI-CheckpointHandpickerSuite was designed to make this process more explicit and repeatable.

The basic ideas are:

1. You need checkpoint cycling before you can efficiently gather review targets.
2. Interesting checkpoints should be easy to revisit by inserting them into the next jobs.
3. Statuses should stay simple, but expressive enough for real review.
4. delete should mean delete reservation, not immediate checkpoint deletion.
5. Generated images should be easy to inspect, delete, and use as checkpoint thumbnails.
6. Review statuses should be usable as filters for future cycling.
7. To make those filters meaningful, checkpoint selection should be resolved at execution time, not when the job is queued.
8. Execution-time resolution makes it possible to follow checkpoint refreshes and status changes without restarting ComfyUI.
9. Review should be possible during generation, from generated output images in another tab, or externally with a tablet/shared folder/image viewer.

In other words, this suite is not only a set of nodes.

It is a practical proposal for discovering, testing, reviewing, revisiting, and safely cleaning up checkpoints in checkpoint-heavy ComfyUI workflows.