ComfyUI Claude CLI (Vision + Text) — Node Pack

A small collection of ComfyUI custom nodes built around calling the local claude CLI (Claude Code) for vision+text analysis of video frames, plus the batch-manipulation utilities needed to feed it cleanly.

The headline node runs Claude against one or many images per call, reusing a single session across many invocations to avoid the ~30k-token cold-start penalty. The utility nodes fix common friction points from other packs (VHS SelectImages out-of-bounds crashes, iteration/indexing patterns, batch splitting for pair-wise or grid-wise analysis).

Repo: https://github.com/RandyHaylor/comfyui-claude-cli-vision-text-node

---

Installation

1. Install Claude Code and run claude login once.

2. Clone this repo into your ComfyUI custom-nodes directory:

   cd <ComfyUI>/custom_nodes
   git clone https://github.com/RandyHaylor/comfyui-claude-cli-vision-text-node.git
   

3. Restart ComfyUI.

4. Hard-refresh the ComfyUI browser tab (Ctrl+Shift+R) so the frontend picks up the new node schemas.

No extra pip install required. Uses only numpy, torch, and Pillow — already in ComfyUI's environment.

---

Nodes

1. Claude CLI (Vision+Text) — ClaudeCliVisionText

Calls claude -p once per invocation against an optional image input. Uses the user's existing claude login OAuth session by default; no ANTHROPIC_API_KEY needed.

Inputs:

• system_prompt, user_prompt — headers rendered above each field via JS widget.
• model — dropdown: haiku / sonnet / opus / claude-haiku-4-5 / claude-sonnet-4-6 / claude-opus-4-7.
• agent — dropdown: general-purpose / Explore / Plan / code-reviewer / debugger / data-scientist. general-purpose omits --agent for compatibility with older CLIs.
• reuse_session + session_id — session UUID auto-populated on node creation; "Regenerate Session UUID" button with a cost warning reminds users that new sessions cost ~30k tokens to cold-start.
• send_all_frames — when images is a multi-frame batch, attach all frames to one CLI call (vs. just frame 0).
• timeout_seconds — subprocess timeout (default 120).
• on_error — empty / raise / retry_once (default retry_once).
• is_enable — quick disable toggle.
• Optional images — IMAGE tensor (batch or single); text-only when unwired.
• Optional api_key — enables --bare headless mode with ANTHROPIC_API_KEY env (session reuse disabled in bare mode).

Outputs:

• response — parsed .result from the CLI's JSON envelope.
• session_id — the effective UUID actually used (copy into widget to reuse).
• stderr — CLI stderr for debugging.
• session_usage — cumulative token and cost summary for the session, parsed from ~/.claude/projects/**/<session_id>.jsonl. Knows when to advise starting a new session.

Features:

• Strict UUID validation on session_id (non-UUID strings raise cleanly).
• Normalizes round-trip junk values ("null", "undefined", "", whitespace) on optional widgets so a stale widget state doesn't accidentally trip --bare mode.
• Auth-failure detection: non-zero exits with "not logged in" in stderr raise a ComfyUI-visible "Run claude login" error.
• Per-session debug log at <ComfyUI>/output/claude-sessions/<session_id>.debug.log on CLI failures.
• Downsamples images to 1568 px long edge before attaching (safe across Haiku/Sonnet/Opus vision limits).
• Image attachments deleted from disk after each call (PNGs are transient; the Anthropic cache is server-side).

---

2. Image Batch Current Index — ImageBatchCurrentIndex

Drives ComfyUI's per-item iteration while emitting the matching frame index as a parallel integer list. Put this (or any OUTPUT_IS_LIST=True node) between a batch source and a per-frame consumer when you need an integer index alongside the image.

Inputs: images (IMAGE batch, or list of batches), index_offset (INT, default 0 — add +1 for pair-consecutive workflows).

Outputs:

• image — list of single-frame tensors.
• index — list of INTs, one per image.

Downstream nodes that take a single IMAGE and a single INT will be called N times, once per (frame, index) pair.

---

3. Select Images (Bounds Safe) — SelectImagesBoundsSafe

Drop-in replacement for VHS SelectImages with a real err_if_bad_index toggle. Fixes the VHS bug where err_if_missing=False at parse time still passes out-of-bounds indices through to the tensor step, crashing with IndexError.

Inputs: image (IMAGE batch), indexes (STRING, VHS syntax: "3", "0,2,5", "2:8", "0:10:2", "-1", mixed "0,2:4,-1"), err_if_bad_index (default False), err_if_empty (default False), fallback_on_empty (first_frame / all_frames / blank).

Outputs: image, selected_count, skipped_count.

---

4. Indexed 2x2 Grid from Batch — IndexedGrid2x2FromBatch

Collapses a multi-node "select + label + grid-composite" subgraph into one node. Produces a batch of 2×2 grid images from an N-frame batch, with each cell labeled with its original frame index.

Example — N=8, stride=3 →

• Grid 1: frames 0,1,2,3
• Grid 2: frames 3,4,5,6 (stride=3 → 1-frame overlap)
• Grid 3: frames 4,5,6,7 (final grid backfilled from the end)

When N<4, outputs a single 2×2 grid with the missing cells black-filled (real frames are never repeated).

Inputs: images, stride (default 3), label_prefix (e.g. "frame "), label_font_size (default 16), label_bar_height (default 24).

Outputs:

• grids — IMAGE batch of M grids.
• grid_count — INT.
• index_groups_debug — STRING summary like "0,1,2,3 | 3,4,5,6 | 4,5,6,7".

---

5. Split Image Batch to List of Image Batches — SplitImageBatchToListOfImageBatches

Takes an IMAGE batch and emits a list of smaller batches (sub-batches), so ComfyUI iterates downstream once per sub-batch, each call receiving a multi-frame tensor of up to sub_batch_size. Perfect for feeding Claude pairs or quads of frames per CLI call (with send_all_frames=True).

Inputs:

• images — IMAGE batch.
• sub_batch_size — INT, frames per sub-batch (default 2).
• stride — INT, frames advanced per sub-batch. 0 means "same as sub_batch_size" (non-overlapping partition). 1 = sliding window, any other value = custom.
• last_sub_batch_policy — keep_remainder (default) / drop_remainder / pad_with_last.

Outputs (first three are scheduler-iterated lists):

• sub_batches — list of IMAGE sub-batches.
• start_index — list of INTs, the original-batch index where each sub-batch begins.
• end_index — list of INTs, inclusive end index.
• sub_batch_count — single INT.

The node displays a bottom hint: "stride 0: stride = sub-batch size".

---

Typical workflow patterns

Per-frame analysis with session reuse (cheapest):

VHS_LoadVideo → ImageBatchCurrentIndex → ClaudeCliVisionText (reuse_session=True)

N scheduler calls, one frame each. Same session_id across all runs.

Pair-wise analysis (cross-frame reasoning per pair):

VHS_LoadVideo → SplitImageBatchToListOfImageBatches (sub_batch_size=2)
              → ClaudeCliVisionText (send_all_frames=True, reuse_session=True)

N/2 calls, two frames per call.

2×2 grid montage per call:

VHS_LoadVideo → IndexedGrid2x2FromBatch (stride=3)
              → ClaudeCliVisionText (send_all_frames=True)

One call per grid image with all four labeled frames in a single view.

---

License

MIT.

---

Contributing

Issues and PRs welcome at https://github.com/RandyHaylor/comfyui-claude-cli-vision-text-node.