ComfyUI/AGENTS.md

AGENTS.md

Scope

These instructions apply to the entire repository unless a deeper AGENTS.md overrides them.

Project context

This is a standard Git-based ComfyUI repository on Windows.

Repository root: C:\AI_PROJECTS\ComfyUI

Primary Python environment: C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe

Primary shell: Windows PowerShell

Core working rules

• Preserve existing functionality unless the user explicitly asks for redesign or removal.
• Do not remove features, nodes, scripts, launchers, or config behavior unless explicitly told.
• Fix root causes instead of patching symptoms where practical.
• Reuse and improve existing logic instead of duplicating it.
• Do not invent files, APIs, packages, results, or test outcomes.
• Do not claim something was tested unless you actually ran the test or command.
• Keep changes tightly scoped to the user’s request.
• Stay focused on the current task. Do not perform unrelated cleanup or refactors.
• Prefer additive, reversible changes.

Environment rules

• Always use the repo-local Python interpreter: C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe
• Never use a global Python, Conda environment, Windows Store Python, or some other interpreter unless the user explicitly asks.
• When installing packages, use: C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -m pip ...
• Do not use bare pip commands.
• Assume the repo-local venv is the source of truth unless the user says otherwise.

Command rules

When giving commands or running commands:

• Use Windows PowerShell syntax.
• Always state the working directory first.
• Prefer exact commands over summaries.
• Prefer commands that are safe to copy/paste.

File safety rules

• Do not modify files outside this repository unless the user explicitly asks.
• Do not edit anything inside venv\Lib\site-packages unless the user explicitly asks for a local hotfix there.
• Do not delete models, outputs, checkpoints, LoRAs, embeddings, or user assets unless explicitly asked.
• Be careful with files under:
  • models\
  • custom_nodes\
  • user\
  • launch scripts
  • config files
• Before changing behavior in custom_nodes, inspect that node’s current imports, dependencies, and startup assumptions.

Git rules

If modifying files:

• Work on the current branch unless the user explicitly asks for a new one.
• Do not rewrite history.
• Do not amend existing commits unless the user explicitly asks.
• Do not create commits unless the user asks for a commit.
• Show git status after making changes when relevant.

Validation rules

After code changes, run the smallest relevant validation that actually checks the change.

Preferred validation commands:

• Python syntax check for a file: C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -m py_compile <file>
• Package import check: C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -c "import <module>; print('ok')"
• If the change affects startup or node imports, use the repo-local environment and validate with the relevant launch command or targeted import path when practical.
• If a full startup test is too heavy, say so clearly and run the best targeted validation available.

Reporting rules

In responses:

• State exactly which files were changed.
• State exactly which commands were run.
• State exactly what was verified and what was not verified.
• If something is risky, incomplete, or untested, say that plainly.
• Do not hide uncertainty.

ComfyUI-specific guidance

• Treat startup logs as important evidence.
• When debugging node import failures, identify whether the problem is:
  1. missing package
  2. wrong package version
  3. broken path/import
  4. incompatible ComfyUI/custom-node API change
  5. GPU/CUDA/Torch mismatch
• For package fixes, prefer minimal changes over large dependency churn.
• If a custom node shells out to pip, prefer replacing that with interpreter-safe commands using python -m pip when asked to fix it.
• Be cautious about torch, CUDA, TensorRT, xformers, flash-attn, triton, sageattention, and custom kernel packages because version mismatches can destabilize the whole stack.

Instruction priority

• Follow direct user instructions first.
• Then follow deeper nested AGENTS.md files if present.
• Then follow this root AGENTS.md.