Vito
043403d09e
* refactor(thumbnails): one resolver for where previews live on disk (#320) Add py/api/preview_store.py: the store of a source, a preview's path, URL parts to disk, containment (owns), a write generation and the lock around every preview's final rename. Every preview reader, writer and remover now asks it instead of joining <source>/thumbnails by hand: serve, on-demand, capture (its path resolved when the write starts), the after-scan queue, the thumbnail plans and job payloads, clear, the temp sweep, History covers, the auto-tag listing and the owned-preview lookups. Source mode only: every path is the one built before, so nothing changes on disk or on the wire. A structural test keeps new thumbnails joins out of the backend. * refactor(thumbnails): keep the after-scan queue's store rule and pin the write lock (#320) A planned target keeps the plan's own containment rule (inside the store, as the thumbnail job writes it); captures keep the serve rule. The structural test also covers PREVIEW_FOLDER joins and the repo-root modules; the write-lock test asserts the lock instead of waiting on a timer; new tests cover nested roots in the after-scan queue and a legacy upper-case preview served through the resolver. * feat(thumbnails): keep previews in one folder, set from config.json (#320) thumbnails.location in config.json can now name one folder for every source's previews: <folder>/<source key>/<rel>_thumb<ext>. A source key is a readable slug plus a short hash of the source's identity, stored in the folder's marker (.promptmanager-thumbnails.json) with the install that made it. Serving, on-demand and capture writes, listings, clear, delete, duplicates, the temp sweep and History covers all follow it; a leftover in <source>/thumbnails is never served and other text under thumbnails/ is refused. A missing, unplugged or foreign folder is unavailable (a probe checks it every 5 s within 2 s; a stalled or failing store call flips it at once): originals are served, nothing is written anywhere, the folder is never re-created, and generate, convert and clear answer 409 location-unavailable. A bad config value is unavailable too, never a fall-back to the sources. No UI yet: POST /settings refuses thumbnail_location (409 location-needs-move); GET /settings reports it with its path, the thumbnail status without one. Sources inside or around the folder and a library move into it are refused. * fix(thumbnails): never follow a marker or a link out of the thumbnail folder (#320) Marker keys are data, not paths: only a single <slug>-<hex> folder name is ever joined onto the thumbnail folder; anything else is dropped and logged. Every preview write and delete passes one ownership check (below a key folder, lexically and resolved, no link, junction or reparse point on the way); make_parent refuses anything else and writes nothing while the folder lacks this install's marker (an unmounted mount point). Clear never descends into a junction. The configured location is in force before any request (unchecked folder mode is unavailable), and a startup check that fails leaves it invalid, never the sources. Older listings that run on the event loop no longer touch the store in folder mode. A leftover under another case of thumbnails/ on a case-insensitive disk is refused too. * test(memory): let the musl test fake os.confstr on Windows (#523) The portability run on main fails since #523: Windows has no os.confstr, so patching it without create=True raises before the test runs. * feat(thumbnails): move thumbnails between the sources and one folder (#320) POST /images/thumbnails/plan reviews a move (what is copied, removed and left, free space, too-long Windows paths, sources no longer listed) and hands out a token; POST /jobs/thumbnails {mode: move} runs it as a thumbnails job: hold automatic previews, copy and check every preview on the job pool, switch with one config commit that records the old copies, then remove them. Per-file errors still switch; a folder-wide error, a cancel before the switch or a crash leaves nothing changed (a journal is undone at the next start); old copies that could not go are removed by a finishing job at the next start. Leaving a folder removes the previews of this install's sources that are no longer listed (Q320-8). Recreate folder and Use this folder answer an unavailable folder; the Thumbnail maintenance scope prune removes the thumbnails of removed sources. * feat(system): choose where thumbnails are kept and move them (#320) System › Sources & scans gains the Thumbnail location row (D196): Inside each source or One folder, the folder path, the status line and Review move…, whose review (D197) lists what is copied, removed and left before Move thumbnails starts; a refused folder is explained under the field, a folder of your own asks for a confirmation first. Activity shows a move and a prune with their own tiles and step line (D198). An unavailable folder shows a notice on Overview and Sources & scans with Recreate folder or Use this folder (D199). Thumbnail maintenance offers Remove thumbnails of removed sources in folder mode (D200), and Move library's review says where the thumbnails stay (D201). Closes #320 * fix(thumbnails): keep a move's own previews and never walk out of a store (#320) A cleanup that waited from an earlier move never names a key folder the new move just filled, so moving back keeps the previews. Removing empty folders walks top-down and never into a link or junction. Any error while copying undoes the copies; once the switch is committed, a journal that cannot be removed no longer undoes it. Hand-edited cleanup entries and marker keys never name a folder outside the stores; removal stops at interpreter exit. The path field carries aria-invalid with its reason, and a review that went stale reviews again. * test(thumbnails): cover the prune scope, the Overview notice and the space refusal (#320) The frontend coverage gate counted the new branches of thumbnail maintenance, the Activity views, the notices' Change location and the api-client's space refusal as uncovered; page and unit tests now drive them. * fix(thumbnails): report removals that fail and explain the quiet excepts (#320) An old thumbnail the finishing move cannot remove (held open on Windows) is now an error row of the job with its path, and logged; a failed copy's temp that cannot go is logged with its path. Every except that only passes says why, and the thread runners say their caller re-raises. * fix(thumbnails): never plan or delete through a linked key folder (#320) Review finding P1 on #591: in folder mode a source key folder that is a link or junction to a folder outside was still handed to the planner, so Convert outdated could remove an older-format file outside the thumbnail folder. ensure_store now refuses a linked store before any planning, and each removal of an old preview passes may_write at the moment it runs. * fix(thumbnails): the temp sweep never walks into a link (#320) Review finding P2 on #591: Clear thumbnails and the startup sweep removed crashed-write temps with a plain os.walk, which on Windows walks into a junction even without followlinks. The sweeper now skips a folder that is a link, junction or reparse point (the top one too), and each temp passes may_write before it is removed. * fix(thumbnails): lock the folder marker across processes (#320) Review finding P2 on #591: two installs sharing one thumbnail folder could each read the marker, add a key and replace it, so the last writer dropped the other's key. write_marker now re-reads, changes and replaces the marker under a lock file made with O_CREAT | O_EXCL beside it (atomic on shares, unlike flock); a lock older than 30 s, left by a writer that died, is taken over, and a wait past 1.5 s fails as a TimeoutError like an unreachable folder. Tested with three processes adding keys at once. * test(thumbnails): cover the space refusal, Overview's Use this folder and the prune review (#320) The frontend coverage floors of activity-kinds, system-overview and thumbnail-review: a disk without the space shows the review but cannot move (a fixture route fakes the free space), Use this folder on Overview reloads the host values, the prune review's text and rows are pure functions with unit tests, and Overview takes the System drafts it is always mounted with. * fix(thumbnails): never copy through a linked folder; refuse a target inside the folder in use (#320) Moving back to Inside each source followed an existing linked folder in the destination and could replace a file outside the source (Codex P1). A target nested inside the thumbnail folder in use was accepted, and the old-copy cleanup then removed the previews just copied there (Codex P2). Every copy now checks the whole destination chain for links, also when the folders exist, and the move refuses a folder inside the one in use with location-inside-current. The cancelled branches no longer mix explicit and implicit returns (code-quality note). * fix(system): one full stop in the move-back review (#320) * fix(thumbnails): a folder check answers for the folder as it is now (#320) Probe.check() joined a check already running, or a finished one nobody had collected. A folder deleted right after configure() woke the probe therefore stayed available until the next probe, which failed the Overview notice spec in the merge queue. It now waits for a running check and starts a new one, still never two at once, and a stuck check still times out. The spec also asserts the fixture's removal took effect.
ComfyUI Prompt Manager
Every prompt you run, every image it made, and every negative you tried, in one searchable library inside ComfyUI.
Prompt Manager saves your prompts as you generate, links each image back to the prompt that made it, and gives you one page to browse, tag, compare and reuse all of it. Your library is a local SQLite database on your own machine.
What's new: rebuilt from the ground up
- A new UI. One app, the workspace, replaces the separate dashboard, gallery and metadata pages. The old pages still work if you want them.
- Classic and Nodes 2.0. The nodes work in both ComfyUI renderers. CI starts a real ComfyUI and checks both.
- Tested end to end. Unit tests, browser tests in Chromium, Firefox, WebKit and touch emulation, and tests against a real ComfyUI.
- Mac, Linux and Windows. The Python suite runs on all three, on Python 3.12, 3.13 and 3.14.
See it
All images on this page were generated and recorded through Prompt Manager in a clean demo library.
Your whole output folder, finally browsable
Masonry, grid or list, with search, categories, filters and saved views. Images and videos sit side by side, and selecting one shows its prompts and settings without leaving the page.
Open any image and see how it was made
The viewer shows the positive and negative prompts, tags, seed, steps, CFG, sampler and model next to the image.
Keep your hands on the keyboard
The viewer has shortcuts for moving between files, the slideshow, zoom, rotate, flip, full screen, details, download and delete. Press ? to see them all.
Long libraries stay easy to work in
The selection bar stays pinned while you scroll, so you can keep picking images and act on them from anywhere. Back to top appears once you've scrolled down the page.
One positive prompt, many experiments
The Prompt library groups everything by positive prompt, so repeat runs and negative variants stay together instead of filling your list with near-duplicates.
Watch your negatives branch on a timeline
Each prompt has its own page with a timeline of its negative variants. Click a red dot and the gallery filters to the images that negative made. Small dots mark repeat runs.
Compare negatives term by term
Compare negatives shows two variants side by side and lists the terms one adds, so you can see what actually changed between runs.
Auto-tag your images, and approve what sticks
Tag one image, a selection or your whole output with WD14 or JoyCaption. WD14 suggestions come with confidence scores, and you can review suggestions before anything is saved. Auto-tags belong to the image, so they never change your prompts.
Keep your vocabulary tidy
Tags & categories lists every tag and category with how often it's used. Rename, merge and delete tags, and preview a category change before you apply it.
Group images your own way
Collections are hand-picked sets of images, on top of favorites and saved views. Add from the selection bar and they appear in the sidebar.
Nothing gets guessed
When a file's metadata has more than one possible prompt, Prompt Manager doesn't pick for you. The file waits in Needs review, where you can choose the sampler path, link it to any prompt in your library, or leave it unresolved.
Inspect any file, without importing it
Pick an image or video from your computer to read its prompts, settings and workflow. The file is read in your browser. It isn't uploaded or added to your library.
Send a prompt back to your canvas
Pick an open ComfyUI window and a node, then review the exact before and after. Nothing changes until you apply it.
Deletes you can review
Choose what happens to the files before anything is removed: remove the image from the library and leave the file on disk, or on Linux and macOS also move it to the system trash. On Windows, images can only be removed from the library. A safety backup of the database is on by default, and removed images can be brought back.
Maintenance in one place
System holds settings, image sources, auto-tag models, integrations, maintenance, backups and logs. Risky operations show a review first, and long ones run as jobs you can follow in Activity.
Works on your phone too
The workspace adapts to narrow screens, and touch is part of the browser test suite.
The nodes
Six nodes, under ComfyAssets > Prompts in the Add Node menu. Pick the one that suits your workflow; they all share one library. Every screenshot below is a small real workflow that ran.
Prompt Manager (Classic)
The drop-in replacement for CLIP Text Encode: same CLIP input, same CONDITIONING output, with the prompt saved as it runs. It also outputs the text as a STRING.
The same workflow in Nodes 2.0:
Prompt Manager (Focused)
An editor-first layout. Composition and metadata fold away, and Browse library lets you search, preview and use a saved prompt right on the node.
Prompt Manager (Split)
The same editor with the library always visible. Wide nodes put them side by side; narrow nodes stack them.
Prompt Manager (+/-)
Positive and negative in one node, saved as a pair. This is the node that feeds the negative-variant timeline. It outputs CONDITIONING and STRING for both sides.
The same workflow in Nodes 2.0:
Prompt Manager Text
Saves the prompt and outputs a STRING instead of CONDITIONING, for workflows that send text to another node. Prepend and append inputs let you build the final text.
Prompt Search List
Searches your library by text, category, tags and minimum rating, then outputs the matches as a list so ComfyUI runs each one. This workflow found three prompts tagged mushroom and made three images.
To get the images of a Search List batch linked to their prompts, wire the Search List output into a Prompt Manager Text node, not straight into CLIP Text Encode. Wired straight in, the images stay unlinked: the search text is never saved as a prompt.
Install
Requirements: ComfyUI and Python 3.12 or newer. watchdog and Pillow are the only dependencies of their own; the rest comes with ComfyUI.
Install from the Comfy Registry or ComfyUI-Manager (search for Prompt Manager), or by hand:
cd ComfyUI/custom_nodes/
git clone https://github.com/ComfyAssets/ComfyUI_PromptManager
pip install -r ComfyUI_PromptManager/requirements.txt
Restart ComfyUI. Click PM in the top bar, or Web UI on a node, or open http://localhost:8188/prompt_manager/workspace.
Optional extras. Nothing here is installed for you:
| To use | You need |
|---|---|
| WD14 auto-tagging (about 400 MB per model) | onnxruntime, or onnxruntime-gpu for CUDA |
| GGUF JoyCaption (about 4.5 GB) | llama-cpp-python |
| HuggingFace JoyCaption (about 16 GB) | transformers, accelerate, bitsandbytes |
| Prompts embedded in videos | ffprobe on PATH |
| LoRA Manager import | LoRA Manager installed; turn it on in System > Integrations |
Download or unload tagging models in System > Auto-tagging.
Where your data lives
| What | Where |
|---|---|
Library (prompts.db), config.json, database backups, logs |
ComfyUI/user/__promptmanager/ on new installs |
| Thumbnails | output/thumbnails |
| Your images | Left where they are. Prompt Manager reads your output folder and any sources you add. |
Set PROMPT_MANAGER_DATA_DIR to an absolute folder to keep the library somewhere else. config.json can hold your CivitAI key, so treat it as private.
Upgrading from an earlier version
- Python 3.12 or newer is now required.
- Your library stays where it is until you choose. The workspace offers Move library, which makes a verified copy in
user/__promptmanager/and renames the old files instead of deleting them, or Keep it here. - Older images: a one-time notice offers a metadata scan that links them to prompts and negatives. Scans don't count as new runs.
- Going back isn't supported. Workflows are now stored once, and an older version shows new records without their workflow or prompt graph. Back up first in System > Backup & export. See the old README's changelog for the manual way back.
The old pages still work
They stay at their URLs, and System's Overview section links to them:
| Page | URL |
|---|---|
| Dashboard | /prompt_manager/admin |
| Tags | /prompt_manager/admin#/tags |
| Gallery | /prompt_manager/gallery |
| Metadata viewer | /prompt_manager/gallery.html |
The documentation for those pages is in README-legacy.md.
Known limits
- Trash is Linux and macOS only. Windows has no Recycle Bin option, because the bin can delete large files permanently without warning. On Windows you can only remove an image from the library, and the file stays on disk. Where a move to the trash isn't possible on Linux or macOS, the dialog lists why for each file.
- Show in folder opens the file manager on the machine running ComfyUI, not necessarily the one with your browser.
- Returned images get their prompt links back, but not their tags, categories, collections or favorites.
- Inspect a file doesn't add the file to your library.
- Leave unresolved is permanent. A file you leave unresolved in Needs review isn't offered again unless its bytes change.
- Pair prompts saved by earlier versions stay Uncategorized. You can set the category with Edit metadata.
How it's tested
| Layer | What runs |
|---|---|
| Python | Over 200 test files on Linux and Windows with Python 3.12 to 3.14, with an 85% coverage gate |
| Frontend | About 100 unit test files, with coverage floors per file |
| Browser | Over 60 Playwright spec files in Chromium, Firefox, WebKit and touch emulation |
| Real ComfyUI | A pinned CPU ComfyUI, started in Classic and Nodes 2.0, running real workflows |
Linux runs on every pull request and in the merge queue. Windows runs on every push to main and nightly. macOS is not tested; it should work, but support is best-effort. To run the tests yourself, see TESTING.md.
License
MIT. See LICENSE.