> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sidebar Panel

> ComfyUI Agent Panel — an autonomous AI agent in ComfyUI's sidebar that drives your canvas on ANY LLM: Claude, ChatGPT, or Gemini on your subscription (no API key), a free local model via Ollama (no account), or any hosted model over an OpenAI-compatible endpoint. Available on the Comfy Registry as comfyui-agent-panel.

<Note>
  **Now on the Comfy Registry.** Install **ComfyUI Agent Panel**
  (`comfyui-agent-panel`) from ComfyUI-Manager, or install from git for the
  latest build (see [Setup](#setup) below).
</Note>

**[comfyui-mcp-panel](https://github.com/artokun/comfyui-mcp-panel)** puts an
autonomous agent in ComfyUI's sidebar. Ask it for an image, a workflow, or a
change — it works against your ComfyUI and replies right there. Pick a provider —
**Claude**, **ChatGPT**, **Gemini**, or **Ollama (local)** — and the matching
agent runs in the background: subscriptions with **no API key**, local models
with **no account at all** (and the Ollama backend reaches any hosted
OpenAI-compatible endpoint too). See [Backends](./backends) for the matrix and
the [LLM Arena](./arena) for how each model class actually performs.

```
you ⇄ panel (pick a provider) ⇄ loopback bridge ⇄ panel orchestrator ⇄ background agent: Claude · ChatGPT · Gemini · any LLM
```

**No API keys, no per-token billing** on the subscription providers — and fully
free/offline on local models. The agent authenticates with your on-disk login
(or, for Ollama, just talks to the local daemon). One orchestrator on one
loopback bridge port (`ws://127.0.0.1:9199`) serves every provider; each panel
tab picks its provider in the handshake. The bridge is loopback-only, and the
panel executes a **fixed allowlist** of graph commands (no arbitrary
JavaScript).

<Note>
  New here: [Backends / providers](./backends) explains the picker, the provider-neutral
  `AgentBackend` port, and the capability matrix (what's identical across Claude and
  ChatGPT, and the few things that differ).
</Note>

## Setup

1. **Install the pack** — search `comfyui-agent-panel` in ComfyUI-Manager, or from git:

   ```bash theme={null}
   cd ComfyUI/custom_nodes
   git clone https://github.com/artokun/comfyui-mcp-panel
   ```

   <Warning>
     **Pick `Latest`, not `Nightly`, in Manager's version dropdown.** Despite the
     name, Manager's **Nightly** is not built nightly: it clones the repo **once**
     at install time and then never tracks the branch again. It freezes you on
     whatever commit happened to be `main` that day, while `Latest` keeps pace with
     every release — so Nightly is routinely *older* than Latest, and silently drifts
     further behind the longer you leave it. It reports no update available, because
     from its point of view there isn't one.

     To check where you actually are, compare the SHA under **Node Pack Info →
     Version** against [the repo's commit
     history](https://github.com/artokun/comfyui-mcp-panel/commits/main). To escape,
     either select `Latest (x.y.z)` in that same dropdown, or — if you want to stay on
     git — `git pull` in `custom_nodes/comfyui-mcp-panel`, which fast-forwards cleanly.
   </Warning>

2. **Sign in to the provider you want** once, so the background agent can use your
   subscription:

   ```bash theme={null}
   claude        # Claude — or: claude setup-token
   codex login   # ChatGPT (Codex)
   ```

3. **Start the orchestrator** on your machine and leave it running — see
   [Starting the panel orchestrator](./installation#3-starting-the-panel-orchestrator):

   ```bash theme={null}
   npx -y comfyui-mcp@latest connect
   ```

4. **Restart ComfyUI**, open the **Agent** tab, **pick a provider** (Claude /
   ChatGPT chips), and click **Connect**. The panel links to the orchestrator's
   loopback bridge. Type a request and the agent responds. **Disconnect** unlinks
   it; the orchestrator keeps running until you stop it.

No `claude mcp add`, no API key. The panel is a pure-frontend extension and cannot
spawn the orchestrator itself, so it is always a process you start — the panel
auto-connects to a bridge that is already running. Prerequisites are Node.js/`npx`
on your PATH and the provider login above. Change the bridge port with
`COMFYUI_MCP_BRIDGE_PORT`.

<Note>
  **Driving a remote ComfyUI** (a cloud GPU pod, another box on your LAN)? The setup
  above still applies, but run the orchestrator **on your own machine**, not the
  remote box: `npx -y comfyui-mcp@latest connect <remote-url>` handles the rest,
  including a secure tunnel back to the pod's HTTPS page. Then click Connect in the
  panel. See [Cloud deployment](./cloud-deployment) for the full walkthrough.
</Note>

<Note>
  **Provider onboarding.** At Connect the panel checks each provider's readiness (its
  CLI on your PATH + a login on disk; the macOS Keychain is handled). An onboarding card
  appears only when **neither** provider is signed in. If your saved pick isn't usable
  the panel **auto-switches to a ready provider** (your saved preference is kept), and a
  not-ready provider's row offers a **"set up"** action that seeds the one-time
  `claude` / `codex login` step. See [Backends → readiness & onboarding](./backends#connect-time-readiness--onboarding).
</Note>

## What it can do

The agent (Claude *or* ChatGPT) loads comfyui-mcp's model skills (IDEOGRAM, WAN,
LTX, Qwen, and more), so it already knows the models you run — Claude natively, and
ChatGPT via the same knowledge exposed as MCP tools
([knowledge parity](./tools/skills-knowledge)). It can generate images, video and
audio, inspect and manage your ComfyUI, and reason about your setup — then reply in
the panel chat.

It can also **load a whole workflow or installer pack in one shot**
(`panel_load_workflow pack:<name>`) and is **cost-aware**: bundled packs are
local-GPU / free, and for an ad-hoc graph the agent checks the runtime
(`list_packs` with `action:"check_runtime"`) and **asks before spending paid API credits**. See
[Skills, Packs & Runtime Cost](./tools/skills-knowledge).

## Driving the live graph

The autonomous agent works your live ComfyUI through a **fixed allowlist** of
`panel_*` commands — no arbitrary JavaScript. Every graph mutation goes through
LiteGraph's change tracking, so each is undoable with **Ctrl+Z**. The same
`panel_*` surface is exposed identically to both backends (in-process for Claude,
over a loopback HTTP MCP for ChatGPT/Codex), so [parity](./backends) is automatic.

### Read

| Tool                           | Effect                                                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `panel_query_graph`            | Query the graph being viewed — filter/traverse/aggregate, token-bounded                                                                           |
| `panel_get_subgraph`           | Read inside a subgraph node's inner graph                                                                                                         |
| `panel_view_selected`          | Read the node(s) the user has **selected** — answers "this node" in one call                                                                      |
| `panel_view_nodes_in_viewport` | Read only what's **on screen** (viewport rect + zoom) — scopes work on a big graph                                                                |
| `panel_get_errors`             | **Why** a node is red — each errored node joined to its cause (missing model + download URL, missing media, validation, runtime `exception_type`) |
| `panel_list_workflows`         | List open workflow tabs and which is active                                                                                                       |
| `panel_list_nodes`             | List installed custom-node packs                                                                                                                  |
| `panel_list_mcp`               | List connected MCP servers                                                                                                                        |
| `panel_get_content_mode`       | Read the adult-content (NSFW) consent state                                                                                                       |

### Edit the graph (undoable)

| Tool                                 | Effect                                                                                                                                                |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `panel_add_node`                     | Add a node by class\_type                                                                                                                             |
| `panel_remove_node`                  | Remove a node                                                                                                                                         |
| `panel_connect` / `panel_disconnect` | Wire / unwire slots by name or index (omit both slots on `panel_connect` to auto-match by type; `auto_match:false` restores legacy index-0 semantics) |
| `panel_set_widget`                   | Change a widget value (steps, cfg, prompts, …)                                                                                                        |
| `panel_edit_node`                    | Atomically move, resize, retitle, recolor, reshape, collapse, or pin one or more nodes                                                                |
| `panel_auto_layout`                  | Auto-arrange the whole graph (or a subset) into a clean flow/grid layout by link topology — `dry_run` to preview                                      |
| `panel_clear`                        | Remove every node — the whole wipe is one Ctrl+Z                                                                                                      |

### Subgraphs

| Tool                    | Effect                                                       |
| ----------------------- | ------------------------------------------------------------ |
| `panel_select_nodes`    | Select nodes on the canvas (multi-selection)                 |
| `panel_create_subgraph` | Group selected nodes into a subgraph ("Convert to Subgraph") |
| `panel_enter_subgraph`  | Drill into a subgraph to read / edit its inner nodes         |
| `panel_exit_subgraph`   | Return to the parent / root graph                            |

### Spatial layout

The agent can see node geometry — `panel_query_graph` detail rows return each node's
`pos`/`size`, plus subgraph input/output `rails`, `groups`, and per-node
`color`/`collapsed` — and arrange the canvas with a matching set of writes,
then **screenshot** the result to judge its own layout. A `workflow-layout`
skill ties these into a dependency-layered, overlap-free auto-layout whose
headline rule is *always leave inputs and outputs exposed* so you can jump
straight in.

| Tool                                                                                  | Effect                                                                                      |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `panel_move_rail`                                                                     | Move a subgraph's input / output rail so boundary wires stay short                          |
| `panel_create_group` / `panel_move_group` / `panel_edit_group` / `panel_remove_group` | Create, move, retitle/recolor, or delete a labeled group box (pass `node_ids` to auto-wrap) |
| `panel_screenshot`                                                                    | Render the canvas to a PNG and hand it back as an image so the agent can verify its layout  |

### Workflow tabs

| Tool                    | Effect                                                                 |
| ----------------------- | ---------------------------------------------------------------------- |
| `panel_new_workflow`    | Open a fresh blank workflow in a NEW tab (never wipes the current one) |
| `panel_open_workflow`   | Switch to a workflow by path / filename                                |
| `panel_rename_workflow` | Rename a workflow                                                      |
| `panel_close_workflow`  | Close a tab (refuses unsaved changes unless forced)                    |
| `panel_save_workflow`   | Save / save-as programmatically — no dialog pops                       |

### Load a workflow in one shot

| Tool                  | Effect                                                                                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `panel_load_workflow` | Replace the live graph with a full workflow in one call — prefer `pack:<name>` to load a bundled installer pack's local-GPU workflow without shuttling the JSON through chat. The replaced graph becomes an undo point (double-Esc / `/revert`). |

### Knowledge & cost awareness

The agent discovers bundled expertise and checks runtime cost before spending
credits (same tools on both backends — see
[Skills, Packs & Runtime Cost](./tools/skills-knowledge)):

| Tool                                                         | Effect                                                                                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `list_packs` (`action:"skill_list"` / `action:"skill_read"`) | Discover and read bundled model-family + workflow skills                                                               |
| `list_packs` (`action:"list"` / `action:"read_workflow"`)    | List one-command installer packs (local-GPU / free) and read a pack's graph                                            |
| `list_packs` (`action:"list_templates"`)                     | List the connected server's official ComfyUI workflow templates                                                        |
| `list_packs` (`action:"check_runtime"`)                      | Classify a graph as **local** (free) or **api/mixed/unknown** (paid) — the agent asks before spending paid API credits |

### Run & view

| Tool           | Effect                                                  |
| -------------- | ------------------------------------------------------- |
| `panel_run`    | Queue the open workflow (same as pressing Queue Prompt) |
| `panel_canvas` | Fit, center on a node, pan, or zoom the view            |

### Custom nodes (built-in ComfyUI Manager)

| Tool                      | Effect                                                                          |
| ------------------------- | ------------------------------------------------------------------------------- |
| `panel_search_nodes`      | Search installable node packs via the user's own Manager                        |
| `panel_install_node`      | Queue a pack install (registry id or git URL)                                   |
| `panel_node_queue_status` | Check the Manager's install / update queue                                      |
| `panel_restart_comfyui`   | Restart ComfyUI to load new nodes — panel auto-reconnects and the agent resumes |

### MCP & session

| Tool                                 | Effect                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| `panel_add_mcp` / `panel_remove_mcp` | Connect / remove an MCP server in the user's agent MCP config (Claude or Codex) |
| `panel_request_secret`               | Securely collect an API token — the agent never sees the value                  |
| `panel_reload`                       | Soft-reload the orchestrator (new code/tools) or the panel UI, then resume      |

### Working with the user

| Tool                                                       | Effect                                                                              |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `panel_ask`                                                | Ask the user to choose between options (renders a question card, blocks for a pick) |
| `panel_set_todo`                                           | Show a live TODO checklist in the panel's footer tray                               |
| `panel_request_adult_consent` / `panel_disable_adult_mode` | Toggle the 18+ NSFW consent gate                                                    |

<Note>
  Every tool accepts an optional `tab_id` — each browser tab holds its own
  connection, and routing defaults to the only tab, or the tab the user last
  typed in.
</Note>

## Rewind & rollback

Past messages aren't frozen. Hover any message and the **✎ edit** button opens a
rollback modal: roll back the **code** (revert the graph to that turn's
snapshot), the **conversation** (fork the session back to that point), or
**both**, then resend an edited message from there. Graph reverts use per-turn
snapshots, so undoing a turn restores exactly the graph it started from.

Two shortcuts cover the common cases:

* **`/revert`** — undo the graph edits from the last turn.
* **Double-Esc** — a quick last-turn rewind: revert the graph and recall the
  message into the composer to edit and resend.

<Note>
  **Code** (graph) rollback works on **both** providers — it lives in the
  orchestrator via per-turn snapshots. **Conversation** rollback (forking the chat
  back to a past turn) is currently **Claude-only**; the ChatGPT/Codex backend
  resumes whole threads only, so the panel gates that scope off for it. See the
  [capability matrix](./backends#capability-matrix).
</Note>

## Pending-message tray

Type while the agent is busy and your message doesn't get lost in the chat — it
waits in a fixed **Pending** tray docked above the downloads tray, out of the
chat flow. Each pending message has **edit**, **send-now**, and **delete**
buttons, and a drag handle (≡, on the left) to **reorder** how the agent flushes
them. **Send-now** interrupts the current turn to steer it immediately. When a
pending message is dequeued it materializes at the **bottom** of the chat, so the
transcript reads in the exact order the agent (Claude or ChatGPT) processed it.

## Destructive-op confirmation

Irreversible actions ask first. `panel_clear` (wipe every node) and
`panel_restart_comfyui` pop a yes / no card and only act on **yes** — so the
agent can't silently nuke your graph or bounce ComfyUI.

## Reconnect durability

A wedged orchestrator no longer strands the panel. If a previous orchestrator
is still holding the bridge port, clicking **Connect** reclaims that zombie
instead of failing — the panel reconnects rather than leaving you stuck.

## Composer attachments

Attach, drag-and-drop, or paste into the composer. Alongside images, the
composer now accepts **video**, **workflow `.json`**, and **text** files, so you
can hand the agent a reference clip, a workflow to adapt, or a notes file
directly.

## Rich media in agent replies

When a run's media is fed back to the agent, the output isn't just an image block —
it carries **metadata** the agent can reason about: each output's path
(subfolder-relative), file size, pixel dimensions, and **asset-set grouping**
("output K of N from this run" with its sibling filenames, or "single output"), plus
render duration and completion time. Video storyboards add the format and the real
frame count / fps when the payload carries them. So the agent names the actual saved
result accurately and can talk about size, dimensions, and how many files a run
produced.

## Copy & wrap code blocks

Rendered fenced code blocks get a hover **Copy** button and a persisted global
**line-wrap** toggle (off by default — long lines scroll horizontally until you
turn it on). Inline code gets its own Copy. Both are styled to match the panel.

## Render-stall warning

The orchestrator runs a passive watchdog over your ComfyUI queue: a render whose
node/progress stops advancing is flagged as **stalled** and the agent is told (so it
stops blindly stacking jobs behind a wedged one). The threshold is the
**Render stall warning (seconds)** setting under **Settings → Comfy MCP Agent →
General** (default 180s, range 15–3600). It's sent on Connect and pushed **live** —
changing it applies without a reconnect. See
[Configuration → `COMFYUI_MCP_STALL_S`](./configuration#panel-orchestrator--the-bridge).

## Background-tab reliability

Streamed replies now render even when the ComfyUI tab is in the **background**.
Previously the reply typewriter ran on `requestAnimationFrame`, which the browser
pauses in a hidden tab — so switching away during a long multi-stage run left the
bubble empty with a stuck streaming cursor, looking like the agent was "stuck
thinking" even though the turn had finished. The reply now finalizes synchronously
when the tab is hidden, and a `visibilitychange` handler flushes any pending reply on
hide and resumes the typewriter on return. Foreground animation is unchanged.

## RunPod cloud control

A toolbar **host pill** reads **🟢 Local · your rig** or \*\*🔵 RunPod · `<pod>` ·
GPU · $/hr** and opens a **RunPod control panel**: a live status card (GPU / VRAM
/ uptime / $·hr / ComfyUI URL / idle auto-stop countdown), a pod dropdown that
lists your pods **by name**, Connect / Start / Stop / **Use Local**, and a
confirm-armed **Deploy**. Set `RUNPOD_API_KEY` once in the API-Keys card and you
can deploy, monitor, switch local⇄pod, and stop a cloud GPU without touching the
RunPod console — the host pill always tells you where the next render runs. See
[Cloud deployment](./cloud-deployment) and the blog
[Run ComfyUI on a rented cloud GPU](./blog/runpod-comfyui).

## CivitAI browser

The **Civitai** toolbar button opens a full CivitAI browser — images, videos,
checkpoints, LoRAs and workflows with search, filters, and a fullscreen viewer.
Pick a result to **share it with the agent**, **download it to your machine**, or
**save an embedded workflow** to the canvas. The story:
[CivitAI inside ComfyUI](./blog/civitai-in-comfyui).

## See also

* [Mobile app (beta)](./mobile) — pair your phone with the panel and chat with the agent on the go
* [Backends / providers](./backends) — Claude vs ChatGPT, the picker, capability parity
* [Skills, Packs & Runtime Cost](./tools/skills-knowledge) — knowledge parity + the cost guardrail
* [Bridge configuration](./configuration)
* [Cloud deployment](./cloud-deployment) — drive the panel against a remote ComfyUI pod (RunPod, etc.)
* [Self-hosted relay](./self-hosted-relay) — run your own tunnel infrastructure for the bridge
* [The Claude Code plugin](./plugin) — model skills, slash commands, agents
* [comfyui-mcp on GitHub](https://github.com/artokun/comfyui-mcp) · [comfyui-mcp-panel on GitHub](https://github.com/artokun/comfyui-mcp-panel)