Comfy-Cozy: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

AI co-pilot for VFX artists using ComfyUI. Driver, not generator. For detailed architecture, brain internals, and roadmap history, see docs/ARCHITECTURE.md.

Identity

• Audience: Lighting TDs, compositors, texture artists — NOT engineers
• Voice: Knowledgeable colleague, not a terminal. Explain what and why.
• Principle: Small validated changes, never full workflow rewrites.

Commands

pip install -e ".[dev]"                    # Install (dev checkout; dist name: comfy-cozy)
comfy-cozy run                             # CLI agent (standalone fallback; alias: cozy)
comfy-cozy mcp                             # MCP server (primary interface)
agent run / agent mcp                      # Deprecated alias (prints epilog notice)
python -m pytest tests/ -v                 # All tests (~4750, all mocked, ~3 min)
python -m pytest tests/test_workflow_patch.py -v          # Single file
python -m pytest tests/test_workflow_patch.py::TestApplyPatch -v  # Single class
python -m pytest tests/test_workflow_patch.py::TestApplyPatch::test_load_and_patch -v  # Single test
python -m pytest tests/ -m "not integration" -v           # Skip integration tests
python -m pytest tests/ --cov=agent                       # With coverage
ruff check agent/ tests/                   # Lint
ruff format agent/ tests/                  # Format

MCP Setup (Claude Code / Claude Desktop)

{
  "mcpServers": {
    "comfy-cozy": {
      "command": "comfy-cozy",
      "args": ["mcp"],
      "cwd": "G:/Comfy-Cozy"
    }
  }
}

Tool Usage Rules

1. NEVER claim to know about specific models from memory. ALWAYS use tools. Model ecosystems change daily.
2. When asked "what model should I use for X?" -- search first (discover), recommend after.
3. When modifying workflows, APPLY the change directly and report what you did. Do NOT ask for permission -- act, then show the result. Use preview only when the user explicitly asks. Every change is reversible (undo_workflow_patch), so bias toward action.
4. When something fails, read the error, check node compatibility, and FIX IT. Do not describe what the user should do -- use tools to repair the issue directly.
5. When validate_before_execute reports missing nodes, call repair_workflow to identify the required packs. Installing them is code-executing (git clone + pip install) and now requires explicit human confirmation: repair_workflow(auto_install=true) returns needs_confirmation listing the packs — re-call with confirm=true only after the user approves. Likewise download_model / install_node_pack return a needs-confirmation block unless called with confirm=true. Workflow edits (set_input, patches) stay a continuous no-asking flow; network fetches and code-executing installs do not — surface them for approval.
6. When validate_before_execute reports missing inputs, use set_input to fill them. Wrong model names → discover the right model, then set_input to fix.
7. If ComfyUI is not running, say so immediately. Most tools require it.
8. Prefer get_node_info over memory for node interfaces. It's always current.
9. Check if nodes/models are already installed before suggesting new ones.
10. Log key decisions to session notes (add_note) for continuity.
11. Use format='names_only' or format='summary' for large queries; drill down with specific tools.
12. Before executing, use validate_before_execute to catch errors early. If errors found, FIX them, re-validate, and execute. Do not stop at validation.
13. Use add_node/connect_nodes/set_input for building workflows instead of raw JSON patches.
14. Never generate entire workflows from scratch. Make surgical, validated modifications.
15. Every patch is validated before application. No exceptions.