ComfyUI-Droplet-Commander

🪿 Droplet Commander

Run a Photoshop droplet on your renders, right from ComfyUI. This node hands images from your graph to a real Windows Photoshop droplet (a compiled Photoshop Action), waits for it to finish, and reads the processed images back in — bridging a Linux ComfyUI running in WSL2 to native Windows Photoshop, with no Wine.

⚠️ This is built for a specific system

It was written for one setup: ComfyUI running in WSL2 (Ubuntu) with Photoshop native on Windows 11, talking to each other over WSL interop. If that's your setup, it should work well. If it isn't, it will not work as-is — but the Windows/WSL-specific parts (path translation and launching the .exe) are isolated in a handful of functions, so it's very adaptable. See Adapting to another system. Shared in the hope it's useful; offered as-is, no guarantees for other environments.

---

Table of contents

1. What it is
2. Requirements
3. Installation
4. The one thing you must decide: where the droplet saves
5. Two source modes
6. Inputs
7. Path formats
8. Authoring the droplet
9. Troubleshooting
10. Outputs
11. Adapting to another system
12. Versioning & releases
13. License

---

What it is

A Photoshop droplet is a small .exe you export from Photoshop that runs a recorded Action on every file (or folder) dropped onto it. Droplet Commander drops your rendered images onto that droplet and reads the finished images back into the graph.

Think of the droplet as a black box you feed files to — Photoshop opens each one, runs your Action, and saves it wherever the droplet was told to save. That last part is the whole ballgame; the node's job is to find whatever the droplet wrote and bring it back.

When it loads you'll see it announce itself in the ComfyUI console:

====================================================
  🪿  Mess with the HONK you get the BONK.
====================================================

---

Requirements

• ComfyUI on WSL2 (Ubuntu or similar) — the node calls wslpath and launches a Windows .exe through WSL interop.
• Windows Photoshop with a droplet you've exported (see Authoring the droplet). Developed against CS6; newer versions should be fine.
• Python packages numpy and Pillow (installed automatically by ComfyUI Manager, or via requirements.txt). torch is already provided by ComfyUI.

---

Installation

Option A — ComfyUI Manager (recommended)

Once this repo is published to the Comfy Registry, search for Droplet Commander in ComfyUI Manager → Custom Nodes Manager and click Install.

Until then (or instead), use Manager's Install via Git URL: paste your repo URL (https://github.com/hodgemann/ComfyUI-Droplet-Commander) and restart ComfyUI.

Option B — Manual (git clone)

cd ComfyUI/custom_nodes
git clone https://github.com/hodgemannE/ComfyUI-Droplet-Commander
cd ComfyUI-Droplet-Commander
pip install -r requirements.txt   # numpy + Pillow; usually already present
# restart ComfyUI

The node appears under the 🪿 Droplet Commander category.

Option C — Publishing to the Comfy Registry (for the maintainer)

1. Create a publisher at https://registry.comfy.org and copy your Publisher ID.
2. Edit pyproject.toml: set [tool.comfy] PublisherId and the [project.urls] Repository.
3. Install the CLI and publish:

   pip install comfy-cli
   comfy node publish
   

   See https://docs.comfy.org/registry/publishing for the full flow (API key, versioning).

Legacy Manager list: to appear in the older hard-coded Manager list you'd open a PR against ltdrdata/ComfyUI-Manager's custom-node-list.json. The Registry route above is the current, preferred path and requires no PR.

---

The one thing you must decide: where the droplet saves

Photoshop decides the output location, not this node — so the node has to find whatever the droplet wrote. It does that by watching three places and detecting files that appear or change, then reading them back the instant they stop changing:

1. droplet_output_dir — the droplet's own Save In folder, if you tell the node where it is.
2. C:\ComfyDroplet\out\ — the staging out\ folder (use this if you can point the droplet's Save In at it).
3. C:\ComfyDroplet\in\ — the input folder itself, for droplets that overwrite in place ("Save").

So pick one of these three strategies when you author the droplet:

| Your droplet's Action ends with… | What to set on the node | |----------------------------------|--------------------------| | Save In → C:\ComfyDroplet\out (recommended) | Nothing — leave droplet_output_dir empty. | | Save In → some other folder | Set droplet_output_dir to that exact folder. | | Save (overwrite the original) | Nothing — the node reads the overwritten inputs back. |

If none of these is true (e.g. the Action does Save and Close to a path that's none of the above, or doesn't save at all), the node finds nothing, waits the full timeout_seconds, and passes your original image through unchanged. That exact symptom — original image out, full timeout every run — almost always means "the droplet saved somewhere the node isn't watching." Fix it with the table above.

---

Two source modes

• In-Pipeline (IMAGE) — takes IMAGE tensors from your graph, writes them as PNGs to C:\ComfyDroplet\in\, runs the droplet once over that folder, waits for the processed files to settle, and reads them back out as tensors on the IMAGE output. This is the mode for "generate → Photoshop finish → save" in one graph.
• Standalone Folder — hands the droplet an existing folder of renders and waits for it to finish. Nothing flows back as tensors; OUTPUT_DIR reports where the results landed. Use this for batch post-processing of a folder you already have.

---

Inputs

| Input | Meaning | |-------|---------| | droplet | The .exe to run, chosen from the droplets/ folder in the package (also .bat/.cmd). | | source_mode | In-Pipeline (tensors in/out) or Standalone Folder. | | windows_scratch_dir | Windows base for staging; in\ and out\ are created under it. Keep it on a real Windows drive (C:\…), not the WSL home. Default C:\ComfyDroplet. | | timeout_seconds | Safety cap only. The node returns as soon as the output settles — it does not wait this long on success. Raise it only if a single Photoshop run genuinely takes longer. | | image (In-Pipeline) | The batch of tensors to process. | | folder (Standalone) | The existing folder of images to process. | | droplet_output_dir | Where the droplet's Save In writes, if it isn't out\. Accepts a drive path, a UNC WSL path, or a plain WSL path (all normalised). | | droplets_dir_override | Load droplets from another folder instead of the package droplets/. |

---

Path formats — all three are accepted

Anywhere you type a path, the node normalises it, so use whichever you have handy:

• Drive: C:\ComfyDroplet\out
• UNC into WSL: \\wsl.localhost\Ubuntu\home\you\out or \\wsl$\Ubuntu\home\you\out
• Native WSL: /home/you/out

Internally the droplet is always handed a Windows path and the node always reads via the WSL path, converted with wslpath (with a naive fallback when wslpath isn't present, e.g. off-WSL).

---

Authoring the droplet (do this once, in Photoshop)

1. Record your edit as an Action (Window → Actions).

2. File → Automate → Create Droplet. Save the .exe into this package's droplets/ folder.

3. In the Create Droplet dialog you must:

   • tick Suppress File Open Options Dialogs, and
   • tick Suppress Color Profile Warnings (or set a fixed colour policy).

   Skip either and Photoshop stalls on an invisible modal the moment a file opens — the node will look hung. This is the #1 failure.

4. Set Destination using one of the three save strategies in the table above. For the smoothest setup, choose Folder → C:\ComfyDroplet\out and tick Override Action "Save As" Commands.

---

Troubleshooting

| Symptom | Cause & fix | |---------|-------------| | Original image comes out unchanged and it always takes the full timeout_seconds | The node never found the droplet's output. Point droplet_output_dir at the droplet's Save In, or re-author the droplet to save to C:\ComfyDroplet\out, or to overwrite in place. See the save-location table. | | It hangs / never finishes | A Photoshop dialog is open. Re-create the droplet with both suppression options ticked. | | wslpath not available in the log | You're running off real WSL2 (e.g. a plain-Linux or dev box). The node falls back to a naive translation; on genuine WSL2 the tool exists and paths translate exactly. | | Output images are different sizes and only the first returns | The Action resizes inconsistently. Make the Action output a fixed size, or use Standalone mode and consume OUTPUT_DIR downstream. | | selected droplet not found | The .exe isn't in droplets/ (or in droplets_dir_override). |

The node logs which folders it watched on a timeout, so you can see exactly where it looked.

---

Outputs

• IMAGE — the processed tensors (In-Pipeline). On a genuine timeout it passes the input through unchanged so the graph doesn't break.
• OUTPUT_DIR — the folder the processed files were read from (feed a Save node, or use it downstream for Standalone batches).

---

Adapting to another system

Not on WSL2 + Windows Photoshop? The environment-specific pieces are small and isolated, so you can likely repoint them:

• Path translation lives in to_unix() / to_win() (and the _wslpath / _is_unc_wsl helpers). Swap these for your platform's mapping — or make them identity functions if your ComfyUI and image tool share one filesystem.
• Launching the droplet is one function, _run_droplet() — it just calls subprocess.run([exe, target]). Point it at any batch tool that accepts a file/folder argument (a shell script, an ImageMagick pipeline, a different editor's CLI, etc.).
• Completion detection (_await_outputs) is platform-agnostic already: it watches folders for new/changed images and returns when they settle. It doesn't care what produced them.

In other words, the "Photoshop droplet" is just "an executable that transforms files in a folder" — replace that executable and the two translation functions and the rest works. PRs and forks welcome.

---

Versioning & releases

• Current version: 1.0.0 (see CHANGELOG.md). Version lives in both pyproject.toml and __init__.py (__version__) — keep them in sync.
• Tag releases as vMAJOR.MINOR.PATCH (e.g. git tag v1.0.0 && git push --tags) and create a matching GitHub Release. Bump the version and publish to the Registry with comfy node publish.

---

License

MIT — see LICENSE. Edit the copyright holder line before you publish.