# Comfy Addons Comfyui Sdk Comfyui Sdk

> ComfyUI SDK

- Skill: `tomevault-io/comfy-addons-comfyui-sdk-comfyui-sdk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/comfy-addons-comfyui-sdk-comfyui-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/comfy-addons-comfyui-sdk-comfyui-sdk/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/comfy-addons-comfyui-sdk-comfyui-sdk

---


# ComfyUI SDK

## Quick Start

```typescript
import { ComfyApi } from "@saintno/comfyui-sdk";

const api = new ComfyApi("http://localhost:8188");
await api.init().waitForReady();
const stats = await api.getSystemStats();
api.destroy();
```

### Workflow Execution

```typescript
import { ComfyApi } from "@saintno/comfyui-sdk";
import { PromptBuilder } from "@saintno/comfyui-sdk";
import { CallWrapper } from "@saintno/comfyui-sdk";
import { seed } from "@saintno/comfyui-sdk";

const api = new ComfyApi("http://localhost:8188");
await api.init().waitForReady();

const builder = new PromptBuilder(workflowJson, ["positive", "negative", "checkpoint", "seed"], ["images"])
  .setInputNode("positive", "6.inputs.text")
  .setInputNode("negative", "7.inputs.text")
  .setInputNode("checkpoint", "4.inputs.ckpt_name")
  .setInputNode("seed", "3.inputs.seed")
  .setOutputNode("images", "9")
  .input("positive", "a beautiful landscape")
  .input("negative", "blurry, watermark")
  .input("checkpoint", "model.safetensors")
  .input("seed", seed());

new CallWrapper(api, builder)
  .onFinished((data) => {
    console.log(api.getPathImage(data.images.images[0]));
  })
  .onFailed((err) => console.error("Failed:", err.message))
  .run();
```

### Multi-Client Pool

```typescript
import { ComfyPool, EQueueMode } from "@saintno/comfyui-sdk";

const pool = new ComfyPool(
  [new ComfyApi("http://gpu1:8188", "client-1"), new ComfyApi("http://gpu2:8188", "client-2")],
  EQueueMode.PICK_ZERO
);

pool.on("ready", (ev) => console.log(`Client ${ev.detail.clientIdx} ready`));

const result = await pool.run(async (api) => api.getSystemStats());
pool.destroy();
```

## Architecture

```
ComfyApi          → Main client, extends EventTarget
CallWrapper       → Runs a PromptBuilder workflow, emits callbacks
PromptBuilder     → Immutable fluent API to mutate workflow JSON
ComfyPool         → Distributes jobs across multiple ComfyApi clients
WebSocketClient   → Auto-picks native ws (browser) vs ws (Node)
```

## Key Rules

1. Always call `api.init().waitForReady()` before making API calls
2. Always call `api.destroy()` when done (closes WebSocket, cleans up listeners)
3. Never call `fetch` directly — use `api.fetchApi(route, options)`
4. Check `api.ext.manager.isSupported` / `api.ext.monitor.isSupported` before calling feature methods
5. PromptBuilder methods return clones — original is not mutated
6. CallWrapper `onFailed` is mandatory — unhandled errors crash silently

## Conventions

- **No comments** in code — self-documenting only
- **Imports** use path alias `import { X } from "src/module"`, not relative paths
- **Type imports** use inline `import("path").Type` to avoid circular deps
- **Error handling** — `this.log(fnName, message, data)` dispatches `"log"` event, then re-throws
- **No emojis** unless explicitly requested
- **Naming** — PascalCase classes, camelCase methods, UPPER_SNAKE_CASE constants

## API Reference

See [references/api-reference.md](references/api-reference.md) for complete method signatures, return types, and deprecation status.

## Usage Patterns

See [references/patterns.md](references/patterns.md) for common workflows including authentication, event handling, error handling, and batch processing.

## Testing

```bash
bun test                         # Unit tests only (integration auto-skipped)
COMFYUI_HOST=http://host:8188 bun test  # Full suite with live server
```

Integration tests use `describe.skipIf(!process.env.COMFYUI_HOST)` — they skip silently without a server. Set `COMFYUI_HOST` to enable them. Workflow execution tests need `it("name", fn, 120_000)` timeout.

---
> Source: [comfy-addons/comfyui-sdk](https://github.com/comfy-addons/comfyui-sdk) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-28 -->