combuddy 0.2.1

A local model & workflow dependency manager for ComfyUI

combuddy

A local-first dependency manager for your ComfyUI models and workflows — see what's used, what's missing, and what's safe to delete.

A model & workflow dependency manager for ComfyUI. Point it at your local model library and workflow files, and it shows you how they depend on each other — which workflows use which models, which models nothing uses, and which models a workflow is missing. Local-first: model identity (base architecture, precision, parameters) is computed from file headers; optional Civitai enrichment by content hash is on by default and toggleable in settings.

Why

Community workflows reference models by bare filename — no download link, no hash. Over time you lose track of what a model is, which workflows need it, and what's safe to delete. combuddy answers those from what's already on your disk:

• Dashboard — total models & size, base-architecture coverage, and how many models nothing references.
• Model library — search/filter every model; click one to see its details and the workflows that reference it (reverse dependencies).
• Workflow resolution — pick a workflow, see each referenced model marked hit / ambiguous / missing.
• Cleanup — the models no workflow uses, with reclaimable space, moved to a recoverable trash (never a hard delete; only 0-reference models can go).
• Offline identity — base architecture (SD1.5/SDXL/Flux/…, incl. GGUF), role labels (text encoder, VAE, ControlNet, …), and precision, all read straight from file headers.
• Civitai identity — for models found on Civitai by content hash: real name, base model, trigger words, and a cached preview thumbnail with HD zoom. Enrichment sends only the hash, is on by default, and is toggleable in settings.

Features

• Model library + Civitai enrichment — every model in one searchable, filterable grid, with real names, preview thumbnails, and trigger words looked up from Civitai by content hash (only the hash ever leaves your machine). Offline identity — base architecture, precision, parameter count — comes straight from local file headers, Civitai match or not.

  

• Reclaimable duplicate detection — models are grouped by exact (byte-for-byte, sha256) content match, so you see at a glance how much disk space duplicates are wasting, then clear the unreferenced copies in one click to a recoverable trash.

  

• Workflow dependency resolution — pick a workflow and see every model it references marked hit, ambiguous, or missing, so you know what a shared workflow actually needs before you run it.

Install & run

Requires Python 3.11+.

pipx install combuddy   # recommended — isolated env, `combuddy` always on PATH
pip install combuddy    # alternative, into your current environment
uvx combuddy            # or run without installing (needs uv)

combuddy         # scan your own model library and workflows
combuddy demo    # zero-config tour: bundled sample data, no local library needed

combuddy starts a local server on http://127.0.0.1:8511 and opens your browser. On first run, point it at your ComfyUI models directory and workflows directory (e.g. .../user/default/workflows); it scans and populates the Dashboard in seconds. No library handy? combuddy demo seeds a temporary database with bundled sample models and workflows and opens the same UI — a full tour, no setup required.

How it works

• Scans model directories (skipping noise and its own trash), and parses ComfyUI workflow JSON for model references.
• Matches references to local files by directory type + normalized relative path (handling subfolders, case, Unicode, and backslashes) — not by fragile basename guessing.
• Computes content hashes for identity; optional Civitai enrichment sends only the hash to look up real names and metadata.
• Stores everything in a single local SQLite index; the UI reads it live.

Tech stack

• Backend: Python 3.11+, FastAPI, standard-library sqlite3 (no ORM). One command (combuddy) runs Uvicorn and serves both the API and the UI.
• Frontend: Vue 3, Vite, PrimeVue, Tailwind — built into combuddy/web/ and served by the backend, so the whole app installs as one package.

Development

pip install -e ".[dev]"     # backend + test deps
pytest -q                    # backend tests

cd frontend
npm install
npm test                     # frontend tests (Vitest)
npm run dev                  # dev server, proxies /api to :8511
npm run build                # rebuild the bundle into ../combuddy/web

After changing anything in frontend/src, run npm run build — the packaged app serves the committed combuddy/web/ bundle.

Status & roadmap

v1.2 — local-first with optional Civitai enrichment (real names, preview images, trigger words by content hash, default on and toggleable). Planned next: download center for missing models, and dependency pinning for shareable, self-healing workflows.