ruminar-ComfyUI-CheckpointHandpickerSuite/RELEASE_NOTES.md

ComfyUI-CheckpointHandpickerSuite 0.3.1

ComfyUI-CheckpointHandpickerSuite 0.3.1 is a maintenance release for Cycler correctness, node-menu organization, and documentation accuracy.

Changes

Fixed mode now ignores status filters

Checkpoint Name Cycler in fixed mode now always uses its selected start_checkpoint, regardless of the active status Filter. Local List remains the only intentional temporary override of fixed mode.

This restores the documented normal-checkpoint-selector behavior and prevents an unrelated Filter from silently selecting another checkpoint.

Shallower node menu

The four main nodes now appear directly under HandpickerSuite. Ephemeral Preview and ImageDir Preview appear under HandpickerSuite / Preview.

Node registration names and sockets are unchanged, so existing workflows continue to load without reconnecting nodes.

Documentation and regression coverage

• Corrected the documented outputs of Checkpoint Status Tagger and Ephemeral Preview; both are terminal nodes without output sockets.
• Corrected the documented three-output interface of Checkpoint List Selector.
• Added executable regression tests and GitHub Actions coverage for all four Cycler modes, the Local List override contract, public node registration, menu categories, and output contracts.
• Added the current behavior specifications under .spec/ to version control.

Compatibility

Existing workflow node IDs, registration names, inputs, and outputs are unchanged. Only node-menu placement has changed.

Upgrade notes

Update the custom node and restart ComfyUI. Existing workflow nodes do not need to be recreated.

---

ComfyUI-CheckpointHandpickerSuite 0.3.0

ComfyUI-CheckpointHandpickerSuite 0.3.0 adds portable backup and restore for checkpoint evaluations.

Highlights

Checkpoint Tag Export / Import

The new standalone Checkpoint Tag Export / Import management node backs up evaluated checkpoint tags to JSON and merges them into another ComfyUI environment without moving checkpoint files.

• Export and Import run directly from the node and do not use the ComfyUI queue.
• Export files are written atomically under output/CheckpointHandpickerSuite/.
• An optional Tag Transfer Directory field accepts an existing full local or network path, allowing several PCs to share exports without manual copies. A blank field uses the default output location.
• Portable matching uses checkpoint file name and file size, not directories, drives, or timestamps.
• Import fills only currently untagged checkpoints. Existing equal tags are unchanged, and different tags are reported as conflicts without being overwritten.
• Missing and ambiguous checkpoints are skipped safely.
• Imported delete tags do not create deletion reservations or touch checkpoint files.
• Refresh All clears stale delete tags when their checkpoint files no longer exist, even if the original deletion reservation is unavailable.
• A successful Import immediately refreshes HandpickerSuite tag state in every open browser tab.

Import automatically selects the greatest timestamp string in a matching export filename. Timestamp validity and future dates are intentionally not checked, so renaming a file to a future timestamp can explicitly prioritize it. If the selected latest JSON is invalid, Import stops instead of falling back to an older export.

Custom transfer directories are never created automatically and never fall back silently to the default. Export uses unique temporary files and a same-directory reservation so simultaneous writers sharing a directory do not publish partial JSON files or overwrite the same timestamped export.

Compatibility

Existing workflows, nodes, and socket types are unchanged. The export document format starts at format_version: 1 and is versioned independently from the package.

Upgrade notes

Update the custom node and restart ComfyUI. Add Checkpoint Tag Export / Import anywhere on the canvas; it has no connectable sockets and does not participate in workflow execution.

---

ComfyUI-CheckpointHandpickerSuite 0.2.1

ComfyUI-CheckpointHandpickerSuite 0.2.1 is a maintenance release focused on ImageDir Preview performance and documentation.

Changes

Bounded ImageDir Preview search

ImageDir Preview now stops collecting matching image candidates when the internal candidate limit (currently 3,000 matching images) is reached.

Previously, the candidate list was truncated only after the directory walk had finished, so a large output directory could still consume unnecessary time and memory. The scan now stops at the limit and sorts the bounded candidate set by modification time before selecting preview images.

Japanese documentation improvements

The Japanese usage guide now includes a job-time checkpoint evaluation workflow using Ephemeral Preview and Checkpoint Status Tagger.

Formatting and navigation in the Japanese documentation have also been corrected.

Compatibility

There are no public node or socket changes in 0.2.1.

The intentional socket roles remain:

• ckpt_name for checkpoint-loader-compatible connections
• ckpt_name_str for Checkpoint Status Tagger and ImageDir Preview
• ckpt_name_safe for filesystem-safe labels

Existing 0.2.0 workflows should continue to work without reconnecting nodes.

Upgrade notes

Update the custom node and restart ComfyUI.

---

ComfyUI-CheckpointHandpickerSuite 0.2.0

ComfyUI-CheckpointHandpickerSuite 0.2.0 is a major workflow upgrade for checkpoint review, tagging, thumbnail setup, and generated-image cleanup.

This release turns the suite from a checkpoint cycling/tagging helper into a more complete checkpoint review desk: you can now review generated images per checkpoint, choose the best image as the checkpoint thumbnail, delete failed preview images, and tag checkpoints while reviewing images either inside ComfyUI or externally on a tablet/shared folder/image viewer.

Highlights

👑 New god! status

A new top-tier status has been added above favorite.

Status order:

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

Use god! for hall-of-fame checkpoints or models you absolutely want to keep.

delete remains a reserved deletion state. Checkpoints are never deleted immediately when tagged.

ImageDir Preview actions

ImageDir Preview can now do more than display a contact sheet.

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

• Delete image
• Set as checkpoint thumbnail

Set as checkpoint thumbnail

You can now set the best generated image as the checkpoint thumbnail directly from ImageDir Preview.

This is especially useful when paired with model manager tools that display sidecar checkpoint thumbnails.

Delete generated preview images

You can now delete failed generated images directly from ImageDir Preview.

• Deletion asks for confirmation.
• Images are deleted directly from disk.
• The contact sheet layout is preserved.
• Deleted tiles are marked with a NO IMAGE overlay.
• Deleted tiles become inactive and do not open the action menu.

This is intended for quickly cleaning up failed AI-generated images while reviewing checkpoints.

🌑🌕 DirectLink mode

Checkpoint List Selector now supports DirectLink mode for external image review.

Use this when you want to review generated images outside ComfyUI, for example:

• on a tablet
• in a shared folder
• in an external image viewer
• on a larger monitor

Connect:

CheckpointListSelector.ckpt_name_str -> CheckpointStatusTagger.ckpt_name_str

When this connection is detected, the Selector button becomes:

• 🌑 DirectLink OFF
• 🌕 DirectLink ON

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

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

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.

If ImageDir Preview is connected, the Selector uses normal Sync mode instead.

Selector action button cleanup

Checkpoint List Selector now changes its main action depending on what it is connected to:

• No review node connected:

  • 🏹 Push to Local List

• Connected to ImageDir Preview:

  • 🎯 Sync Checkpoint

• Connected only to Checkpoint Status Tagger:

  • 🌑 DirectLink OFF / 🌕 DirectLink ON

The old List Only button has been removed from the normal UI. Internal refresh behavior remains available where needed.

Tagger UI improvements

Checkpoint Status Tagger has been cleaned up for better readability.

• The current tag status is easier to read.
• Delete guidance text is shorter.
• The message area is more compact.
• DirectLink source text is not shown in the Tagger, to keep focus on the current tag state.
• DirectLink ON/OFF state is shown by the Selector instead.

Delete script output moved to output

Checkpoint deletion scripts are now exported to:

ComfyUI/output/CheckpointHandpickerSuite/delete_scripts/

instead of the ComfyUI temp directory.

The folder is created automatically when needed.

This makes deletion scripts easier to find and less likely to disappear unexpectedly when temp files are cleared.

Sidecar thumbnail cleanup support

When creating checkpoint deletion scripts, the suite now also includes managed sidecar thumbnail candidates for the checkpoint.

This helps keep checkpoint folders cleaner after deleting reserved checkpoints.

Checkpoint deletion is still script-based and confirmation-based. No checkpoint file is deleted immediately from the UI.

ListSelector thumbnail preview

Checkpoint List Selector can show sidecar checkpoint thumbnails while hovering checkpoint rows.

This makes it easier to recognize checkpoints visually before selecting or tagging them.

Recommended companion saver nodes

For best results, use this suite together with one of these saver nodes:

• ComfyUI-GMImageSaver
• ComfyUI-PillowImageSaver

Connect ckpt_name_safe to the saver node's label input.

This lets generated images be saved into checkpoint-aware filenames or directories, making ImageDir Preview, thumbnail selection, and cleanup much more effective.

Notes

This release keeps the review-first cleanup philosophy:

• tagging a checkpoint as delete only reserves it for deletion
• checkpoint deletion is performed later by an exported script
• generated image deletion in ImageDir Preview is immediate, but requires confirmation

Upgrade notes

After updating, restart ComfyUI.

If an existing workflow contains old Checkpoint Status Tagger or Checkpoint List Selector nodes from earlier versions, recreating those nodes may help ensure the latest UI and connection behavior is used.