VibeComfy: Making agents first-class citizens in the ComfyUI ecosystem

Its core job is translation: import a ComfyUI workflow, represent it as editable Python, validate the result, and compile it back to the API JSON that ComfyUI queues. JSON is the import/export format. Python is the authoring surface. Load candidates through load_bundle() when you need the canonical bundle and its identity; compile the returned VibeWorkflow to API JSON only at the execution boundary. See Why Python, Not JSON?.

The generated Python is intentionally ordinary code because Python is the language even small local agents tend to understand best. A ready template is a build() function that creates a VibeWorkflow, calls typed ComfyUI node wrappers or generated subgraph functions, and finalizes the workflow contract. The goal is not clever syntax; it is a surface that lightweight agents can read, edit, validate, and translate back to ComfyUI without needing to reason directly over graph JSON. This is abridged from ready_templates/image/z_image.py:

# Abridged from ready_templates/image/z_image.py.
from vibecomfy.templates import ReadyMetadata, new_workflow
from vibecomfy.nodes.core import SaveImage

READY_METADATA = ReadyMetadata.build(capability="image")

def text_to_image_z_image_base(*, width, height, unet_name, clip_name, vae_name, prompt, steps, cfg):
    # Generated from a ComfyUI subgraph. Internally this calls CLIPLoader,
    # VAELoader, UNETLoader, EmptySD3LatentImage, CLIPTextEncode,
    # ModelSamplingAuraFlow, KSampler, and VAEDecode.
    ...

def build():
    wf = new_workflow(READY_METADATA, source_path=__file__)

    edited = text_to_image_z_image_base(
        width=1024,
        height=1024,
        unet_name="z_image_bf16.safetensors",
        clip_name="qwen_3_4b.safetensors",
        vae_name="ae.safetensors",
        prompt="a glass teapot on black basalt",
        steps=25,
        cfg=4,
    )

    save = SaveImage(_id="9", images=edited, filename_prefix="z-image")
    return wf.finalize(
        {},
        output_node=save,
        output_type="SaveImage",
        name="image",
        artifact_kind="image",
        mime_type="image/png",
        expected_cardinality="one",
        filename_prefix="z-image",
    )

Generated files in ready_templates/ are annotated # vibecomfy: generated. Treat them as read-only; copy one to a local recipes/ workspace with copy-to-recipe before editing. That workspace is gitignored.

Unlike ComfyScript-style exports that flatten a graph into Python calls, VibeComfy preserves a workflow contract for agents. See VibeComfy And ComfyScript, and What Is a VibeWorkflow? for the object at the center of that contract.

Comfy MCP provides an agent access layer for operating ComfyUI. VibeComfy focuses on the authoring layer: understanding workflows, finding proven patterns, making complex edits, and preserving the result. See VibeComfy And Comfy MCP.

Getting Started

Import an Existing Workflow

With VibeComfy installed, start in your project directory:

vibecomfy import path/to/my_workflow.json
vibecomfy inspect workflows/my_workflow
vibecomfy edit workflows/my_workflow set sampler.steps 30
vibecomfy validate workflows/my_workflow

The folder keeps your editable Python, its .vibe.json companion, and the unchanged original source.json together. Import prints the paths and next commands. Standalone commands are local and untracked by default; add --project <name> to import or edit while recording accepted changes in Astrid. You can also edit workflow.py directly, then run vibecomfy edit <bundle> capture to record that change. Use doctor to investigate dependency findings; validation does not run generation. Follow Import and edit a ComfyUI workflow for batch edits, Astrid-native use, file responsibilities, and troubleshooting.

Look up a node by its ComfyUI class name:

vibecomfy node SaveImage             # interface and available implementation source
vibecomfy node SaveImage --inputs    # just input parameters
vibecomfy node SaveImage --outputs   # just output sockets
vibecomfy node SaveImage --source    # just the local implementation class

Filters can be combined; add --json for structured output. Cached schemas can describe the interface without local implementation source. The command reports that distinction explicitly.

For installation, each path below can be copied directly into an agent. The ComfyUI path also includes a manual install block because it is a normal custom-node install.

Use VibeComfy Inside ComfyUI

Use this when you want VibeComfy's ComfyUI extension nodes. The in-editor agent panel also works from a normal install, but it needs the agent extra so the Arnold runtime package is present in the same Python environment as ComfyUI.

Install ComfyUI fresh (clone https://github.com/comfyanonymous/ComfyUI.git, create a venv, install torch and requirements.txt, start it once), then install VibeComfy into that ComfyUI checkout with the agent extra using the same Python that runs ComfyUI, symlink `vibecomfy/comfy_nodes` into `ComfyUI/custom_nodes/vibecomfy`, restart ComfyUI, and verify that the VibeComfy node categories are available.

Fresh ComfyUI install (skip this block if you already have a working ComfyUI checkout):

git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
python3 -m venv venv
venv/bin/pip install torch torchvision torchaudio
venv/bin/pip install -r requirements.txt
venv/bin/python main.py  # start once to verify; Ctrl-C once it has loaded

Manual install of VibeComfy into that checkout:

cd /path/to/VibeComfy
COMFYUI=/path/to/ComfyUI
COMFY_PYTHON="$COMFYUI/venv/bin/python"  # replace with the Python that runs ComfyUI
"$COMFY_PYTHON" -m pip install -e ".[agent]"
ln -sfn "$PWD/vibecomfy/comfy_nodes" "$COMFYUI/custom_nodes/vibecomfy"

The default install is ".[agent]": it installs the VibeComfy Python package, the extension-only dependencies, and the Arnold runtime that powers the in-editor agent panel into ComfyUI's interpreter.

Restart ComfyUI, confirm that VibeComfy nodes appear in node search, and verify that /vibecomfy/agent/status returns ready: true.

Use VibeComfy Directly

Use this when you want an agent to install VibeComfy, discover templates, copy one into a recipe, import unfamiliar ComfyUI workflows when needed, validate the result, and show the runtime JSON that ComfyUI will receive.

The supported template-corpus install is a VibeComfy checkout installed editable (pip install -e .); ready_templates/ and template_index.json are checkout data. A built wheel is the Python library and ComfyUI plugin, including its plugin assets, but does not include that corpus. The in-editor agent panel is optional and requires pip install -e ".[agent]" (or the equivalent extra on a wheel install).

Clone https://github.com/peteromallet/VibeComfy and install it with `python -m pip install -e .`.
The canonical agent skill lives in `docs/agent-skill/SKILL.md`; there are no root
agent bootstrap copies. Run `python scripts/sync_agent_skill.py --apply` to check
it, or `python scripts/sync_agent_skill.py --install-user` to install it globally.
That installer uses SkillSinker: it symlinks the VibeComfy skill into detected Claude, Codex, and Hermes skill directories without overwriting existing entries, and it updates Codex's `AGENTS.md` with an idempotent fenced VibeComfy block.
For community workflows, search the canonical Hivemind catalogue through the
deployed Astrid pack (`python3 -m astrid hivemind search "..." --kinds
workflow`). Pull the selected resource directly through the same importer when
you are ready to inspect or edit it: `python -m vibecomfy.cli import
hivemind:external_resources:<id>`. This creates one local bundle under
`workflows/<source-id>/`; it does not bulk-mirror Hivemind. Use `sources sync
--official ... --custom-nodes ...` only for local ComfyUI examples and
installed node schemas.
List ready templates with `python -m vibecomfy.cli workflows list --ready`.
Inspect `image/z_image` with `python -m vibecomfy.cli inspect image/z_image`.
Copy it to `recipes/my_z_image.py` with `python -m vibecomfy.cli copy-to-recipe image/z_image --out recipes/my_z_image.py`.
If I give you an unfamiliar ComfyUI JSON workflow instead of a ready template, import it with `python -m vibecomfy.cli import <workflow.json>`; the same command also accepts a public `https://...` URL, `hivemind:external_resources:<id>`, or `hivemind://resource/<id>`. All sources create `workflows/<source-id>/` with editable `workflow.py`, its `workflow.vibe.json` bundle companion, and the exact local source representation. URL imports retain the URL and a content snapshot pin; Hivemind imports retain the evidence ID, any provider revision, and a content digest (used as the snapshot pin when no revision is exposed) in bundle provenance. Use `--out <directory>` to choose another destination, `--dry-run` to preview, or `--json` for machine-readable output. Import preserves provenance; it does not install nodes or models, configure a runtime, or run the graph.
Inspect the imported folder with `python -m vibecomfy.cli inspect workflows/<source-stem> --json` and `python -m vibecomfy.cli analyze info workflows/<source-stem>`. Edit `workflow.py` at the existing node call/value you want to change, using `node <ClassType> --inputs` to confirm unfamiliar sockets or widgets. For recipes using public handles, `VibeWorkflow` supports `set_prompt`, `set_seed`, `set_steps`, and `set_input`; check `inspect --field <name>` before calling a setter.
Validate and diagnose the imported folder with `python -m vibecomfy.cli validate workflows/<source-stem> --json` and `python -m vibecomfy.cli doctor workflows/<source-stem> --json`. The imported bundle is the single local authoring surface.
Edit the copied, imported, or converted Python itself: change prompts, seeds, steps, model choices, wiring, and output prefixes in the Python authoring surface, not by editing compiled API JSON.
Validate the artifact you actually edited: the imported folder for a direct edit, or `python -m vibecomfy.cli validate recipes/my_z_image.py` for the copied recipe. A separate variation must be validated at its own path, not at the source folder it loads.
Export that same edited artifact with `python -m vibecomfy.cli port export <edited-folder-or-python-path> --to json --json`.
If node packs are missing, use `python -m vibecomfy.cli nodes ensure <workflow>`. If model assets are missing, prefer normal `run` because it reconciles declared assets before queueing; use `fetch` only when explicitly staging authored model assets.
Summarize what changed and show me the exact API JSON fields ComfyUI will receive before any GPU run.

Architecture In One Pass

Everything flows through VibeWorkflow.

flowchart LR
    A[ComfyUI JSON<br/>import/export format] -->|import| B[Python workflow bundle]
    B --> C[VibeWorkflow<br/>editable IR]
    Agent[Agent edits here] --> B
    C --> D[validate / patch / compose]
    D -->|compile api| E[API JSON dict]
    E --> F[ComfyUI queue_prompt]

Loading

compile("api") returns the dict that ComfyUI's queue_prompt accepts. It is derived execution data, useful for inspection and runtime, but it is not the format VibeComfy asks agents to edit or treat as a reusable source. load_bundle() reopens the canonical Python candidate; a raw JSON export remains an import input.

The main artifact types are:

Term	Meaning
Workflow	Any graph, whether it came from ComfyUI JSON, a ready template, or a scratchpad.
Ready template	A curated Python starting point in ready_templates/, addressed by ids like image/z_image.
Recipe	Local user code in gitignored recipes/ that loads templates, applies patches, adds blocks, and runs or exports the result.
API JSON	The runtime dict produced by wf.compile("api"); ComfyUI queues this, but agents should not hand-edit it.

Agents should edit the Python workflow surface. Use patches when a change decorates an existing graph, such as resolution, save prefix, model policy, or low-VRAM behavior. Use blocks when a change adds graph structure and creates new handles to wire.

Templates And Porting

Ready templates live in ready_templates/. Give this to an agent when you want it to choose a starting point:

If I have an existing ComfyUI checkout or workflow folder, first run `python -m vibecomfy.cli sources sync --external <workflow_dir> --custom-nodes <ComfyUI/custom_nodes> --json` so discovery and node specs reflect my local workflows and installed custom nodes.
List ready templates with `python -m vibecomfy.cli workflows list --ready`.
Search for a relevant workflow with `python -m vibecomfy.cli search <query> --task <task>`.
Inspect likely candidates with `python -m vibecomfy.cli inspect <template_id>` and `python -m vibecomfy.cli analyze info <template_id>`.
Pick the smallest ready template that already has the needed media type, model family, and output contract.

For maintainers promoting an imported workflow into a curated ready template, use the expert porting commands only after the normal import path:

Run `python -m vibecomfy.cli validate workflows/<source-id> --json` and `python -m vibecomfy.cli doctor workflows/<source-id> --json` before editing or GPU time.
Run `python -m vibecomfy.cli nodes install-plan <workflow.json>` against the same custom-node context, then use `nodes ensure`, `nodes lock`, or `nodes restore` when the workflow needs packs that are missing or unpinned.
Run `python -m vibecomfy.cli nodes reconcile --workflow workflows/<source-id> --json` when the imported workflow needs node-pack reconciliation.
Validate the imported bundle with `python -m vibecomfy.cli validate workflows/<source-id>`.
If the workflow should become reusable, promote the validated bundle with `python -m vibecomfy.cli templates create workflows/<source-id> --id <kind>/<name> --out ready_templates/<kind>/<name>.py --json`.

Promote durable workflows to Python ready templates. Keep raw JSON as source evidence; do not make compiled API JSON the reusable source of truth.

Deeper Docs

The authoring, sidecar, browser transaction, and no-GPU boundaries are defined in VibeWorkflow and the agent reference.

• Authoring
• Porting workbench
• Adding templates and models
• Testing user code
• What Is a VibeWorkflow?
• Why Python, not JSON?
• ComfyScript comparison
• Comfy MCP comparison

Repository Layout

Path	Purpose
vibecomfy/	Package, CLI, workflow IR, porting code, runtime helpers, and ComfyUI nodes.
ready_templates/	Curated Python templates intended as starting points.
ready_templates/sources/	Generated/pinned source snapshots shipped with curated ready-template adapters; not the community catalogue.
tests/structural_harness/	Deterministic structural contract harness: adapter, runner, builders, scenarios, and briefs.
tests/live_agentic_harness/	True live-agentic harness placeholder; no fake builders or scripted scenarios.
docs/	Authoring, porting, runtime, testing, architecture, and migration docs.
docs/agent-skill/	The single authored VibeComfy agent skill source.
scripts/	Direct-run operational scripts, RunPod harnesses, sync helpers, and maintenance commands.
tools/	Importable developer tools intended to run with python -m tools.<name>.
tests/	Unit, integration, browser, parity, structural harness, and live agentic harness tests.
.github/	GitHub Actions workflows.
pyproject.toml, uv.lock	Python package metadata and locked dependencies.
custom_nodes.lock	Custom-node pack inventory: the enforced pin is each pack's git URL + commit; pip_packages is an unversioned hint for local catalog install/doctor/template metadata. RunPod continues with the cloned pack's requirements.txt plus compatibility dependencies; this is separate from uv.lock.
template_index.json	Tracked ready-template index consumed by fast discovery and strict-ready validation.
out/, input/, output/, temp/	Generated local runtime data; gitignored.

Thanks

VibeComfy is a relatively thin Python authoring layer for agents. The real work belongs to:

• pip-and-uv-installable-ComfyUI by Dr. Pangloss / hiddenswitch - the fork that makes ComfyUI installable as a normal Python package, which is what lets VibeComfy embed Comfy at all.
• ComfyUI by Comfy Anonymous and the Comfy team / community, plus the custom-node pack authors VibeComfy indexes (KJNodes, VideoHelperSuite, WanVideoWrapper, LTXVideo, rgthree, was-node-suite, and many more).
• The workflow builders whose graphs the ready templates are based on - Kijai, the Comfy team's official examples, and many others across the community whose published workflows we adapted into the ready_templates/ set.
• The open-source model authors whose weights every workflow actually runs - Black Forest Labs (Flux), Tencent (Hunyuan), Alibaba (Wan, Qwen), Lightricks (LTX-Video), Stability AI (SD/SDXL), and the long tail of fine-tuners and LoRA authors releasing openly on Hugging Face and Civitai.

License

MIT - see LICENSE.