Extensions/comfyui-character-suite

ComfyUI Extension

comfyui-character-suite

A node suite for prompt engineering with persistent character and segment libraries.

By DrkSun81·Created 2 months ago·Updated 24 days ago· 0

DrkSun81/comfyui-character-suite

Nodes—

On cloudLocal install

Stars0

Updated24 days ago

Readme

ComfyUI Character Suite

A node suite for prompt engineering with persistent character and segment libraries.

| | | |---|---| | Version | 1.1.1 | | Revision | bb8b76d | | Released | 2026-07-26 |

Changelog (recent)

1.1.1 (bb8b76d) — Fix CS_LoraStacker FLOAT "None" errors: strength/bypass widgets no longer use converted-widget hide (which skipped them in the prompt and shifted combo "None" into FLOAT fields). Visual collapse only; client-side float/bool coercion; server-side _as_float / _as_bool guards.
1.1.0 — LoRA Stacker node with CivitAI trigger-word picker and example workflow.
1.0.0 — Initial release (Character Expander, segments, Prompt Builder, web Character Manager).

Installation

cd ComfyUI/custom_nodes/
git clone https://github.com/DrkSun81/comfyui-character-suite
# or extract the zip directly into custom_nodes/

Restart ComfyUI. No pip dependencies required.

Windows note: Requires Python 3.9+ (tested on 3.11). The embedded Python included with the standalone ComfyUI build is fully supported.

Example Workflow

An example workflow is included at examples/character_suite_example.json.

Drag it into ComfyUI to load a fully wired setup covering all nodes:

{Avery} expansion through CharacterExpander
Segment injection via SegmentLoader → Prompt Builder (CharacterSuite)
CLIP encoding → KSampler → SaveImage
PromptCategorizer wired off the final positive prompt
SegmentSaver ready to capture the built prompt for reuse

Before running: update the checkpoint in the CheckpointLoaderSimple node to one you have installed. The default (illustrious/absoluteTerritory_v3.safetensors) is set as a placeholder.

Nodes

All nodes appear under the CharacterSuite category in the Add Node menu.

🎭 Character Expander

Class name: CharacterExpander

Finds {Name} tokens in your prompt and replaces them with that character's stored tags. The character's negative prompt is automatically collected and merged into the negative output.

Inputs: | Name | Type | Description | |------|------|-------------| | positive_text | STRING | Your prompt, e.g. {Avery}, wearing armor, in a dungeon | | negative_text | STRING | Your base negative prompt | | merge_mode | COMBO | append (default) or prepend — where character tags land |

Outputs: positive, negative, expansion_log

Example:

Input positive:  {Avery}, wearing armor, in a dungeon
Output positive: 1girl, silver hair, heterochromia, red left eye, blue right eye,
                 athletic build, confident expression, wearing armor, in a dungeon

Supports multiple characters in one prompt: {Avery} and {Kira}

🗂️ Prompt Categorizer

Class name: PromptCategorizer

Splits a flat comma-separated prompt into labeled buckets using keyword heuristics.

Inputs: | Name | Type | Description | |------|------|-------------| | prompt | STRING | Any prompt string to analyze | | use_llm | BOOLEAN | Send unclassified tags to a local LLM (default off) | | llm_api_url | STRING | LM Studio / Ollama endpoint (optional) |

Outputs: categorized_text (formatted summary) + one STRING output per category:

| Output | Examples | |--------|----------| | quality | masterpiece, best quality, highres | | style | anime, cel shading, watercolor | | character | 1girl, heterochromia, confident expression | | hair | long silver hair, twintails | | clothing | school uniform, thighhighs | | action | running, holding sword | | pose | cowboy shot, from above | | scene | forest, sunset, rain | | lighting | rim light, dramatic lighting | | misc | everything else |

Wire any individual output directly into other nodes.

💾 Save Prompt Segment

Class name: SegmentSaver

Saves any prompt string as a named entry in the persistent segment library.

Inputs: | Name | Type | Description | |------|------|-------------| | prompt_text | STRING | The prompt content to save (linkable) | | category | COMBO | One of: quality, style, character, hair, clothing, action, pose, scene, lighting, misc | | label | STRING | Your name for this segment, e.g. plate armor fantasy |

Output: status — confirmation string shown in a Show Text node.

Saving with an existing category + label combination overwrites the previous entry.

📂 Load Prompt Segments

Class name: SegmentLoader

Loads up to 4 saved segments by category + label and concatenates them.

Inputs: Four category / label pairs (set category to (skip) to leave a slot unused), plus a separator string (default , ).

Outputs: combined_prompt (all loaded segments joined), load_log (what was found/missed).

Wire combined_prompt into Prompt Builder (CharacterSuite) segment_a, or directly into a CLIP encoder.

🔍 Browse Segments

Class name: SegmentBrowser

Lists all saved segments. Wire output into a Show Text node to view your full library.

Input: category — (all) to show everything, or pick a specific category to filter.

Output: segment_list — formatted text block.

🔨 Prompt Builder (CharacterSuite)

Class name: CS_PromptBuilder

Note: The internal registry key is CS_PromptBuilder (not PromptBuilder) to avoid conflicts with other installed node packs. In the Add Node menu it appears as Prompt Builder (CharacterSuite).

Merges a character-expanded prompt with loaded segment strings into final positive and negative outputs.

Required inputs: | Name | Type | Description | |------|------|-------------| | base_positive | STRING | Positive prompt from CharacterExpander | | base_negative | STRING | Negative prompt from CharacterExpander | | insert_mode | COMBO | append, prepend, or after_quality | | use_break | BOOLEAN | Insert BREAK between sections instead of , |

Optional inputs: segment_a, segment_b, segment_c (from SegmentLoader or any STRING), extra_negative

Outputs: final_positive, final_negative

Insert modes:

append — segments go after your base prompt
prepend — segments go before
after_quality — inserts after the last quality tag (masterpiece, best quality…)

Web Panel — Character Manager

A Characters sidebar tab is added to ComfyUI automatically (look for the person icon in the left sidebar panel). On older ComfyUI builds without the extensionManager API a floating 🎭 Characters button appears in the top-right corner instead.

Features:

Search characters by name or tag
Create / edit / delete characters with positive + negative prompts
Copy positive prompt to clipboard
Tags for filtering and organization

Characters are stored in data/characters.json inside the node folder.

Data Files

data/
  characters.json   # character name → positive/negative/tags
  segments.json     # id, category, label, content, created

These are plain JSON — safe to edit manually or back up.

Typical Workflow

[CharacterExpander]
  positive_text: "{Avery}, wearing armor, in a dungeon"
  negative_text: "worst quality, low quality, blurry"
        |
        ├─ positive ──→ [Prompt Builder (CharacterSuite)] ──→ final_positive ──→ [CLIPTextEncode] ──→ [KSampler]
        └─ negative ──→ [Prompt Builder (CharacterSuite)] ──→ final_negative ──→ [CLIPTextEncode] ──┘

[SegmentLoader]
  category_1: clothing  label_1: plate armor fantasy
        |
        └─ combined_prompt ──→ [Prompt Builder (CharacterSuite)] segment_a

[PromptCategorizer] ← wire final_positive in to analyze the built prompt
[SegmentSaver]      ← wire final_positive in to save a refined look for reuse
[SegmentBrowser]    ← standalone, wire segment_list to a Show Text node

LLM Categorization

Set use_llm = True in the Prompt Categorizer node and provide your local API URL:

LM Studio: http://localhost:1234/v1/chat/completions
Ollama: http://localhost:11434/v1/chat/completions

Heuristics run first; only unmatched tags are sent to the LLM. Any instruct model works, 7B+ recommended for best results.

Compatibility

| Component | Requirement | |-----------|-------------| | ComfyUI | Any recent version | | Python | 3.9+ (3.11 recommended, tested) | | Frontend | Sidebar tab requires ComfyUI frontend 1.x (extensionManager API); older builds get a floating panel fallback | | OS | Windows, Linux, macOS | | Dependencies | None required (stdlib only). If requests is already importable in your environment, the CivitAI tag fetch uses it for more reliable HTTP handling; otherwise it transparently falls back to urllib. |