Flux Ref Latent Controller ⚡

Of all nine nodes in ComfyUI-Flux-Reference-Tools, this is the one you'll spend the most time with. Flux Ref Latent Controller is the "how strongly does reference number N influence the image" dial - per-reference, per-attention-block, with an optional spatial fade so you can say this reference matters in the middle of the frame but not at the edges. If the pack shipped nothing but this node, it would still be worth installing.

The mental model is simple: once reference latents are attached to conditioning (via Flux Multi Reference Latent), every attention block in the Flux model computes key/value vectors for those reference tokens just like it does for your prompt tokens. This node scales the K and V for one chosen reference's tokens, at every attention block, before attention runs. Scale them up and the reference's influence grows; scale toward 0 and the model politely ignores that reference.

How it works

The node clones your model and installs an attention patch (set_model_attn1_patch) that fires on every DoubleStreamBlock/SingleStreamBlock forward call - shared code across the whole Flux family. It reads reference_image_num_tokens from comfy's own extra_options to find the exact token slice for the reference you picked with reference_index, then multiplies that slice's K and V by your strength. This works on any Flux-family checkpoint (Flux.1, Kontext, Klein) because it never computes anything about the model's internals itself - comfy already exposes the bookkeeping.

The spatial fade is the clever part. Instead of a flat multiplier, it generates per-token weights derived from the reference latent's own 2D grid (patch size 2), so center_out keeps the middle of the reference influential while fading the outside, edges_out does the opposite, and top_down / left_right fade along one axis. Handy when a reference image has what you want in the center (say, a subject) and junk around the border.

The inputs that matter

• strength (default 1.0, range 0–1000) - the flat K/V multiplier. Yes, 1000 is a lot; the headroom is for situations where you're fighting another patch. Below 1 attenuates, above 1 amplifies. 0 effectively removes that reference.
• reference_index (0–7) - which attached reference to scale. Matches the order you attached them.
• spatial_fade - none (default), center_out, edges_out, top_down, left_right.
• spatial_fade_strength (default 0.5) - how aggressive the fade gradient is.

Outputs are MODEL and CONDITIONING - the conditioning passes through unchanged, so you can thread it into the next controller or the KSampler.

Where it sits in the workflow

After the reference-attachment node, before the KSampler - feed its model into the sampler and keep the conditioning on the same path. Chain multiple controllers (one per reference) if you want different strengths for different refs; each patches its own slice.

Install

Same story as the rest of the pack: zero extra dependencies, zero downloads.

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

Restart, search "Flux Ref Latent Controller" under 🤖 CCTech/Flux Reference, or use ComfyUI Manager.

Common issues

• Nothing changes when you move strength. Most likely reference_index points at a reference that isn't attached - check the wiring into Flux Multi Reference Latent and the order. Also make sure the conditioning input actually carries the reference metadata; this node reads it to find the fade geometry.
• Strength above 1 causes weird artifacts. Amplifying K/V past ~1.5-2x can wash out the image or inject the reference too hard. Dial it back; the sweet spot for "make reference N stronger" is usually 1.1–1.5.
• The pack is new. It shipped in August 2026 with essentially zero community footprint, so treat default values as starting points, not doctrine. The mechanism (stock comfy attention patches) is well-trodden; the exact feel of these dials is yours to tune.