Comfy Agent

Comfy Agent is a CLI for GPU-less individual creators to delegate image, video, and music generation to AI agents across any ComfyUI server—Google Colab, RunPod, or a home GPU.

Japanese documentation: README.ja.md

QuickStart (3 lines)

npm install -g comfy-agent
comfy-agent connect http://127.0.0.1:8188            # or a Colab tunnel URL: https://<id>.trycloudflare.com
comfy-agent run default --source remote --prompt "a cat riding a bicycle"

connect verifies the server once and remembers the URL (re-run it when a Colab tunnel changes — presets and outputs stay local). run submits the workflow, waits, and saves files under ./.comfy-agent/outputs/<preset>/<timestamp>/. default is any workflow saved in the ComfyUI UI; to run your own JSON, comfy-agent import <file> --name <preset>.

No GPU? Jump to Run on Google Colab. Driving this from an AI agent? See For AI agents.

Why comfy-agent

• Verified environment catalog — 39 kits expose GPU, download size, setup time, license, and E2E evidence as machine-readable data.
• Artifacts and instructions stay local — presets, outputs, recipes, and jobs survive server resets; connect absorbs volatile URLs.
• Facts and policy stay separate — the CLI returns a structured error contract, while the playbook defines agent-independent recovery policy.
• Production recipes and verification — reusable recipes combine generation with verify and evidence-based artifact review.

For AI agents (Claude Code, Codex, Cursor, Gemini CLI, OpenClaw)

Install the bundled skill for your agent and read the live policy:

comfy-agent skill install --agent claude
comfy-agent skill install --agent codex
comfy-agent playbook

Other supported targets are cursor, gemini, and openclaw; use comfy-agent skill list to see bundled skills. Repository agents should also follow AGENTS.md. Prefer --json, branch on structured error codes, and use only exit codes 0, 2, and 3; the CLI reference is canonical.

For a reusable character, start every generation with brief <name> --preset <preset> --json. Use run <preset> --character <name> to inject its canonical prompt/reference/LoRA data. Keep only human-approved outputs in its gallery; record rejects and kit notes for the next session.

Run on Google Colab

No local GPU? The bundled kits run ComfyUI on a Colab GPU and expose it to the local CLI through a cloudflared tunnel. Start with this five-step flow:

comfy-agent colab kit z_image      # prints installed paths: 01_setup.py / 02_start_comfyui.py / workflows
# paste setup + launcher into Colab, copy the tunnel URL
comfy-agent connect https://<id>.trycloudflare.com
comfy-agent import <workflow path printed above> --name z_image_turbo
comfy-agent run z_image_turbo --prompt "a cat riding a bicycle"

Statuses are evidence levels, not model quality: Verified passed the complete Colab-to-local flow, Partial passed only some GPUs or workflow variants, and Starter is statically validated but awaits recorded E2E verification. Review each kit README for gated, non-commercial, territory, acceptable-use, and paid-GPU cautions.

Use the catalog before choosing a runtime:

comfy-agent colab catalog --json
comfy-agent colab suggest "fast image generation on a T4" --json
comfy-agent colab kit z_image --json

Presets and outputs survive Colab resets. Rerun the two printed scripts, then connect the new tunnel URL; do not re-import the preset. Full setup and license notes are in the Colab kit guide.

Install & requirements

• Node.js 22 or newer.
• A reachable ComfyUI server for connection and generation commands.

npm install -g comfy-agent
comfy-agent --help

Contributors can use npm install, npm run build, and npm run dev -- <command>. On Windows, use PowerShell and quote file paths containing spaces.

The npm package includes the playbooks, skills, recipes, catalog, setup scripts, and workflow JSON used by the commands above. No repository checkout is required to read or install those bundled resources.

Commands at a glance

See the complete CLI reference for every option and payload.

Outputs & work directory

connect or init creates .comfy-agent/ with workflows/, presets/, outputs/, jobs/, and cache/; the remembered URL is in config.yaml. Use --global for ~/.config/.comfy-agent. Generated files default to .comfy-agent/outputs/<preset>/<timestamp>/, alongside run.json; verify writes review aids below <run-dir>/verify/.

Exit codes & JSON

The CLI returns only 0 (success), 2 (invalid invocation/input/local environment), or 3 (server/executed target/artifact state differs from expectations). With --json, success is { "ok": true, ... } and failure is { "ok": false, "error": { "code": "...", "message": "...", "details": ... } }. run --dry-run --json prints raw workflow JSON when no character option is present; with --character, it returns an envelope containing the patched workflow and character injection metadata. PROMPT_REJECTED (exit 3) means ComfyUI rejected the submitted workflow; inspect details.error and details.node_errors, correct the reported node inputs, and rerun. See Exit codes and errors.

Documentation

• Agent Playbook — blueprint, recovery, and verification policy.
• CLI reference — commands, presets, JSON, and errors.
• Roadmap — released foundations, planned milestones, and non-goals.
• MiniMax H3 prompting — H3 video/audio prompt format.
• Music-video recipe — multi-stage production workflow.
• Colab kit guide — all kits and their setup details.
• CHANGELOG — release history.

Contributing / License

Contributors must follow the E2E verification discipline in CLAUDE.md. Comfy Agent is available under the MIT License.

Command reference

For complete command documentation, see docs/cli-reference.md.

Optional H3 profiles (Starter)

• H3 extensions: SNS LoRA, Guide, motion/audio continuation.
• VDN H3: explicit-only efficiency experiment.

Ordinary H3/FastH3 stay unchanged; extensions are opt-in. The new kits are not Colab E2E verified.

H3 selection and compatibility