comfy-pilot: Instructions file for Claude Code

ComfyUI Claude Code Plugin - Guidelines

Working with ComfyUI Workflows

When creating or modifying ComfyUI workflows, follow these best practices:

Node Titles

Always assign descriptive custom titles to nodes when creating them. This makes workflows much easier to understand when reading them back later.

Instead of generic type names like:

• CLIPTextEncode → Use "Positive Prompt" or "Style Description"
• KSampler → Use "Initial Generation" or "Refine Pass"
• LoadImage → Use "Reference Photo" or "Input Image"
• VAEDecode → Use "Final Decode" or "Preview Decode"
• ImageScale → Use "Upscale 2x" or "Resize for ControlNet"

Example:

comfyui_create_node(node_type="CLIPTextEncode", title="Positive Prompt", pos_x=200, pos_y=100)
comfyui_create_node(node_type="CLIPTextEncode", title="Negative Prompt", pos_x=200, pos_y=300)

Node Layout

Position nodes logically from left to right following the data flow:

• Loaders on the left (pos_x ~100-300)
• Processing in the middle (pos_x ~400-700)
• Output/preview on the right (pos_x ~800+)
• Keep related nodes vertically aligned
• Minimum padding: Always leave at least 20px of padding between nodes (2 grid units, default grid = 10px)

Node sizing: When placing a node directly below another node, match the width of the node above it for visual consistency. Use edit_graph with resize action after creation if needed.

Special case: Load 3D & Animation nodes These nodes expand after creation to show a 3D preview. The preview adds ~180px in height. When placing nodes below a Load 3D & Animation node, add at least 200px of extra vertical spacing to avoid overlap.

Placing New Node Groups in View

When creating nodes that are not connected to existing workflow (new starting points, separate node groups, or standalone utilities), use place_in_view: true:

edit_graph(operations=[
  {action: "create", node_type: "CheckpointLoaderSimple", title: "Load Model", place_in_view: true, ref: "loader"},
  {action: "create", node_type: "KSampler", title: "Sampler", place_in_view: true, ref: "sampler"},
  {action: "connect", from_node: "loader", from_slot: 0, to_node: "sampler", to_slot: 0}
])