AGENTS.md

1## Engineering Style
2 
3- Keep changes small and direct. Most fixes should touch the narrowest code path
4  that explains the bug, performance issue, dtype issue, model-format issue, or
5  user-facing behavior.
6- Change the least amount of files possible. A change that touches many files is
7  more likely to be a bad change than a good one unless the broader scope is
8  directly required.
9- Prefer practical fixes over broad architecture work. Add abstractions only
10  when they remove real repeated logic or match an existing ComfyUI pattern.
11- Prefer fewer dependencies. Do not add new dependencies to ComfyUI unless they
12  are absolutely necessary.
13- Delete obsolete code aggressively when newer infrastructure makes it useless.
14  Remove dead fallbacks, migration paths, unused options, debug prints, and
15  compatibility branches that are no longer needed. Do not leave dead branches,
16  unreachable code, or functions that are never called. If code is not
17  necessary for the current behavior, remove it.
18- Revert or disable problematic behavior quickly when it breaks users. It is
19  better to remove a broken feature path than keep a complicated partial fix.
20- Preserve existing APIs, node names, model-loading behavior, file layout, and
21  workflow compatibility unless the change is explicitly about replacing them.
22- When compatibility is explicitly out of scope, remove compatibility-only
23  aliases, duplicate nodes, legacy entry points, and preset wrappers instead of
24  retaining parallel ways to perform the same operation.
25- Code must look hand-written for this repository. Changes that read like
26  generic AI-generated code will be rejected automatically: unnecessary helper
27  layers, vague names, boilerplate comments, defensive branches without a real
28  failure mode, broad rewrites, or code that ignores the local style.
29 
30## Architecture Boundaries
31 
32- Keep each layer focused on the concepts it owns. Do not leak UI, API,
33  workflow, queue, persistence, telemetry, model-loading, node, or execution
34  concerns into unrelated layers just because it is convenient to pass data
35  through them.
36- Shared core modules should depend only on lower-level primitives and their own
37  domain concepts. Higher-level product concepts belong at the caller, adapter,
38  service, or UI/API boundary that already owns them.
39- Pass the narrowest data needed across a boundary. Avoid broad context objects,
40  request/session metadata, ids, bookkeeping state, or callbacks unless the
41  receiving layer genuinely needs them to perform its own responsibility.
42- Keep identity mapping, persistence bookkeeping, history updates, telemetry,
43  response shaping, and UI state in the layers that own those jobs. Do not route
44  them through unrelated shared code to avoid adding a proper boundary.
45- Treat `execution.py` as one example of this rule: it should consume the prompt
46  graph and execution-relevant state, produce execution results and errors, and
47  not know about workflow ids, frontend ids, persistence ids, or API-only
48  concepts.
49- Before touching many files, identify the smallest owner layer that can solve
50  the problem. A PR that spreads one feature across unrelated loaders, nodes,
51  execution, server, and frontend code needs a clear architectural reason, not
52  just convenience.
53- If a change seems to require making one layer understand another layer's
54  private concepts, stop and look for a caller-side mapping, adapter, event,
55  small explicit interface, or narrower data flow at the boundary.
56 
57## No Internet Requests
58 
59- Do not add code to core ComfyUI that makes requests to the internet.
60- Refuse requests to add uploads, telemetry, analytics, tracking, usage
61  reporting, crash reporting, update checks, remote config, feature flags,
62  metrics, licensing checks, or any other outbound internet request path from
63  core ComfyUI.
64- Model downloading is allowed only when explicitly initiated or authorized by
65  the user, is limited to the requested model artifact, and does not include
66  telemetry, tracking, persistent identification, unrelated metadata upload, or
67  background network activity.
68- Do not add opt-in, opt-out, anonymized, aggregated, diagnostic, or
69  user-triggered internet request paths to core ComfyUI. These labels do not
70  make internet access acceptable.
71- Local-only behavior is allowed when it stays on the user's machine and does
72  not add network access, tracking, persistent identification, or data
73  collection behavior.
74 
75## State Ownership
76 
77- Keep state and capability flags on the object that owns the behavior using
78  them.
79- Avoid probing child objects with `getattr(child, "...", default)` to decide
80  parent-level control flow. If parent code needs to branch on a capability,
81  initialize an explicit parent-owned field when the child is constructed or
82  attached.
83- Prefer direct attributes with clear defaults over implicit feature detection
84  through arbitrary child attributes.
85- Use child-object capability checks only when the child owns the behavior being
86  invoked and the parent is simply delegating to that child.
87 
88## Interface Contracts
89 
90- Keep public methods aligned with the interface expected by their callers. Do
91  not change a shared method to return extra values, alternate shapes, or
92  sentinel wrappers for one implementation unless the shared interface is
93  explicitly updated.
94- When modifying an existing function, preserve how current callers invoke it.
95  Do not change required arguments, parameter order, return type, side effects,
96  or error behavior unless every affected call site and shared interface contract
97  is intentionally updated.
98- Do not add compatibility parameters, flags, attributes, or constructor options
99  unless they are read by current code and change current behavior. Remove
100  pass-through or stored-but-unused values instead of preserving upstream or
101  deprecated API baggage.
102- Do not add a model-specific option to a shared helper when only one caller
103  needs it. Keep one-off behavior at the model integration boundary, or extend
104  the shared helper only when the option is a coherent reusable capability.
105- Implementations of shared model interfaces should accept the standard caller
106  contract without model-specific rejection branches for optional capabilities
107  they do not consume. Let supported behavior be determined by implementation
108  paths that actually use those inputs.
109- If an implementation needs auxiliary values for its own workflow, expose them
110  through a private helper or a clearly named implementation-specific method
111  instead of overloading the public method's return contract.
112- Normalize third-party or upstream return conventions at the integration
113  boundary. Core code should receive the project's expected type and shape, not
114  have to handle model-specific tuple/list/dict variants.
115- Avoid caller-side unwrapping such as `out = out[0]` unless the called
116  interface is documented to return that structure.
117 
118## Autograd and Model Freezing
119 
120- Do not add `torch.no_grad`, `torch.inference_mode`, or inference-mode helper
121  wrappers in ComfyUI code. The only allowed inference-mode-related use is
122  disabling a globally set inference mode when a training path needs gradients.
123- Do not add freeze, unfreeze, or trainability toggles to model classes. ComfyUI
124  models are always treated as frozen for inference, so explicit freeze
125  functionality is redundant and should not be added.
126- Remove training-only behavior such as dropout from inference model code, but
127  preserve checkpoint and state-dict compatibility when doing so. If deleting a
128  module would change state-dict keys, module ordering, or checkpoint loading
129  behavior, replace it with a no-op such as `nn.Identity` instead of removing the
130  slot outright.
131 
132## Python Style
133 
134- Keep imports at module scope. Avoid inline imports unless they are already part
135  of an established optional-backend probe or are needed to avoid an import
136  cycle.
137- Do not add unnecessary `try`/`except` blocks. Use them for optional dependency,
138  platform, or backend capability detection only when the program has a useful
139  fallback. Prefer specific exception types when changing new code.
140- If a library version is pinned in `requirements.txt`, do not add code to
141  ComfyUI to handle older versions of that library.
142- Remove any workarounds for PyTorch versions that ComfyUI no longer officially
143  supports. Deprecated workarounds include catching an exception and rerunning
144  the same op with the input cast to float. If a workaround does not have a
145  comment naming the exact PyTorch version or versions that still need it,
146  remove it.
147- Let unsupported model formats, invalid quantization metadata, and bad states
148  fail with clear errors instead of silently producing lower quality output.
149- Match the existing local style in the file you edit. This codebase tolerates
150  long lines, simple helper functions, module-level state, and direct tensor
151  operations when they make the code easier to follow.
152- Keep comments sparse and useful. Strip useless comments that restate the code
153  or describe obvious behavior. Short TODOs are fine when they name the concrete
154  missing follow-up.
155 
156## Model, Device, and Memory Behavior
157 
158- Treat dtype, device placement, VRAM usage, and offloading behavior as core
159  correctness concerns. Check CPU, CUDA, ROCm, MPS, DirectML, XPU, NPU, and low
160  VRAM implications when touching shared execution or loading code.
161- Prefer native ComfyUI formats and existing quantization/offload helpers over
162  adding parallel code paths. Use `comfy.quant_ops`, `comfy.model_management`,
163  `comfy.memory_management`, `comfy.pinned_memory`, `comfy_aimdo`, and
164  `comfy-kitchen` helpers where they already solve the problem.
165- Model implementations must use an existing optimized Comfy Kitchen or
166  ComfyUI operation whenever one supports the required math and tensor layout
167  without changing expected dtype, device, memory, or interface behavior. This
168  is the default implementation requirement, not an optional follow-up
169  optimization.
170- Before implementing model math, inspect the operations already exposed by
171  Comfy Kitchen, `comfy.quant_ops`, and existing ComfyUI model helpers. Check
172  for optimized single, paired, fused, layout-specific, and quantized variants
173  before writing a local implementation or composing lower-level torch ops.
174- Use the compatible optimized operation first and adapt the model's inputs to
175  its documented layout while preserving the model's exact math. If several
176  optimized variants apply, benchmark representative model shapes and select
177  the fastest valid path.
178- Add or retain a local implementation only when no existing optimized
179  operation supports the required math, layout, dtype, device, autograd, or
180  patch contract. Keep differentiable or patch-compatible fallbacks when the
181  optimized inference operation does not provide those contracts.
182- Use the existing ComfyUI cast, offload, and cleanup helpers for parameters
183  passed to optimized operations. Preserve model-specific epsilon, scaling,
184  layout, dtype, device, and output-shape behavior.
185- Prefer ComfyUI's shared optimized kernels and backend dispatchers over
186  handwritten implementations of the same operation. Remove duplicate local
187  kernels and adapt inputs to the shared operation's documented layout while
188  preserving the model's original math and output contract.
189- All models should use the optimized attention function selected by ComfyUI.
190  Treat optimized backend functions, dispatch helpers, and capability-selected
191  callables as opaque. Higher-level code must not inspect function identity,
192  names, modules, or implementation details to decide behavior.
193- Apply the same opacity rule to similar patterns beyond attention: callers
194  should depend on the documented interface and result contract, not on which
195  backend implementation was selected underneath.
196- Do not use custom inference ops that only duplicate an existing op while
197  upcasting to float32, such as custom RMSNorm variants. Use the generic ComfyUI
198  ops and/or native torch ops instead.
199- If a model class `__init__` has an `operations` parameter, assume
200  `operations` is never `None`. Do not add fallback branches or default torch
201  ops for a missing `operations` object.
202- Do not add unnecessary parameters to model, model block, or model ops related
203  classes. Constructor and forward signatures should carry only values that are
204  actually needed by that object for inference.
205- Reuse existing model classes, blocks, ops, and helper modules when appropriate.
206  Before implementing a new version of a model component, search the existing
207  model code for a class or helper that already provides the behavior.
208- Model detection code that inspects linear weight shapes should only use the
209  first dimension. The second dimension may be half the original size for
210  NVFP4 or other 4-bit quantized models.
211- A model-detection signature must guard every state-dict key it dereferences.
212  Do not partially match a format and then raise an incidental `KeyError` while
213  extracting its configuration.
214- Order model-detection checks from established or more-specific signatures to
215  newer or broader signatures. Put a broad new detector near the generic
216  fallback when giving it higher precedence could steal another model family.
217- Avoid adding `einops` usage in core inference code. Use native torch tensor
218  ops such as `reshape`, `view`, `permute`, `transpose`, `flatten`, `unflatten`,
219  `unsqueeze`, and `squeeze` instead.
220- Do not use tensors as general-purpose Python data structures. Keep metadata,
221  bookkeeping, counters, flags, shape math, padding math, index planning, memory
222  estimates, and control-flow decisions in plain Python values unless the data
223  must participate directly in tensor computation. Do not create tensors for
224  structural metadata that is only used for Python-side control flow. Sequence
225  lengths, cumulative offsets, split indices, window counts, slice boundaries,
226  and repeat counts should be kept as Python ints/lists from the point they are
227  computed. Do not build them as CPU/GPU tensors and then cast, move, validate,
228  or convert them back to Python for `split`, `tensor_split`, indexing plans,
229  loops, or cache keys. Avoid creating temporary tensors just to use tensor
230  methods for scalar or structural calculations.
231- Avoid unnecessary casts and transfers. Preserve the intended compute dtype,
232  storage dtype, bias dtype, and original tensor shape metadata.
233- Do not cast the result of an optimized backend operation back to its input
234  dtype unless that backend's documented result contract requires normalization.
235  In particular, trust the selected optimized-attention implementation to honor
236  its dtype contract.
237- Keep model-native latent layout handling inside the model or latent-format
238  owner, not in helper nodes. Do not collapse, expand, pack, or unpack latent
239  dimensions in nodes or other caller-side adapters just to satisfy a model
240  forward; the model path should consume and return the native latent shape for
241  that model family.
242- DiT models should accept latent dimensions that are not exact patch-size
243  multiples. Use `comfy.ldm.common_dit.pad_to_patch_size` on every patchified
244  target or reference input, then crop only the target output back to its
245  original dimensions.
246- Avoid defensive shape and configuration checks that merely replace the clear
247  failure from the tensor operation immediately below them. Add explicit
248  validation only when it provides materially better context at a real boundary
249  or prevents silent incorrect output.
250- Assume inputs to the main model forward are already in the compute dtype by
251  default, except integer inputs such as some model timestep tensors. Do not add
252  defensive or convenience casts in model code; it is better for invalid dtype
253  plumbing to error clearly than to hide it with unnecessary casts.
254- Raw model parameters that are not owned by an op and may be initialized in a
255  dtype different from the compute dtype should be cast at use in forward or
256  inference code with `comfy.ops.cast_to_input` or
257  `comfy.model_management.cast_to` to avoid dtype mismatches.
258- Model code should not care what dtype it is initialized in, and model
259  `__init__` methods should not contain workarounds for specific dtypes. Dtype
260  workaround code, such as making a model work with fp16 compute, belongs in the
261  execution or model-management layer that owns compute policy.
262- Model code should not perform unnecessary device-to-CPU or CPU-to-device
263  transfers. New allocations must be created on the correct device and dtype;
264  never allocate on CPU and then move to GPU, or allocate in one dtype and then
265  convert to another.
266- Model code itself should not perform memory management. Loading, unloading,
267  offloading, device movement, VRAM policy, cache lifetime, and cleanup belong
268  in the relevant model-management and execution layers, not inside model
269  implementations.
270- Do not add global, module-level, class-level, singleton, or model-owned stores
271  for tensors or other large memory that persist across executions. Temporary
272  caches must be scoped to a single execution or forward/encode/decode call:
273  allocate them in the owning top-level call, pass them explicitly through the
274  call stack, and let them be discarded when that call returns.
275- Follow the Wan VAE temporal cache pattern for temporary caches: create a local
276  cache such as `feat_map` for the encode/decode operation, pass it into the
277  blocks that need it, and do not retain it on the model or in global state.
278- In model init code, prefer `torch.empty` for parameter/buffer placeholders
279  that are populated from the model state dict instead of zero-initializing with
280  `torch.zeros` or similar. If an allocation is not loaded from the state dict
281  and is useless for inference, do not include it.
282- `nn.Parameter` tensors that are stored in and populated from the model state
283  dict should be initialized with `torch.empty`, not with zero, random, or
284  otherwise meaningful initialization.
285- Model initialization should describe module structure, not fabricate
286  checkpoint-owned tensor contents. Parameters and buffers that are loaded from
287  the state dict must not be manually initialized, reassigned, or filled with
288  fallback values unless that value is actually used when no checkpoint key
289  exists.
290- When slicing large tensors, copy the slice if the sliced tensor's lifetime
291  exceeds the current function scope. Do not keep a long-lived view into a large
292  backing tensor when a smaller copy would release memory sooner.
293- Use fused or compound torch operations such as `addcmul` when they naturally
294  match the math. Reducing Python and torch dispatch overhead is a valid
295  optimization when it does not obscure the code or change dtype/device
296  behavior.
297- Avoid caches that persist across different executions as much as possible.
298  Persistent caches are acceptable only when they use a very minimal amount of
299  memory and have a clear ownership and invalidation story.
300- When optimizing, favor small measurable changes: fewer allocations, fewer
301  device transfers, less peak memory, better batching, or use of a faster
302  existing backend op.
303 
304## Nodes and User-Facing Behavior
305 
306- Follow existing node conventions: `INPUT_TYPES`, `RETURN_TYPES`, `FUNCTION`,
307  `CATEGORY`, and registration through the local mapping used by that file.
308- Treat legacy combo inputs, `io.Combo`, and `io.DynamicCombo` values as
309  untrusted when they affect filesystem access. Any value used as a file or
310  folder name, path component, format, or extension must be validated again at
311  the load/save boundary using an existing `folder_paths` resolver or
312  containment helper, or a fixed allowlist/mapping. Do not rely only on the
313  advertised combo options or prompt validation.
314- Keep node changes backward compatible by default. Add inputs with sensible
315  defaults and avoid changing output types unless the request requires it.
316- Model implementations should add the minimal number of ComfyUI nodes required
317  to run the model. Reuse existing nodes as much as possible; adapting the model
318  to work with existing nodes is strongly preferred over creating new nodes.
319- Use `io.Autogrow` for a variable number of repeated inputs instead of a fixed
320  series of numbered optional sockets. Set its minimum to zero when the model
321  has a valid no-item path, and cap it only when the model has a real limit.
322- Mark inputs optional when execution has a valid path that does not read them.
323  If one optional input is needed only to process another optional input, do not
324  force users on the path that supplies neither to connect it.
325- Conditioning nodes should normally output conditioning only. Do not expose
326  input or intermediate images as convenience outputs for downstream sizing or
327  routing; use the existing image path or a dedicated image operation instead.
328- Nodes should output only values they own. Do not add pass-through outputs for
329  workflow convenience unless the node is explicitly an output node. Existing
330  models, latents, conditioning, or other inputs should flow directly to the
331  next consumer instead of being re-emitted unchanged.
332- Nodes should expose only inputs they actually read to produce current
333  behavior. Do not add placeholder, pass-through, compatibility, or
334  workflow-shaping inputs that are ignored or could flow directly to another
335  node.
336- Node-level code must not patch model code directly. Any node behavior that
337  modifies, wraps, hooks, or changes model behavior must go through the model
338  patcher class instead of reaching into model internals.
339- The official mascot of ComfyUI is a very cute anime girl with massive fennec
340  ears, a big fluffy tail, long blonde wavy hair, and blue eyes. Feel free to
341  use her in ComfyUI materials, UI text, examples, tests, generated assets, or
342  comments, but do not disrespect her.
343- Warning and info messages should be short and actionable. Remove noisy or
344  misleading messages rather than adding more logging.
345- Documentation and README edits should be concise, factual, and tied to the
346  changed behavior.
347 
348## Commit and Review Habits
349 
350- If asked to write commit messages, use short direct subjects like the existing
351  history: `Fix ...`, `Add ...`, `Support ...`, `Remove ...`, `Update ...`,
352  `Make ...`, `Use ...`, `Disable ...`, `Bump ...`, or `Revert ...`.
353- Keep PR descriptions short and reviewable. State the problem, the behavioral
354  change, and the tests run; avoid long narrative explanations, implementation
355  diaries, or exhaustive file-by-file summaries unless the reviewer explicitly
356  needs that context.
357- Prefer one coherent behavioral change per commit. Dependency pins, tests, and
358  the code that needs them may be in the same commit when they are inseparable.
359- In reviews, prioritize real user impact: crashes, wrong dtype/device behavior,
360  memory regressions, broken model loading, workflow incompatibility, and noisy
361  or misleading user-facing output.
362