{"id":30687299,"url":"https://github.com/regiellis/ComfyUI-SDXL-Adherence","last_synced_at":"2025-09-02T00:03:58.551Z","repository":{"id":311966741,"uuid":"1045810769","full_name":"regiellis/ComfyUI-SDXL-Adherence","owner":"regiellis","description":"Custom nodes that make SDXL follow your prompt better and run smoother on single-GPU rigs","archived":false,"fork":false,"pushed_at":"2025-08-27T22:35:12.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T03:33:00.558Z","etag":null,"topics":["comfyui","comfyui-custom-node","comfyui-nodes","sdxl"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/regiellis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-27T18:39:42.000Z","updated_at":"2025-08-27T22:35:15.000Z","dependencies_parsed_at":"2025-08-28T03:52:28.769Z","dependency_job_id":null,"html_url":"https://github.com/regiellis/ComfyUI-SDXL-Adherence","commit_stats":null,"previous_names":["regiellis/comfyui-sdxl-adherence"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/regiellis/ComfyUI-SDXL-Adherence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regiellis%2FComfyUI-SDXL-Adherence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regiellis%2FComfyUI-SDXL-Adherence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regiellis%2FComfyUI-SDXL-Adherence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regiellis%2FComfyUI-SDXL-Adherence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/regiellis","download_url":"https://codeload.github.com/regiellis/ComfyUI-SDXL-Adherence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regiellis%2FComfyUI-SDXL-Adherence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273208777,"owners_count":25064204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comfyui","comfyui-custom-node","comfyui-nodes","sdxl"],"created_at":"2025-09-02T00:01:51.360Z","updated_at":"2025-09-02T00:03:58.542Z","avatar_url":"https://github.com/regiellis.png","language":"Python","funding_links":[],"categories":["Workflows (3395) sorted by GitHub Stars"],"sub_categories":[],"readme":"\n---\n\n# SDXL Adherence ⚡\n\n[![ComfyUI](https://img.shields.io/badge/ComfyUI-Custom_Node-00bcd4?logo=pytorch)](https://github.com/comfyanonymous/ComfyUI)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nCustom nodes that make SDXL follow your prompt better and run smoother on single-GPU rigs.\n\nYou don’t need a new model to ship good work. This pack patches SDXL’s weak spots: adherence, negatives, and high-res stability.\n\n\u003e [!Caution]\n\u003e This node is a work in progress and may not cover all use cases. Please test thoroughly and provide feedback.\n\n\u003e [!IMPORTANT]\n\u003e This node was designed and created with my personal needs and goals in mind. This may not fit your specific use case or project and you may need to adapt it accordingly. I encourage you to experiment and modify it to better suit your needs.\n\u003e\n\u003e If you find it useful, please consider supporting my work by starring the repository or sharing it with others who might benefit from it. But please understand, this is a personal project and released only in an effort to help others and as with most open-source projects, done in my free time with no support or pay.\n\u003e\n\u003e Please keep that in mind when leaving issues, comments, etc.\n\n---\n\n## Why this exists\n\n* Flux and other DiT-style models are great, but most are aimed at 48–80 GB cards or cloud inference.\n* SDXL still has the strongest ecosystem (LoRAs, ControlNets, adapters, VAEs, fine-tunes).\n* Out of the box, SDXL can drift from your subject, waste tokens, and choke on odd aspect ratios.\n* Recent ComfyUI builds handle long prompt chunking silently (no more 77-token warnings), but they don’t **prioritize which tokens land in which chunk, clean negatives, or snap resolutions safely**. These nodes add that missing layer of *control, consistency, and guardrails*.\n\nThese nodes fix those gaps so you can keep moving fast on a single 24 GB GPU or less.\n\n---\n\n## Quick start (2 minutes)\n\n1. Install in `ComfyUI/custom_nodes` (see Install below) and restart ComfyUI.\n2. Load an SDXL checkpoint → get model, clip, vae.\n3. Drop in these nodes:\n\n   * Smart Latent (mode: *Empty* for new images, or *Encode Image* for img2img/inpaint)\n   * SDXL Prompt Styler (pick a style; keep “Normalize Negatives” on)\n   * SDXL Dual CLIP Encode (wire the 4 texts from the styler)\n4. KSampler: connect model + latent + cond+/cond-.\n5. VAE Decode (tiled if needed). If you padded at encode, use Crop By BBox at the end.\n\nThat’s it. Bigger images? Smart Latent snaps sizes to 64 safely and uses tiled VAE automatically when available.\n\n---\n\n## Node cheat sheet\n\n* **SDXL Prompt Styler 🎨**\n\n  * Protects subject (early/late split), adds style preset, cleans negs.\n  * Essentials automation: strategy controls (off/conservative/balanced/aggressive), allow/block lists, and max\\_essentials cap.\n  * Auto pivot for early/late based on prompt length; manual early\\_ratio available.\n  * Good defaults: style=cinematic/portrait; normalize\\_negatives=on; essentials\\_strategy=balanced.\n\n* **SDXL Dual CLIP Encode 🔗**\n\n  * Builds pos+neg conditioning with pooled_output (stable for SDXL ADM).\n  * Modes: `auto` (default), `core_parity`, `custom_only` — see Encoder modes below.\n  * Auto adds soft-ramped head/tail assists and early-only essentials on long prompts.\n  * Resolution-aware nudges; optionally wire sampler context (steps→`total_steps`, cfg→`cfg`) for adaptive ramps.\n  * Good defaults: early_late_mix=0.4; essentials_lock=0.35.\n\n* **Smart Latent 📐**\n\n  * Makes empty latents or encodes images at any size. Snaps to 64 safely.\n  * Resolution presets dropdown with aspect ratios; selecting a preset overrides width/height (empty mode).\n  * Good defaults: snap\\_mode=pad\\_up; tile\\_size=320; keep alpha-safe padding.\n\n* **Align Hints To Latent (helper)**\n\n  * Resizes/pads canny/depth/lineart/etc. to exactly match latent W×H.\n\n* **Crop By BBox (helper)**\n\n  * After decode, crops padded generations back to the original content.\n\n* **Auto-Size 64 (MP) (helper)**\n\n  * Pick target megapixels and snap W/H to 64-multiples. Size: Auto/1.0MP/1.5MP/2.0MP.\n\n* **Negative Prompt Helper (helper)**\n\n  * Toggle Realism Negs to merge a vetted pack with your negatives and de-dup.\n  * Helps counteract SDXL’s tendency toward plastic skin / CGI by merging a curated set automatically.\n\n* **Post Polish (Film Touch) (helper)**\n\n  * Tiny tone S-curve + subtle grain for micro-texture. Place last.\n\n---\n\n### Encoder modes\n\n* **Auto (default)** — Uses a single fused encode (like core) on long prompts, then adds tiny, **soft-ramped** assists (head/tail echoes; early-only essentials) to improve adherence without new knobs.\n* **Core parity** — Bypasses assists; behaves like the stock ComfyUI SDXL encoder for maximum predictability.\n* **Custom only** — Keeps short/medium-prompt controls (early/late/essentials multi-entry blending) for aesthetic steering.\n\n\u003e [!IMPORTANT]\n\u003e **Seeing a sudden, drastic change in the KSampler preview mid-run?**  \n\u003e That’s usually a *conditioning schedule* issue (guidance turning on/off too abruptly), or an overly strong guidance stack. Try these:\n\u003e\n\u003e 1) **Switch `mode`**  \n\u003e    * For long prompts: set `mode = core_parity` to match core exactly.  \n\u003e    * For short/medium prompts: `mode = custom_only` if you want early/late control without long-prompt assists.\n\u003e\n\u003e 2) **Pass sampler context (so ramps adapt)**  \n\u003e    If available, wire your KSampler **`steps`** and **`cfg`** to the encoder’s optional inputs (`total_steps`, `cfg`).  \n\u003e    The encoder will auto-shrink ramps and extra weights at high CFG / low step counts to prevent late flips.\n\u003e\n\u003e 3) **Keep guidance moderate**  \n\u003e    * **CFG** ~ 5.5–7.0  \n\u003e    * **CFG rescale** ~ 0.7–0.8 (extremes can cause late instability)\n\u003e\n\u003e 4) **Make the canvas stable**  \n\u003e    * Use **64-safe sizes** (e.g., 1536×896)  \n\u003e    * Avoid stacking many heavy **LoRAs**; keep combined LoRA influence reasonable  \n\u003e    * If using other conditioning nodes (regional prompts, control adapters), try disabling them to isolate the cause\n\u003e\n\u003e 5) **Essentials got too pushy?**  \n\u003e    Leave `essentials_text` empty for very long prompts, or simplify it. The encoder already *time-limits* essentials to early steps, but redundant terms can still over-constrain.\n\u003e\n\u003e **Debugging:** set environment variable `ADHERENCE_DEBUG=1` to print a one-line summary (tokens, caps, ramp slices) for each run.\n\n\n## Install\n\nClone into your ComfyUI custom\\_nodes directory:\n\n```bash\ncd ComfyUI/custom_nodes\ngit clone https://github.com/yourname/ComfyUI-SDXL-Adherence.git\n```\n\nRestart ComfyUI.\n\n---\n\n## Any-size + tiled VAE (what this solves)\n\nSmart Latent accepts any H×W and safely snaps to 64-multiples:\n\n* pad\\_up: letterbox with reflect/edge/constant (alpha-safe), preserves content\n* downscale\\_only: fit inside lower 64-multiple, then pad the small residuals\n* resize\\_round: resize near the nearest 64 (may change aspect)\n* crop\\_center: centered crop down to the lower 64 (no resize)\n\nIf your VAE has tiled encode/decode, the wrappers pick the right signature automatically and fall back to non-tiled if needed. This lets you push larger sizes on 24 GB GPUs with fewer OOMs.\n\nOutputs include dims\\_json and bbox\\_json so you can align hints 1:1 and crop back after decoding.\n\n---\n\n## Prompt adherence beyond 77 tokens\n\n* ComfyUI SDXL CLIP silently splits long prompts into 75-token chunks. That means you won’t see the old “77 token” warning, but the limit is still there.\n* Extra tokens **do still matter** up to \\~225–250, but unmanaged they can dilute subjects.\n* These nodes:\n\n  * Bias important tokens (subject, camera, lighting) into the first chunk.\n  * Drop filler/duplicates to fit the token budget.\n  * Give you optional reporting so you know what stayed, what was dropped, and where it landed.\n\n---\n\n## Usage diagram\n\n```text\n[CheckpointLoader] -\u003e (model, clip, vae)\n    |                 |      |\n    |                 |      v\n    |                 |  [SmartLatent]\n    |                 |     └─\u003e (latent, dims_json, bbox_json, W, H)\n    |                 v\n    |           [SDXL Prompt Styler]\n    |                 └─\u003e (early, late, neg, essentials)\n    v\n[SDXL Dual CLIP Encode]\n    └─\u003e (cond_positive, cond_negative)\n\n(cond+, cond-) + (model, latent) -\u003e [KSampler] -\u003e [VAE Decode]\n                                            └─\u003e (image)\n\nOptional helpers:\n\nImage → Auto-Size 64 → Smart Latent/Encode  \nNeg → Negative Prompt Helper → SDXL Dual CLIP Encode (negative)  \n… → VAE Decode → Post Polish → (final)  \nOptional: [Crop By BBox] with bbox_json -\u003e (image cropped)\n```\n\n---\n\n## Recommended defaults\n\n* Sampler: DPM++ 2M SDE Karras, 28 steps, CFG 6.0, rescale 0.8, ETA=0\n* Smart Latent: snap\\_mode=pad\\_up, tile\\_size=320\n* Prompt Styler: normalize\\_negatives=True, style=cinematic/portrait/etc.\n* Dual CLIP Encode: early\\_late\\_mix=0.4; essentials\\_lock=0.35 (auto-bumps on \u003e1280px)\n\n---\n\n## Speed and VRAM tips\n\n* Prefer pad\\_up over full-resize to keep detail without extra compute.\n* If you see OOM, lower tile\\_size (e.g., 320 → 256) or reduce the long side.\n* Keep ControlNet hints aligned via Align Hints To Latent to avoid wasted steps.\n* Avoid stacking many heavy LoRAs at once; mix fewer, stronger ones.\n\n---\n\n## Troubleshooting\n\n* NoneType pooled\\_output or ADM crash: always run conditioning through SDXL Dual CLIP Encode from this pack.\n* Sampler shape mismatch: ensure hints go through Align Hints To Latent and that latent W×H match the sampler.\n* Washed-out style or broken subject: turn down early\\_late\\_mix, bump essentials\\_lock, or simplify the style.\n* Output size wrong after decode: use Crop By BBox to get back to your original content size.\n\n---\n\n## Why not just switch to Flux?\n\nFlux and other DiT-style models are promising:\n\n* Better prompt adherence out of the box\n* Longer context window\n\nBut today they’re aimed at bigger GPUs + cloud inference. On consumer cards, you’ll hit VRAM ceilings, and the support ecosystem (LoRAs, ControlNets, adapters) is still catching up.\n\nFlux Dev, Flux Krea, and Flux ControlNets are improving fast — but licensing is restrictive and VRAM demands are steep. SDXL is still open for commercial work and runs well locally. With these adherence nodes, SDXL remains competitive in image quality while avoiding VRAM and licensing headaches.\n\n---\n\n## Documentation\n\n* Smart Latent: docs/SmartLatent.md\n* SDXL Dual CLIP Encode: docs/SDXLDualClipEncode.md\n* SDXL Prompt Styler: docs/SDXLPromptStyler.md\n* Align Hints To Latent: docs/AlignHintsToLatent.md\n* Crop By BBox: docs/CropByBBox.md\n\n---\n\n## License\n\nMIT — use it, hack it, ship it. Don’t sell it as “secret sauce.”\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregiellis%2FComfyUI-SDXL-Adherence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fregiellis%2FComfyUI-SDXL-Adherence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregiellis%2FComfyUI-SDXL-Adherence/lists"}