ComfyUI Workflow Layout & Organization

Turn a tangled graph into a clean left-to-right dataflow a human reads at a glance, using the panel_* canvas tools. The golden rule: never lay out blind. Read the real node sizes and rail positions first, then compute positions from them.

Primitives (panel tools)

• panel_query_graph {fields:'detail', limit:200, max_chars:60000}. READ FIRST, every time. Returns, for the graph you're viewing:
  • each node's pos [x,y], size [w,h] (body only), and full_height (the TRUE rendered footprint = title bar + body; use this for vertical stacking),
  • all groups (id, title, color, bounding [x,y,w,h]),
  • and, only when inside a subgraph, the rails: the input / output boundary node positions. Everything below is computed from these numbers.
• panel_edit_node({node_id, pos?, size?, title?, collapsed?, preset?|color?|bgcolor?}) atomically moves, resizes, retitles, collapses, or color-codes a node. Widget values remain on their dedicated tool; execution mode is available as mode when needed.
• Groups (colored boxes; nodes stay put): panel_create_group (pass node_ids to auto-wrap, or bounds [x,y,w,h]; color hex), panel_move_group, panel_edit_group, panel_remove_group.
• Subgraphs (nest nodes into one collapsible node): panel_create_subgraph(node_ids), panel_enter_subgraph / panel_exit_subgraph, panel_get_subgraph, panel_promote_widget, panel_move_rail(rail, [x,y]) (rail = "input"|"output", must be inside the subgraph), panel_expose_subgraph_output(from_node_id, from_output) / panel_expose_subgraph_input(to_node_id, to_input) (expose an interior slot on the boundary rail; must be inside the subgraph), and panel_unpack_subgraph(node_id) (expand/dissolve a subgraph back into the parent, the inverse of panel_create_subgraph).
• panel_canvas({action:"fit"}) to frame the result; panel_save_workflow to persist.

The layout algorithm (dependency-layered, overlap-free)

1. Read the graph. Build a DAG from each input's connected_from (ignore unconnected widget inputs; only node→node edges matter).
2. Layer every node by longest path from a source: layer(n) = 0 if it has no incoming node edges, else 1 + max(layer(of its sources)). Layers become columns, left → right.
3. X by layer: x = X0 + layer * COL_PITCH, where COL_PITCH ≈ widest node.size[0] in that column + ~80.
4. Y by FULL height (this is what stops overlaps): stack a column top→down with y[i+1] = y[i] + node[i].full_height + ROW_GAP. Use full_height (from panel_query_graph detail rows), NOT size[1]. size[1] is the BODY only (slots + widgets); the title bar renders ~30px ABOVE pos and is NOT in size[1], so stacking by size[1] overlaps every node by a header (the classic "headers eating the node above" bug). full_height already includes that header (and is only the title height for a collapsed node), so y += full_height + ROW_GAP lands an exact ROW_GAP gap between the previous node's bottom and the next node's title. Never use a fixed row pitch. Tall nodes (KSampler, WanVideo Sampler, LoRA-select) are 480 to 600px and WILL overlap a 320 pitch. (If full_height is ever absent, fall back to size[1] + ~30 for the header.)
5. Order within a column to cut wire crossings: place each node near the average Y of its connected nodes (a median/barycenter pass is plenty).

Reads-well constants: COL_PITCH 360 to 480, ROW_GAP 40. Because full_height already accounts for the title bar, you don't add extra top headroom per node. ROW_GAP is the clean gap you'll actually see.

Subgraph interiors — move the rails!

A subgraph has two boundary rails (input left, output right). They do not follow the inner nodes. Move the nodes without moving the rails and you get a huge gap (a common mistake). For each subgraph: panel_enter_subgraph → lay out the inner nodes (algorithm above) → then pin the rails to the node band:

• input rail → panel_move_rail("input", [minNodeX - 180, bandTopY])
• output rail → panel_move_rail("output", [maxNodeX + 60, bandTopY])

Keep rails at the same Y as the first row. Read current rail positions from panel_query_graph (rails) before deciding. panel_exit_subgraph when done.

Wiring interior nodes to the boundary (don't connect to a guessed rail id). To expose an interior node's output/input on the boundary so the PARENT graph can wire it, do NOT panel_connect to a rail node id you guessed. Use panel_expose_subgraph_output(from_node_id, from_output) (interior output → output rail) and panel_expose_subgraph_input(to_node_id, to_input) (interior input → input rail), both while inside the subgraph. panel_query_graph's rails shows which boundary slots already exist and which still need exposing. To expand or dissolve a subgraph back into the parent (inline its inner nodes and rewire external links, removing the wrapper, the inverse of panel_create_subgraph), use panel_unpack_subgraph(node_id). All undoable with Ctrl+Z.

Groups vs subgraphs — choose deliberately

• Group (colored box): lightweight visual band; nodes stay in place and editable. Reach for this first, to label regions of a flat graph or band stage-columns at the root.
• Subgraph: collapses a stage into one node. Useful for large graphs, but it nests and hides nodes and adds boundary ports. Don't subgraph everything. A 2 or 3 node stage rarely earns it, and over-subgraphing hurts readability and complicates packaging and handoff.
• Clean recipe: lay the flat graph out well → wrap only the complex stages in subgraphs → drop colored group bands around the columns at the root.

Stage decomposition that fits most pipelines

Loaders → Inputs → Preprocess (pose/controlnet/conditioning) → Embeds → Sample → Decode/Output, one concern per column/stage, strictly left-to-right.

Always leave inputs & outputs exposed

The nodes a user touches first, the input (Load Image / Load Video) and the output (save / video-combine / preview), must stay expanded and visible so they can jump straight in: drop in their media, hit run, watch the result. Collapse the internal machinery (loaders, encoders, samplers) into chips to cut noise, but never collapse the inputs or outputs. When they live inside subgraphs, keep those subgraph nodes expanded, and consider panel_promote_widget to lift the one key widget (prompt, seed) onto the subgraph node so it's editable without drilling in.

Heads-up: input/output preview nodes (LoadImage, VHS_LoadVideo, video-combine) report their full size[1] but render short until media loads. Size their group band to the .size (so it fits once filled), not to the empty-preview render.

End-to-end workflow

1. panel_query_graph {fields:'detail', limit:200, max_chars:60000} to capture pos/size/groups (and rails inside each subgraph).
2. Compute layers and overlap-free positions from the real sizes.
3. panel_edit_node for each node (or bulk only when the same presentation change is intended).
4. Per subgraph: enter → lay out inner nodes → panel_move_rail both rails → exit.
5. Optional: panel_create_group bands around the root columns (and panel_remove_group any stranded empty groups left behind by earlier edits).
6. panel_save_workflow, then panel_canvas({action:"fit"}).

Gotchas

• Save before relying on it. Node positions, titles, and groups persist only once saved; a browser refresh reloads from the saved workflow (and re-binds nodes after installing packs).
• Converting nodes to a subgraph preserves inner node ids; the subgraph node gets a new id.
• Moving nodes inside a subgraph leaves the rails behind. Always re-pin them (see above).
• Canvas edits never affect an in-flight render; but a ComfyUI restart clears the queue.
• Image/video nodes under-report height. LoadImage, VHS_LoadVideo, preview nodes return a tiny size[1] because the image/video preview height isn't in .size. Leave extra vertical room (≈250 to 300px) below them so the preview doesn't overlap the next node.
• Color-code by stage (e.g. all loaders blue, sampler green) and collapsed rarely-touched loaders to cut visual noise. Cheap wins once the positions are right.
• Don't over-tidy a graph that's mid-build for the user. Confirm if a big reorg is wanted.

Sources

• Official: comfyui-mcp panel layout tools (this repo).
• Empirical: spacing/grouping recipes from observed unreadable canvases.