Metadata viewer & manager for ComfyUI generated images
Features • Status • Quick Start • Screenshots • Documentation • API
ComfyUI Meta Viewer is a local-first web application for viewing, organizing, and analyzing images generated by ComfyUI. Every generated file is treated as a carrier of reproducible intelligence: prompts, sampler settings, models, LoRAs, and the complete node graph are extracted from PNG text chunks, EXIF, and embedded ComfyUI workflow JSON - all in a fast, keyboard-driven interface.
Under the surface it is more than a gallery: metadata stays attached to the workflow that created it, the Media Library is a virtual database view over your real folders, AI prompting is compiled from layered model-aware skills instead of one universal system prompt, and the integrated ComfyUI runtime can turn an existing asset back into a queueable workflow - everything runs locally with no cloud dependency.
- Metadata extraction from PNG chunks, EXIF, and ComfyUI workflow JSON
- Interactive workflow graph visualization with color-coded nodes
- Live source monitoring for local and desktop-synced cloud folders, with no file copying
- Image and video uploads - drop supported media into the app; images stay lazy while videos receive technical metadata and a poster frame when FFmpeg tools are available
- Object cutout - automatic background removal with transparent PNG export
- SQLite persistence - all data survives restarts
- Media Library - virtual albums, favorites, ratings, tags, notes, and bulk selection without moving source files
- Unified image and video assets - shared sources, albums, favorites, previews, and technical metadata
- Unified media browsing - folders, albums, the central gallery, and the Media sidebar can show images and videos together or filter either type independently
- Create workspace - manifest-driven image, reference, video, and two-stage workflow templates with dynamic local model selection (partial - see Feature Status)
- ComfyUI execution - integrated runtime setup, dependency preflight, queue state, cancellation, result import, and workflow provenance
- Remix drafts - carry an asset prompt and lineage into a supported reference workflow without starting generation automatically (scaffold - see Feature Status)
- BYOK provider profiles - OpenAI-compatible endpoints with OS-keyring or environment-variable credentials, plus detected OpenCode, Claude Code, and Antigravity CLI adapters
- Model-aware prompt compiler - layered family, operation, scenario, modifier, and output-contract instructions with strict structured results
- Keyboard-first workflow with 14 shortcuts
- Virtuality first - albums, favorites, ratings, tags, and notes live in the database as a view over the real folders: nothing is moved, renamed, or copied. Even a factory reset rebuilds the index without touching a single source file.
- In-place indexing - sources are scanned in place with an incremental cache, and desktop-synced cloud folders can be watched continuously without duplicating data on disk.
- Provenance as data - the original ComfyUI workflow graph is preserved per asset, rendered as an interactive color-coded node graph, and available for re-import into the workflow editor.
- Local & private - runs on
localhostwith no cloud dependency; AI provider credentials are stored masked in the OS keyring or environment variables, and authenticated local CLIs (OpenCode, Claude Code, Antigravity) are discovered automatically. - Model-aware AI tooling - prompting is compiled from layered family (FLUX / SDXL / Pony), operation, scenario, and modifier skills into strict structured output, guarded by deterministic intent judges and CLI-run benchmarks; the same engine powers AI prompt enhancement and vision reconstruction inside Create.
- ComfyUI-native execution - detects and can auto-start a local ComfyUI (including portable installs), queues generation, and imports results back with full provenance.
- Unified media - images and videos share one pipeline: uploads, previews (video poster frames need FFmpeg), a virtual library, and independent media-type filters.
Not every planned surface is wired into the running product yet. This section separates what works end-to-end today from what is laid out as infrastructure (scaffold) but not yet usable from the UI.
Implemented - works from the UI today:
- Core viewer - gallery & lightbox, metadata tabs, folder scan + live source monitoring, fuzzy search, object cutout, image/video uploads.
- Media Library - albums, favorites, ratings, tags, notes, bulk selection, deletion to the system trash.
- Unified image/video assets - shared sources, albums, previews, and media-type filters (video previews require FFmpeg).
- BYOK AI providers - provider profiles with keyring/env credentials and local CLI discovery (OpenCode, Claude Code, Antigravity); the prompt compiler, intent/quality benchmarks, and smoke runners are functional via CLI.
- ComfyUI runtime - auto-detection/auto-start, queue, cancellation, result import, and workflow provenance.
- Create - generation - model download and workflow execution work for 5 of 8 bundled models (model_01-03, 07, 08).
Scaffold / partial - laid out, but not working end-to-end from the UI:
- Create - model_04 / 05 / 06 - shown as selectable in the UI, but still
calibration placeholders: resources can be downloaded, generation is blocked
(no
workflow.json/bindings.jsonyet). - Remix - the lightbox action creates a draft and jumps to the Create page,
but Create does not read
draft_idfrom the URL, so the handoff is a dead end. - Advanced Workflow Editor + AI operations (generate / translate / adapt /
reconstruct / enhance) - the backend is real, but the editor page is only
reachable at
/settings/comfyuior/editor/legacyand is unlinked from the main navigation. - Social publishing (VK / Telegram / Instagram) - provider cards render on the Integrations page, but publishing is unimplemented for all providers, and VK OAuth works only over port 80.
Metadata ExtractionPrompts, settings, models, LoRA, EXIF |
Workflow VisualizationInteractive SVG graph of ComfyUI nodes |
Folder ScanningIn-place scan with incremental caching |
Gallery & LightboxCached 4K previews, cursor zoom, click-drag pan, and full-original access |
Fuzzy SearchSearch by filename, prompt, model, sampler |
Object CutoutAuto background removal, transparent PNG |
Keyboard Shortcuts14 shortcuts + Help Center |
Live Source Index Watcher + periodic reconciliation |
DiagnosticsSystem stats in Help Center |
|
Gallery view Masonry grid layout with thumbnails and quick metadata preview on hover. |
Lightbox with metadata Prompts, generation parameters, and model info at a glance. |
|
|
|
Gallery browsing Smooth scrolling through large galleries with lazy-loaded thumbnails. |
Workflow inspection Zoom, pan, and inspect individual ComfyUI node parameters. |
|
|
- Python 3.10+
- Poetry (for dependency management)
# Clone the repository
git clone https://github.com/Lotargo/ComfyUI-Meta-Viewer.git
cd ComfyUI-Meta-Viewer
# Install dependencies
poetry install --no-root# Start the server (opens browser automatically)
poetry run python -m app.main
# Or use the launcher script
# Windows:
start.bat
# Linux/macOS:
chmod +x start.sh
./start.shThe app will be available at http://localhost:7860
- Connect a folder - use Open Folder, then toggle monitoring or recursive subfolder scanning from the source card
- Browse media - use the Media sidebar to show images, videos, or both; click an item to preview it
- View metadata - Summary tab shows prompt + settings
- Explore workflow - Workflow tab shows the ComfyUI node graph
- Search - Ctrl+F to fuzzy search across all metadata
- Cutout - Select an image and generate a transparent PNG
- Configure AI - open the AI page, add an endpoint or import a detected local CLI, choose exact model IDs, and test text or image support
- Create - choose Image, Reference, Video, or High detail; describe the result, select a local model, and press Create. Dependency checks run automatically, while technical controls stay under More settings (model_04-06 are still calibration placeholders and cannot generate)
- Remix - available from the lightbox, but the draft->Create handoff is not wired yet; see Feature Status
- Custom Nodes & Workflows: Standard built-in workflow templates cover checkpoint-contained, Flux separate-components, Pony/SDXL GGUF, reference, and video pipelines. Highly customized third-party node workflows can be imported using the mapping wizard, but complex multi-pipeline graphs may require manual node binding or mapping adjustment.
- Desktop Installers: Standalone desktop installers (
.exe/.dmg/AppImage), electron/tauri packaging, and auto-update are scheduled for Post-v1. Currently, the application runs as a local Python web application. - FFmpeg Dependency: Basic image viewing, metadata extraction, and library management work out-of-the-box without extra tools. Video thumbnail preview and technical stream metadata extraction require
ffmpeg/ffprobebinaries on your systemPATH. - Platform Support: Primary release platform is Windows; cross-platform validation is performed via GitHub Actions CI for Linux and macOS.
| Layer | Technology | Purpose |
|---|---|---|
| Backend | Python 3.10+ | Server logic |
| HTTP | Flask 3.1 | REST API + static files |
| Database | SQLite (WAL mode) | Metadata storage |
| Validation | Pydantic v2 | Request/response models |
| Images | Pillow 11.0 | Metadata extraction, thumbnails, cutout |
| Monitoring | Watchdog 6.0 | Cross-platform filesystem events |
| Secrets | Keyring 25.x | Windows Credential Manager, macOS Keychain, or Linux Secret Service |
| Frontend | Vanilla JS (ES modules) | SPA interface |
| CSS | Custom Properties | Modular styling |
| Search | Fuse.js 7.0 | Fuzzy search (vendored in app/static/js/vendor/) |
| Tracing | OpenTelemetry | Optional traces via OTLP exporter |
| Tests | pytest | Unit + integration suite (see tests/) |
| Dependencies | Poetry | Package management |
| Document | Description |
|---|---|
| Architecture | System overview, data flow, database schema |
| API Reference | Detailed REST endpoints, behavior, examples, and legacy editor notes |
| Interactive API | Scalar portal backed directly by the public OpenAPI 3.1 contract |
| Features | Detailed feature descriptions |
| Configuration | Environment variables, paths, CLI flags |
| Development | Guide for contributors and public API synchronization rules |
| JS Architecture | Frontend module structure |
| CSS Architecture | Styling system and custom properties |
| Prompt intent benchmarks | Targeted raw-intent generation and model-judge evaluation |
| OpenCode smoke testing | Managed CLI execution, profiles, scenarios, and reports |
| AI prompt architecture | Canonical profiles, compilation, execution routing, persistence, and skill export |
| Legacy workflow editor notes | Retained /api/editor/* implementation reference, intentionally outside the public OpenAPI contract |
| Roadmap | AI prompt compiler status, benchmark targets, and planned work |
CMV exposes a local REST API at http://localhost:7860. The machine-readable public contract is site/api/openapi.json and the interactive Scalar portal is available at lotargo.github.io/ComfyUI-Meta-Viewer/api/.
The public contract covers every supported non-legacy /api/* route. The retained /api/editor/* workflow-editor surface is legacy/internal and is documented separately in docs/core/api.md rather than advertised as part of the public contract.
| Area | Method | Endpoint | Description |
|---|---|---|---|
| Sources | POST |
/api/scan |
Connect and index a source directory |
| Sources | PATCH |
/api/folders/{id} |
Enable/disable a source or change recursion |
| Sources | POST |
/api/folders/{id}/reconcile |
Queue a full source reconciliation |
| Media | POST |
/api/upload |
Upload image or video files |
| Media | GET |
/api/images |
List paginated image/video assets |
| Media | GET |
/api/assets/{id} |
Get unified asset details and separated metadata layers |
| Library | GET |
/api/library/assets |
Query the virtual library with filters |
| Library | POST |
/api/library/assets/bulk |
Apply bulk virtual-library operations |
| Preview | GET |
/api/preview/{id} |
Get or generate a bounded display preview |
| AI | GET/POST |
/api/ai/profiles |
Manage sanitized AI provider profiles |
| AI | POST |
/api/ai/generate |
Generate a durable prompt draft |
| AI | POST |
/api/ai/translate |
Translate prompt text, optionally through SSE |
| AI | POST |
/api/ai/adapt |
Adapt a prompt to a target model family |
| AI | POST |
/api/ai/enhance |
Enhance prompt composition and detail |
| AI | POST |
/api/ai/reconstruct/analyze |
Analyze an indexed image into a SceneSpec |
| ComfyUI | GET |
/api/comfyui/status |
Read runtime and queue state |
| ComfyUI | POST |
/api/comfyui/start |
Start a managed local ComfyUI instance |
| Create | GET |
/api/simple/models |
List curated Simple Mode models |
| Create | POST |
/api/simple/generate |
Queue Simple Mode generation |
| Create | GET |
/api/simple/runs/{run_id} |
Refresh run state and imported outputs |
| Social | GET |
/api/social/status |
Inspect social integration capability/auth status |
| System | GET |
/api/diagnostics |
Read local diagnostics and cache statistics |
Full behavior and examples: docs/core/api.md.
| Key | Action |
|---|---|
← → |
Navigate images |
Enter |
Open lightbox |
Escape |
Close lightbox / panel |
Delete |
Delete image |
Ctrl+F |
Search |
G |
Toggle gallery/list |
? |
Help Center |
1 2 3 |
Switch meta tabs |
D |
Toggle meta panel |
S |
Toggle sidebar |
Full shortcuts list: docs/core/features.md#keyboard-shortcuts
| Variable | Default | Description |
|---|---|---|
COMFY_META_PORT |
7860 |
Server port |
COMFY_META_DATA_DIR |
.comfy_meta_uploads |
Database and application data directory |
COMFY_META_CACHE_DIR |
cache |
Thumbnail, preview, and cutout cache directory |
COMFY_META_UPLOAD |
- | Legacy alias for COMFY_META_DATA_DIR |
Full configuration: docs/core/configuration.md
See Development Guide for setup instructions and code style.
- Add the route to the owning public module (
app/main.py,app/ai/routes.py,app/comfyui/routes.py,app/comfyui/simple_routes.py, orapp/integrations/social/routes.py). - Add Pydantic request/response validation where useful.
- Add the operation to
site/api/openapi.jsonwith its method, path parameters, tags, summary, and uniqueoperationId. - Document detailed behavior in
docs/core/api.md. - Add/update a frontend wrapper only when the browser UI consumes the endpoint.
- Run
poetry run python -m pytest tests -q;tests/test_openapi_contract.pyrejects public Flask/OpenAPI drift.
app/comfyui/editor_routes.py is the retained pre-Simple-Mode legacy editor and is intentionally outside the public OpenAPI coverage gate unless it is explicitly promoted back into the supported API.
- Create module in
app/static/js/features/ - Create styles in
app/static/css/features/ - Import in
app.js - Document in
docs/core/features.md
GNU Affero General Public License v3.0 only. See LICENSE.