ruminar-ComfyUI-CheckpointHandpickerSuite/doc/HOW_TO_USE.md

# How to use

## Installation

```bash
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`](https://github.com/ruminar/ComfyUI-GMImageSaver)
- [`ComfyUI-PillowImageSaver`](https://github.com/ruminar/ComfyUI-PillowImageSaver)

For these saver nodes, connect:

```text
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

```text
🏹 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

```text
🎯 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

```text
🌑 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:

```text
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:

```text
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.

<img width="1440" height="1150" alt="image" src="https://github.com/user-attachments/assets/90b43e08-e759-4b56-ad6f-0be0c64e4afd" />

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:

```text
🎯 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.

<img width="1348" height="923" alt="image" src="https://github.com/user-attachments/assets/82ad36fe-1b04-457f-863c-6ca17b70ed8b" />

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:

```text
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:

```text
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:

```text
ComfyUI/output/CheckpointHandpickerSuite/delete_scripts/
```

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

Example:

```bash
python delete_reserved_checkpoints.py
```

The generated script asks for confirmation before deleting:

```text
[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.