SF Claude Library Builder

SF Claude Library Builder is the unglamorous half of a two-node pair, and it does the actual work. It opens every image in a folder and writes a searchable manifest.json describing each one - category, archetype, tags, a one-sentence description - plus a project-level art style sentence. Once that exists, SF Claude Asset Director can choose reference images from your library without opening a single file, which is the whole reason the pair exists.

Think of it as captioning, with the discipline the community settled on for LoRA datasets: same keys on every entry, a small shared vocabulary instead of a new word per asset, and descriptions written so someone could pick the asset without seeing it.

How it works

It doesn't hand your whole library to one Claude session - that's the failure mode it was built to avoid. It chunks the library into batches of batch_size assets (15 by default), and each batch call gets an instruction scoped to just its own files, with Claude told to open each one before describing it. That runs through the Claude Code CLI on your existing login: claude -p <batch brief> --output-format json, working directory set to your library root, --allowedTools Read. No API key, no token billing.

Claude never writes your files. It replies with JSON and the node assembles and saves the manifest itself; the Write tool is never offered. In read-only mode the only tool it gets is Read.

Progress is checkpointed per batch. After each successful batch the node writes a hidden .sf_library_builder_checkpoint.json and clears it on success. If a run dies, rerunning resumes and skips the batches already paid for. The checkpoint is fingerprinted by mode, manifest_name, system_prompt and project_notes - edit the system prompt or project notes mid-way and it starts fresh instead of resuming.

There's a neat self-repair in there too: if a batch's reply comes back cut off mid-JSON because the model ran past its reply length, that batch is retried as two halves, and split again if needed. A single asset that still fails is a hard stop.

Inputs you'll actually set

• library_path - the folder to catalogue.
• mode - the important one. Default is manifest only (read-only): nothing moves. organise into a copy writes a tidy renamed copy to output_path and leaves originals alone. organise in place renames and moves your real files.
• write_manifest - off by default. In manifest-only mode you get the JSON back as text and nothing is written to disk. That's a good first run: read it, sanity-check the tags, then turn this on.
• project_notes - the genre, art direction, naming you prefer. Anything Claude can't infer from pixels.
• update_existing - on by default, and the feature you'll use most. It reads the manifest already in the library, reuses those descriptions, drops entries whose file is gone, and only sends genuinely new assets to Claude. Drop five new assets into a 500-file library and you pay for five. (Skipped in copy mode, where manifest paths point at the renamed copies and can't be matched back to your source folder.)
• batch_size - 15. Raising it means fewer calls and more risk of a rambling batch; lowering it is the fix when things get flaky. timeout_seconds is per batch, not per library, so don't shrink it thinking you're being efficient.

system_prompt ships with a sensible default you should edit per project, manifest_name is the output filename, model picks default/opus/sonnet/haiku, and seed is only there to bust ComfyUI's result cache.

Outputs

manifest is the JSON text, and report is a human summary - files scanned, reused versus newly catalogued, category breakdown, art style, elapsed time and the CLI's reported cost. Send report to a Show Text node; it's how you spot "12 files were not catalogued" without reading logs. Asset Director takes a manifest filename, not a connection, so write_manifest on is the low-friction path.

Install

ComfyUI Manager → search "SF ComfyUI Nodes". Or:

cd ComfyUI/custom_nodes
git clone https://github.com/Stillfront/comfyui-sf-nodes.git
cd comfyui-sf-nodes
pip install -r requirements.txt

requirements.txt pulls torch, pillow, numpy<2.0.0, pydantic, plus google-genai and google-cloud-storage for the VertexAI nodes - heavy, but not needed here. Skip config.ini; that's WaveSpeed. The genuine requirement is Claude Code installed and signed in on the ComfyUI machine, found on PATH or in ~/.local/bin, ~/.claude/local, /opt/homebrew/bin, /usr/local/bin. Restart ComfyUI afterwards.

Where people get burned

Budget about 5 seconds per asset. It opens every image, so 300 assets is a long coffee break and a lot of Claude calls. Rate limits on a Claude subscription are the thing that actually bites here, not dollars.

"organise in place" moves your files. It hands Claude Bash, in your asset folder, with instructions to rename to lowercase_with_underscores and group into characters/heroes, environments and so on. It's genuinely good on a folder of final_v2 copy.png. Try it on a copy of a copy first. In copy mode, output_path must sit outside library_path - the node refuses otherwise.

"Nothing new to catalogue" is not an error. It means update_existing matched everything in your manifest.

A gap between the two nodes: this node's scan includes .tga files and Asset Director's does not, so TGA assets get catalogued and then can never be picked. Convert them. And remember the timeout is per batch: if one dies, finished batches are already checkpointed, so fix the setting and re-run with the same values to resume rather than restart.