ComfyPromptExtractor (CPE)

ComfyPromptExtractor (CPE) is an ultra-fast, zero-dependency C application for Linux, Windows, and macOS engineered to extract clean generation prompt text and workflow metadata from ComfyUI-generated PNG images with zero startup overhead.

---

Key Features

• 🎯 Multi-Framework Prompt Extraction: Automatically parses ComfyUI, InvokeAI (sd-metadata, invokeai_metadata, invokeai_graph, Dream), SDXL, Flux, Krea2, and AUTOMATIC1111/WebUI metadata to deliver clean, raw human-readable prompt text and workflow JSON structure.
• ⚡ Instant Execution (< 1ms): Fast, sequential C stream parser reads only PNG chunk headers (tEXt and iTXt) and skips multi-megabyte IDAT pixel data with fseek().
• 🔄 Smart Context Detection:
  • Terminal / CLI Mode (TTY detected): Emits clean prompt text directly to stdout and exits immediately (0 on success, 1 on error). Zero GUI initialization overhead.
  • Desktop / GUI Mode (No TTY / File Manager): Launches a sleek, compact, borderless dark UI centered on screen.
• 📋 Seamless Clipboard & Dismissal:
  • Copy Prompt: Click "Copy Prompt", press Enter, or press Ctrl + C.
  • Copy Workflow: Click "Copy Workflow" or press Ctrl + W to copy the full JSON workflow structure to the clipboard.
  • Dismiss: Press Esc, click "Close", or simply click outside the window (instant close on focus loss).
• 📦 Zero External Runtime Dependencies: Single source file (cpe.c), tiny stripped binary (~960 KB), embedded lightweight JSON graph parser, and minimal Raylib GUI.
• 🌐 Cross-Platform Support: Native pre-built releases for Linux (x86_64), Windows (x86_64), and macOS (ARM64 / Apple Silicon).
• 🗂️ Desktop Integration: Includes FreeDesktop cpe.desktop specification for "Right Click -> Open With" in Linux file managers (Nautilus, Dolphin, Thunar, Nemo, etc.) with quick actions for Negative Prompt and Workflow JSON.

---

Installation & Building

Pre-built Releases

Download ready-to-run binaries from GitHub Releases:

• Linux (x86_64): cpe-linux-amd64.tar.gz (includes cpe, cpe.desktop, icon)
• Windows (x86_64): cpe-windows-amd64.zip (includes cpe.exe)
• macOS (Apple Silicon arm64): cpe-macos-arm64.tar.gz (includes cpe)

Prerequisites for Building from Source

• C99-compliant C compiler (gcc, clang, or MinGW)
• make

Dependencies by Platform:

• Linux: libx11-dev, libxcursor-dev, libxrandr-dev, libxinerama-dev, libxi-dev, libgl1-mesa-dev (Raylib is fetched automatically via vendor/raylib if not present)
• macOS: Raylib via Homebrew (brew install raylib)
• Windows: GCC and Raylib via MSYS2 (pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-raylib)

Compile

# Clone repository
git clone https://github.com/JRufer/ComfyPromptExtractor.git
cd ComfyPromptExtractor

# Compile optimized binary for your OS
make

# On Windows (MSYS2):
# make EXE=.exe

Install System-Wide (Linux)

# Install to /usr/local/bin and install desktop handler
sudo make install

# Or install to user directory (~/.local)
make install PREFIX=~/.local

---

Usage

CLI Mode (Terminal)

When invoked from a terminal or shell pipeline, CPE automatically operates in CLI mode:

# Extract clean positive prompt text (default)
cpe image.png

# Extract negative prompt text
cpe -n image.png

# Extract raw prompt JSON graph
cpe -r image.png | jq .

# Extract raw ComfyUI workflow JSON
cpe -w image.png | jq .

# Force CLI mode in scripts
cpe --cli image.png > prompt.txt

GUI Mode (Desktop / File Manager)

• Desktop: Right-click any ComfyUI PNG image in your file manager and select "Open With -> ComfyPromptExtractor".
• Terminal (Forced GUI):

  cpe --gui image.png

Keyboard Shortcuts in GUI

Shortcut	Action
Enter or KP_Enter	Copy prompt text to clipboard and exit
Ctrl + C	Copy prompt text to clipboard and exit
Ctrl + W	Copy entire workflow JSON structure to clipboard and exit
Esc	Close window without copying
Click Away	Close window immediately on focus loss
Mouse Wheel / ↑ ↓	Scroll wrapped text
Page Up / Page Down	Scroll by page

---

Options Reference

ComfyPromptExtractor (CPE) v1.1.0
Usage: cpe [options] <image.png>

Options:
  -p, --prompt       Extract clean prompt text (default)
  -n, --negative     Extract negative prompt text
  -r, --raw          Extract raw prompt JSON metadata graph
  -w, --workflow     Extract raw workflow JSON metadata
      --cli          Force CLI mode (print text directly to stdout)
      --gui          Force GUI mode (open compact UI window)
  -h, --help         Show this help message
  -v, --version      Show version information

---

Running Tests & Benchmarks

# Run automated test suite
make test

Benchmark Comparison

$ time cpe tests/sample_user_prompt.png > /dev/null
real    0m0.001s
user    0m0.001s
sys     0m0.000s

---

Continuous Integration & Automated Draft Releases

This repository includes a cross-platform GitHub Actions workflow (.github/workflows/release.yml) that triggers on every commit pushed to main:

1. Multi-OS Build Matrix: Compiles binaries across Linux (ubuntu-latest), Windows (windows-latest via MSYS2 / MinGW-w64), and macOS (macos-latest Apple Silicon ARM64).
2. Automated Testing: Runs the complete make test test suite on all platforms.
3. Release Packaging: Generates platform archives (cpe-linux-amd64.tar.gz, cpe-windows-amd64.zip, cpe-macos-arm64.tar.gz) along with standalone executables.
4. Automated Draft Release: Publishes a new Draft Release on GitHub containing pre-built assets for all operating systems.

---

License

MIT License