ComfyUI-FluxDetailGuidance

A single node — Flux Detail Guidance (FDG) — that adds natural micro-detail to a Flux.1 refine without raising denoise and without changing composition or text.

It's a Flux port of the "token detail guidance" self-guidance idea. Crucially, it's a per-forward-pass MODEL patch, so unlike full-image inversion/upscalers it runs inside tiled samplers (Ultimate SD Upscale, etc.) at 3K-4K. Pairs naturally with a clean solver such as seeds_3 at eta=0 (ComfyUI-SEEDS3Sampler).

How it works

During a chosen window of the denoise schedule, each step runs the model twice:

eps_full = model(x)                  # normal
eps_weak = model(x) with the image-token high-frequency detail attenuated
                                     # in a selected band of Flux double-blocks
delta    = eps_full - eps_weak       # = the detail the model was adding
eps      = eps_full + scale * shaped(delta)

shaped() splits the delta into mid/high frequency bands (weighting high-freq more in late steps), gates the hardest edges to avoid outline halos, and std-limits it, so you get texture/detail back without color drift or crunchy edges. An output_rescale stabilizer blends the result back toward the normal pass.

Cost: ~2x model evaluations during the active window only.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/lookuters22/ComfyUI-FluxDetailGuidance

Restart ComfyUI. Node appears under Flux/experimental.

Wiring (refiner)

UNETLoader -> (LoRAs) -> ModelSamplingFlux -> Flux Detail Guidance -> UltimateSDUpscaleCustomSample

Use a clean sampler (e.g. SEEDS-3 Sampler eta=0) and the ays scheduler.

Parameters

| Param | Default | Notes | |-------|---------|-------| | double_start / double_end | 10 / 19 | Double-block band to weaken (Flux-dev has 19). Set end <= start to disable. | | single_start / single_end | 15 / 38 | Single-block band to weaken (Flux-dev has 38 — most of the detail lives here). Set end <= start to disable. | | step_start / step_end | 0.0 / 1.0 | Active window as a fraction of the executed steps. At low denoise (e.g. 0.3) the executed steps are already the tail, so keep step_start near 0. | | guidance_scale | 0.35 | Detail strength. Main dial. Start 0.3-0.6 and raise until it looks crunchy. | | weaken_strength | 0.5 | How hard the weak pass suppresses detail per block (bigger delta = more effect). | | blur_passes | 1 | Defines the "detail" scale (high-freq residual). 1 = finest. | | output_rescale | 0.3 | Stabilizer toward the normal-pass statistics. Lower = more raw detail. | | adaptive_gate | True | Only weaken where local detail energy is high; keeps flat areas clean. |

Tuning: not enough detail -> raise guidance_scale, widen the single-block band, or lower output_rescale. Halos / crunch / "flat contrasty default-Flux look" -> lower guidance_scale, narrow the band, and avoid weakening the early blocks (keep the bands in the back half of each stack so the weak pass stays a detail-starved model, not a broken one).

Notes / limitations

• Flux only. Requires .model.diffusion_model.double_blocks + single_blocks; it refuses to patch non-Flux models. (Z-Image / SD / SDXL are different architectures.)
• Patches both double-blocks (pure image stream) and single-blocks (image tokens sliced out of the [txt ; img] sequence via transformer_options["img_slice"]).
• If a step's image-token count doesn't match a plain grid (e.g. Kontext/reference latents add tokens), the weak attenuation safely no-ops for that pass.
• Cost: ~2x model evaluations during the active window only.

License

MIT. No ComfyUI source is copied; only public model-patcher APIs are used.