ComfyUI-Flux-Reference-Tools

ComfyUI-Flux-Reference-Tools

Nine generic Flux-family reference-conditioning nodes for ComfyUI: multi-reference latent chaining, per-reference K/V attention weighting, color/identity anchoring, and text-vs-reference conditioning balance.

Works on any Flux-family checkpoint — Flux.1, Flux.1 Kontext, Flux.2 Klein — because every node hooks mechanisms comfy's own core Flux code exposes generically, not anything specific to one checkpoint family:

• conditioning's own reference_latents / reference_latents_method keys (stock node_helpers.conditioning_set_values mutation, no custom conditioning format)
• model.set_model_attn1_patch / set_model_attn1_output_patch — fired on every DoubleStreamBlock/SingleStreamBlock forward call in comfy/ldm/flux/layers.py, shared code across the whole Flux family, with extra_options already carrying reference_image_num_tokens, block_index, block_type, and img_slice populated by comfy's own model code
• model_options["sampler_post_cfg_function"] — fired only through comfy's own CFGGuider/sampling_function, i.e. any sampling done through a real comfy sampling path (stock KSampler and equivalents)

None of these nodes download models, read tokenizer internals, or depend on any checkpoint-specific conditioning shape.

Origin

Extracted from Comfy-GGUF's Flux Klein node port (nodes/flux_klein.py), where these 9 classes originally carried "Klein"/"Flux2Klein" branding left over from that port. They were pulled out, renamed, and generalized here since none of the 9 actually read anything Klein-specific. Comfy-GGUF keeps its own Klein-branded copies of this logic unchanged for existing users.

The underlying mechanism design for these nodes originally came from ComfyUI-Flux2Klein-Enhancer by capitan01R (MIT License), via Comfy-GGUF's port of that pack.

Install

Clone (or copy) this repo into your ComfyUI custom_nodes/ directory:

cd ComfyUI/custom_nodes
git clone https://github.com/ChrisColeTech/ComfyUI-Flux-Reference-Tools

No extra Python dependencies — only torch and comfy's own node_helpers, both already provided by any ComfyUI install. Restart ComfyUI; the nodes appear under category 🤖 CCTech/Flux Reference.

Nodes

All nodes are searchable in ComfyUI's node search by their SEARCH_ALIASES.

reference_latents chaining

• Flux Multi Reference Latent (FluxMultiReferenceLatent) — attaches up to 8 reference latents to both positive and negative conditioning at once, using comfy's indexed reference method (reference_latents_method="index"). Each connected latent's batch is split into individual references. Overwrites any existing reference_latents, matching stock behavior rather than chaining.
• Flux Mask Ref Controller (FluxMaskRefController) — spatially attenuates one reference latent using a painted mask, replacing it in conditioning.

attn1_patch K/V scaling

• Flux Ref Latent Controller (FluxRefLatentController) — scales one reference's K/V attention contribution at every attention block, with an optional spatial fade (center-out / edges-out / top-down / left-right) over that reference's own token grid.
• Flux Ref Latent Weight (FluxRefLatentWeight) — the simple flat-multiplier case of the above, model-only, no conditioning input or spatial fade.
• Flux Text/Ref Balance (FluxTextRefBalance) — a single dial trading text K/V strength against reference K/V strength (0.0 = text only, 1.0 = reference only, 0.5 = both unscaled).

sampler_post_cfg_function pulling (requires stock KSampler)

• Flux Color Anchor (FluxColorAnchor) — nudges each denoising step's x0 prediction toward a reference latent's per-channel spatial-mean color, ramping in over the course of sampling.
• Flux Identity Guidance (FluxIdentityGuidance) — pulls each step's x0 prediction toward a VAE-encoded identity reference latent over a configurable sigma window, via adaptive/direct/channel_match blend modes.

Conditioning-tensor manipulation

• Flux Detail Controller (FluxDetailController) — per-section (front/mid/end) conditioning multiplier. Standalone, it uses a fixed 25/50/25 split of the active conditioning region. If Comfy-GGUF's Klein-specific Sectioned Encoder is also installed and its meta["klein_sections"] metadata is present on the conditioning, this node uses those real section boundaries instead.
• Flux Text Enhancer (FluxTextEnhancer) — normalize / contrast / magnitude adjustments on the active text conditioning region, with a safe (never sign-inverting) negative-contrast formula.

Example graph

A typical multi-reference edit chain:

FluxMultiReferenceLatent (up to 8 LATENT inputs)
        │  positive, negative
        ▼
FluxRefLatentController (per-reference K/V scale + spatial fade)
        │  model, conditioning
        ▼
   stock KSampler

FluxColorAnchor / FluxIdentityGuidance attach to model upstream of the KSampler (they read conditioning at apply-time and only need it if you want FluxColorAnchor to source its reference latent from there); FluxDetailController / FluxTextEnhancer / FluxMaskRefController sit on the conditioning path between your CLIP encoder and the reference/attention nodes above.