# Contributor handoff — Comfy-Org/ComfyUI

> Canonical page: https://codevetter.com/unpack/comfyui/agent-handoff

# Contributor handoff — Comfy-Org/ComfyUI

Scanned commit b33e2b55cae074eca5aec96283cceac19aa249ba (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/AGENTS.md)
- 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](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/AGENTS.md)
- 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. — [AGENTS.md](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/AGENTS.md) [execution.py#L751](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/execution.py#L751)
- 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. — [main.py#L245-261](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/main.py#L245-L261) [comfy_execution/graph.py#L9-10](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/comfy_execution/graph.py#L9-L10)
- 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. — [comfy/cli_args.py#L61-64](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/comfy/cli_args.py#L61-L64) [folder_paths.py#L14-23](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/folder_paths.py#L14-L23) [main.py#L1-4](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/main.py#L1-L4)
- 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. — [server.py#L1134](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/server.py#L1134) [main.py#L366-372](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/main.py#L366-L372) [server.py#L69-71](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/server.py#L69-L71)
- 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. — [comfy_execution/graph.py#L49-68](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/comfy_execution/graph.py#L49-L68) [execution.py#L439-443](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/execution.py#L439-L443)
- 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. — [comfy_execution/caching.py#L83-120](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/comfy_execution/caching.py#L83-L120) [execution.py#L64-105](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/execution.py#L64-L105)
- 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. — [nodes.py#L2068-2137](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/nodes.py#L2068-L2137) [nodes.py#L2394-2552](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/nodes.py#L2394-L2552) [app/model_manager.py#L28](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/app/model_manager.py#L28) [comfy/model_detection.py](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/comfy/model_detection.py)
- 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. — [tests-unit/README.md](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/tests-unit/README.md) [.github/workflows/test-unit.yml](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/.github/workflows/test-unit.yml) [tests/execution/test_execution.py#L505-562](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/tests/execution/test_execution.py#L505-L562)
- 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. — [folder_paths.py#L273-357](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/folder_paths.py#L273-L357) [server.py#L536-549](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/server.py#L536-L549) [AGENTS.md](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/AGENTS.md)
- 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. — [pyproject.toml#L14-30](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/pyproject.toml#L14-L30) [AGENTS.md](https://github.com/Comfy-Org/ComfyUI/blob/b33e2b55cae074eca5aec96283cceac19aa249ba/AGENTS.md)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)