Comfy-Org/ComfyUI
AGENTS.md is unusually prescriptive and is the first file to read: it demands minimal diffs, no new dependencies, no outbound network calls in core, strict layer boundaries (execution.py must not learn API/persistence concepts), no torch.no_grad wrappers (inference_mode already wraps execution), and reuse of comfy.ops/quant_ops/Comfy Kitchen optimized ops for model code. Read main.py -> server.py -> execution.py -> nodes.py -> folder_paths.py -> comfy/cli_args.py to understand any user-facing change. Tests: pytest tests-unit for fast checks; tests/execution needs a spawned server; tests/inference needs real models. Watch the traps: import-time side effects everywhere, tuple-indexed queue items, three different node ids (real/display/ephemeral), and signature-based caching that silently reuses outputs.
- AGENTS.md mandates: smallest possible diff, no new dependencies, no internet requests from core ComfyUI (no telemetry/upload/update-check code paths), and aggressive deletion of dead compat code.
- AGENTS.md architecture rule: keep layer boundaries — execution.py consumes the prompt graph and must not know workflow/frontend/persistence ids; fix leaks with caller-side mapping or narrow interfaces rather than passing context objects through.
- AGENTS.md model rules: never add torch.no_grad/inference_mode wrappers (execution is already inside torch.inference_mode), never add freeze/trainability toggles, prefer existing optimized ops in comfy.ops/comfy.quant_ops/Comfy Kitchen, and DiT models must tolerate non-patch-multiple latents via pad_to_patch_size.
- Import order is load-bearing: torch must not be imported before main.py's late import block (it warns if 'torch' is in sys.modules), which is why ExecutionBlocker lives in comfy_execution/graph_utils.py rather than graph.py — keep heavy imports out of modules parsed early.
- The args singleton from comfy.cli_args is parsed at import time and read by folder_paths at import time to fix base_path/models_dir — tests and embedding code must control argv or env carefully; comfy.options.enable_args_parsing() is the gate.
- Queue tuple layout is positional and load-bearing: (number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive); index 5 is stripped before exposure — preserve arity when modifying put/get/task_done or the remove_sensitive lambdas.
- Three node-id namespaces coexist: ephemeral ids (created by expand), display ids (UI mapping), and real ids (original prompt); always use dynprompt.get_real_node_id/get_display_node_id rather than raw ids in execution code.
- Caching can silently skip your code path: outputs are keyed by input signature including IS_CHANGED/fingerprint_inputs — when debugging a node that 'doesn't run', check CacheKeySetInputSignature and the node flags NOT_IDEMPOTENT / UNIQUE_ID hidden input first.
- Safe edit boundaries: add a node in nodes.py or a comfy_extras/nodes_*.py file (register in NODE_CLASS_MAPPINGS), add routes in the owning app/* manager, add model support via comfy/model_detection.py signature + comfy/supported_models entry — do not create parallel registries.
- Run `pytest tests-unit` after changes; unit CI is continue-on-error so green CI does not prove correctness — for executor changes also run tests/execution which needs websocket-client and spawns main.py as a subprocess.
- When touching file-serving endpoints, reuse folder_paths.is_within_directory/get_annotated_filepath and is_dangerous_content_type rather than hand-rolling checks — traversal/XSS guards are the most-reviewed security surface.
- Style: ruff lint (E, W, F, T print-usage, S102/S307, N805) with E501/E722/E731/E402 ignored; comments sparse; match local style — long lines and module-level state are normal here.