ComfyUI Workflow Layout & Organization

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