🚀 ComfyUI Prompt Ops

⭐ If you find this project useful, consider starring the repository.

Composable prompt engineering toolkit for ComfyUI powered by Espanso.

This project turns Espanso into a modular prompt composition engine for AI image generation.

Instead of writing large prompts manually, prompts are built from reusable components.

---

✨ Features

• modular prompt components
• Espanso snippet system
• interactive prompt builder
• local prompt library admin
• automatic snippet documentation
• duplicate trigger detection
• development pipeline for validation & generation
• reproducible PowerShell installer
• installer logging system

---

⚡ Quick Start

Clone the repository:

git clone https://github.com/Delcado19/comfyui-prompt-ops.git
cd comfyui-prompt-ops

Run the installer:

.\installer\install.ps1

The installer automatically:

• installs Espanso with Winget, falling back to Scoop when Winget is unavailable or fails
• installs CopyQ with Winget, falling back to Scoop when Winget is unavailable or fails
• checks YAML parsing support
• installs project snippets
• generates snippet documentation
• restarts services if required

Installer logs are written to:

logs/install.log

---

🧠 Prompt Workflow

Traditional Prompt

portrait photo of a woman, cinematic lighting, close-up shot, shallow depth of field

Prompt Ops

:char_woman :ctx_portrait :cam_closeup :light_soft :style_cinematic

Espanso expands the triggers automatically into the final prompt.

---

🧩 Prompt Builder

The project includes an interactive prompt builder.

Trigger:

:prompt

The builder allows selecting:

• Model style preset
• Context
• Characters
• Scene
• Camera
• Lighting
• Style
• Quality
• Negative prompts
• NSFW modifiers

Selections are combined into a final prompt.

The builder snippet is automatically generated from the snippet library:

.\scripts\generate_prompt_builder.ps1

Output file:

snippets/zz_prompt_builder.yml

---

🗂 Prompt Library Admin

Start the local admin interface:

npm run admin

Or use the platform start script:

.\start-windows.bat

On Windows, the start script opens the admin in your browser and keeps a logging window open. Close that window to stop the server.

sh ./start-linux.sh

Open:

http://127.0.0.1:5177

The admin edits the central library:

library/prompt_library.yml

Generated outputs:

snippets/comfy_*.yml
snippets/zz_prompt_builder.yml
docs/snippets.md

Use the admin for adding, editing, deleting, and generating prompt categories and snippets.

---

📦 Installation

Clone repository:

git clone https://github.com/Delcado19/comfyui-prompt-ops.git
cd comfyui-prompt-ops

Run installer:

.\installer\install.ps1

Installer pipeline:

1. PowerShell version check
2. package manager check
3. Espanso installation via Winget with Scoop fallback
4. CopyQ installation via Winget with Scoop fallback
5. YAML support verification
6. snippet installation
7. snippet documentation generation
8. service restart

---

⚙️ Requirements

System

• Windows 10 / Windows 11
• PowerShell 7+
• Git
• Winget, or Scoop as fallback
• Internet connection

---

📦 YAML Support

Several development scripts rely on:

ConvertFrom-Yaml

If missing, the installer installs:

powershell-yaml

Manual installation:

Install-Module powershell-yaml -Scope CurrentUser

Verification:

Get-Command ConvertFrom-Yaml

Expected output:

CommandType     Name
-----------     ----
Function        ConvertFrom-Yaml

---

🧩 Snippet Architecture

Prompt components are grouped by category.

Prefix	Category
:model_	Model style
:ctx_	Context
:char_	Characters
:scene_	Scene
:cam_	Camera
:light_	Lighting
:style_	Style
:quality_	Quality
:neg_	Negative prompts
:nsfw_	NSFW modifiers

Model style snippets describe prompt language that matches known local ComfyUI model families such as Z-Image Turbo, Flux2 Klein, SDXL Cinenauts, and wildcardXL fusion. They do not load models by themselves; they provide reusable text anchors for prompts.

Naming convention:

:<category>_<model-or-look>_<descriptor>

Examples:

:model_zit_jibmix
:style_zit_gothic_editorial
:scene_moonlit_garden
:qual_zit_material

Example snippet:

matches:
  - trigger: ":ctx_portrait"
    word: true
    replace: "portrait, centered composition, subject facing camera"

---

⚠️ Snippet Deployment

Snippets inside this repository are not automatically active in Espanso.

They must be copied to the Espanso match directory.

Run:

.\scripts\install_snippets.ps1

This copies snippets from:

snippets/

to:

%APPDATA%\espanso\match

Example path:

C:\Users\<USER>\AppData\Roaming\espanso\match

---

🧑‍💻 Developer Workflow

Modify snippets inside:

snippets/

Run development pipeline:

.\scripts\dev.ps1

Pipeline steps:

1. snippet generation from library/prompt_library.yml
2. YAML validation
3. PowerShell syntax validation
4. snippet validation
5. duplicate trigger detection
6. prompt builder generation

---

🛠 Developer Utilities

Script	Purpose
doctor.ps1	environment diagnostics
import_snippets_to_library.ps1	migrate generated snippets to the central library
generate_snippets_from_library.ps1	generate Espanso snippets from the central library
test_powershell_parse.ps1	PowerShell syntax validation
validate_yaml.ps1	YAML syntax validation
validate_snippets.ps1	snippet validation
check_duplicate_triggers.ps1	detect trigger conflicts
generate_snippet_docs.ps1	generate snippet documentation
generate_prompt_builder.ps1	build prompt builder
install_snippets.ps1	deploy snippets
restart_services.ps1	restart Espanso

---

📂 Project Structure

comfyui-prompt-ops
│
├ docs
│   admin.md
│   architecture.md
│   banner.png
│   developer_workflow.md
│   prompt_builder.md
│   snippets.md
│   snippet_system.md
│
├ installer
│   install.ps1
│
├ library
│   prompt_library.yml
│
├ logs
│   .gitkeep
│
├ scripts
│   check_duplicate_triggers.ps1
│   dev.ps1
│   doctor.ps1
│   export_existing_snippets.ps1
│   generate_prompt_builder.ps1
│   generate_snippet_docs.ps1
│   generate_snippets_from_library.ps1
│   import_snippets_to_library.ps1
│   install_snippets.ps1
│   restart_services.ps1
│   test_powershell_parse.ps1
│   validate_snippets.ps1
│   validate_yaml.ps1
│
└ snippets
    comfy_camera.yml
    comfy_characters.yml
    comfy_context.yml
    comfy_lighting.yml
    comfy_model.yml
    comfy_negative.yml
    comfy_nsfw.yml
    comfy_quality.yml
    comfy_scene.yml
    comfy_style.yml
    default.yml
    zz_prompt_builder.yml

---

📚 Documentation

Additional documentation in:

docs/

• architecture.md
• developer_workflow.md
• prompt_builder.md
• snippets.md
• snippet_system.md

---

🤝 Contributing

Contributions are welcome.

Please read:

CONTRIBUTING.md

before submitting changes.

---

📜 License

MIT License