pi-comfyui-paint

ComfyUI image/video generation extension for pi.

Install

pi install npm:pi-comfyui-paint

Or install a pinned version:

pi install npm:pi-comfyui-paint@0.0.8

Development/git install:

pi install git:github.com/MacroSony/pi-comfyui-paint@v0.0.8

Configuration

Env var	Default	Description
COMFYUI_URL	127.0.0.1:8188	ComfyUI server address
COMFYUI_WORKFLOW_DIR	(auto)	Custom workflow directory
COMFYUI_INTERRUPT_ON_ABORT	off	Set to 1, true, yes, or on to call ComfyUI /interrupt when a paint tool call is cancelled. By default, cancellation only stops Pi from polling; ComfyUI may continue running.
COMFYUI_IMAGE_QUALITY	85	JPEG quality (1–100) for images sent to the LLM provider. Set to 0 to send raw PNG with no compression. Original files on disk are never modified.
COMFYUI_IMAGE_MAX_DIMENSION	2048	Resize images so the longest side ≤ this many pixels before sending to the LLM. Set to 0 to skip resizing. Original files on disk are never modified.

Workflow Resolution

Workflows are resolved in this order:

1. COMFYUI_WORKFLOW_DIR env var (if set)
2. .pi/comfyui_workflows/ in your project root
3. workflows/ bundled with this package (fallback)

Place your own .json workflow files in any of these locations. To customize the bundled workflows, call paint_copy_workflow_to_project first and edit the copied files in .pi/comfyui_workflows/.

Tools

Tool	Description
paint_list_workflows	List available workflow JSON files
paint_get_details	Inspect a workflow's variables and notes
paint_validate_workflow	Validate a workflow's JSON structure and pi-comfyui-paint annotations
paint_copy_workflow_to_project	Copy bundled workflows into .pi/comfyui_workflows/ for project customization
paint_server_status	Check ComfyUI connectivity and effective extension configuration
paint_get_models	Query ComfyUI server for available models (checkpoints, LoRAs, etc.)
paint_queue_status	Check the current generation queue (running + pending)
paint_interrupt	Cancel the currently running generation
paint	Generate images/videos from a prompt, with optional workflow variables and input files
paint_search_danbooru_tags	Search Danbooru to confirm tags and find related tags (supports multiple queries)

ComfyUI Custom Node Dependencies

Most bundled workflows only require standard ComfyUI nodes plus the models listed in paint_get_details. LoRA-enabled workflows that use Power Lora Loader (rgthree) require rgthree/rgthree-comfy to be installed in your ComfyUI custom_nodes/ directory.

Power Lora Loader (rgthree) is preferred for LoRA workflows because it can load multiple LoRAs in one node, avoiding the need to manually edit workflows when combining style, character, detail, or concept LoRAs.

Workflow Format

Workflow JSONs use _meta.title annotations:

• [VAR] Name — Customizable variable (exposed as a prompt parameter)
• [NOTE] — Documentation shown in paint_get_details
• [OUTPUT:type] — Tagged output node
• [FILE:type:order] — Input file slot for paint.input_files
• [LORA:slot] — LoRA loader slot for paint.loras overrides. Intended for Power Lora Loader (rgthree) nodes.

For workflows with [FILE:type:order] nodes, pass local image paths to paint as input_files in slot order. Relative paths are resolved from the current project directory, uploaded to ComfyUI as input files, and inserted into the annotated workflow nodes.

LoRA Workflows

LoRA-enabled workflows should use Power Lora Loader (rgthree) and annotate each loader with a simple slot name:

[LORA:base_style] Power Lora Loader (rgthree)
[LORA:hires_detail] Power Lora Loader (rgthree)
[LORA:inpaint_character] Power Lora Loader (rgthree)

paint_get_details detects these slots and returns LoRA slot info together with workflow variables, notes, outputs, and sidecar metadata.

Optional LoRA metadata can be stored next to a workflow:

.pi/comfyui_workflows/T2I_Anime_Anima_lora.json
.pi/comfyui_workflows/T2I_Anime_Anima_lora.loras.json

Example sidecar entry:

{
  "file": "anima/[Style]saio_ga_ushi_v1.safetensors",
  "displayName": "Saio ga Ushi Style",
  "activationPrompt": "@saio ga ushi",
  "defaultStrength": 0.7,
  "description": "Artist/style LoRA for Anima. Add the activation tag to the prompt when you want this style."
}

Use LoRA overrides in paint like this:

{
  "workflow": "T2I_Anime_Anima_lora.json",
  "prompt": "masterpiece, best quality, score_7, safe, 1girl, @saio ga ushi, smile",
  "loras": {
    "base_style": {
      "file": "anima/[Style]saio_ga_ushi_v1.safetensors",
      "strength": 0.7
    }
  }
}

To load multiple LoRAs into one Power Lora Loader slot, use an array:

{
  "loras": {
    "base_style": [
      { "file": "anima/[Style]saio_ga_ushi_v1.safetensors", "strength": 0.7 },
      { "file": "anima/[Detail]some_detail_lora.safetensors", "strength": 0.35 }
    ]
  }
}

LoRA overrides replace the contents of the named slot. Activation tags are not added automatically; put them in prompt yourself based on paint_get_details metadata.