Three small things between the Windows clipboard and Claude Code’s chat input are broken. Each one is harmless on its own. Together they make image paste fail completely. Here’s what they are and the workaround I built until the upstream fixes catch up.

What’s actually broken

1. The Windows-to-Linux clipboard sync only knows about an ancient image format

WSL has a built-in piece called WSLg (the “g” is for graphics). Its job is to make Windows and the Linux side share things — including the clipboard, so copy-paste works across the boundary. For text, it works fine. For images, it does two things badly.

First, it only syncs images in one direction: from Windows to Linux. Anything copied from a Linux app doesn’t flow back to Windows as an image.

Second, when WSLg sends a Windows image over to Linux, it converts it into a single, dated format — a specific old BMP variant that uses an obscure colour encoding (“BI_BITFIELDS”). Most software’s BMP readers can’t handle it. Claude Code’s reader is one of those. It tries to read what arrives, gets nothing useful, and gives up — silently. No error, no toast, no visible failure. The image just doesn’t attach.

(This is a known bug: claude-code#50552.)

2. The same Windows-to-Linux sync silently overwrites your workarounds

You might think: fine, I’ll bypass WSLg for images. Read the Windows clipboard myself, convert the image to PNG, push the PNG straight onto the Linux clipboard. Claude Code will then find a PNG when it looks for an image, and the paste will work.

There’s even a standard Linux command for putting things on the clipboard: wl-copy. So you do exactly that — Windows image → PNG → wl-copy --type image/png.

It works. For a moment. Then it stops working again. Here’s what WSL does to you:

1. You put a PNG on the Linux clipboard.
2. WSLg notices the Linux clipboard changed, and dutifully syncs it back to Windows. The Windows clipboard now reflects “PNG.”
3. The Windows clipboard just changed. That fires WSLg’s other half — the half that pushes Windows changes over to Linux. As we know from problem #1, that half only knows how to push BMP.
4. So your good PNG on the Linux side gets overwritten with the broken BMP, shortly after you put it there.

The cruellest part: the program you wrote to watch the Windows clipboard never sees step 4 happen. WSLg writes to the Linux clipboard directly — it doesn’t go through the Windows clipboard to do it. So from your watcher’s point of view, the Linux clipboard just silently mutates, with nothing for you to react to.

3. Windows Terminal eats Ctrl+V before Claude Code sees it

Suppose you fix everything above and a real PNG sits reliably on the Linux clipboard. Press Ctrl+V in Claude Code. Still nothing happens.

The reason: Windows Terminal — the program you’re typing into — has its own meaning for Ctrl+V. It’s the standard “paste text from the Windows clipboard” shortcut. So when you press Ctrl+V inside Windows Terminal:

1. Windows Terminal sees the keystroke first.
2. It pastes (or tries to paste) the Windows clipboard as text into the terminal input.
3. The keystroke never makes it down to the Linux side.
4. Claude Code’s image-paste code (internally named chat:imagePaste) never runs.

The terminal is one layer above Claude Code. It eats the input before the program below can react.

The fix

Three small components, one per failure, laid out in the diagram below.

• clip-listener.exe — runs on Windows and encodes each clipboard image as a real PNG via Windows’ own GDI+. Sidesteps the BMP problem (#1).
• wsl-clip-bridge — runs in WSL, pushes the PNG onto the Linux clipboard with wl-copy, and re-asserts once half a second later if WSLg has overwritten our PNG with the broken BMP. Handles the silent clobber (#2).
• Alt+V keybinding in ~/.claude/keybindings.json — triggers Claude Code’s chat:imagePaste handler without going through Ctrl+V, which Windows Terminal would eat. Routes around #3.

What changes when the bridge is installed. Without it (top), images flow straight to Claude Code as broken BMP and the paste fails. With it (bottom), a Windows listener encodes a real PNG and a Linux script puts it on the Linux clipboard, re-asserting once after WSLg's overwrite. The user presses Alt+V instead of Ctrl+V to bypass Windows Terminal.

End to end: snip an image in Windows, press Alt+V in Claude Code, image attaches.

The full source — the Go listener, the bash bridge, the install script, and a more detailed walkthrough — lives at github.com/rajveerb/wsl-clip-bridge.

Try it yourself

Prerequisites: WSL2 with WSLg (Windows 11, or a recent Windows 10 + WSL update), Go 1.20+ on the Linux side for cross-compiling the Windows binary.

git clone https://github.com/rajveerb/wsl-clip-bridge.git
cd wsl-clip-bridge
sudo apt install wl-clipboard
./install.sh --with-autostart --with-keybinding

That last command does four things: cross-compiles the Windows-side listener (GOOS=windows GOARCH=amd64), drops the binaries into ~/.local/share/wsl-clip-bridge/ and ~/.local/bin/, appends a snippet to ~/.bashrc that starts the bridge on every new WSL shell, and writes ~/.claude/keybindings.json with alt+v → chat:imagePaste.

Open a fresh WSL terminal. The bridge starts in the background. Verify:

# copy any image in Windows (Win+Shift+S)
wl-paste -l   # should print image/png

Then in Claude Code, press Alt+V. The image attaches.

The repo README walks through each step in more detail (running without the install script, stopping or uninstalling the bridge, debugging via the log).

Whose problem is it?

Four things contribute to the failure. The first problem above (“an ancient image format”) is really two separate issues, so the table splits them apart:

#1 is hardcoded in WSLg’s clipboard bridge (rdpclip.c in Microsoft’s Weston fork): exactly five Windows→Linux format mappings, and the only image one is CF_DIB → image/bmp. The strings image/png and image/jpeg don’t appear in the source. The upstream issue microsoft/wslg#833 has been open since September 2022.

#2 is broader than the post above implies, and more fixable than I first thought. Claude Code bundles sharp as its image library, in its WebAssembly build. That build’s bundled libvips has no BMP loader — not just no BI_BITFIELDS variant, no BMP support of any kind. Claude Code does detect BMP on the clipboard and try to convert it via sharp(bmpBuffer).png().toBuffer(), but the call dies with “Input buffer contains unsupported image format.” Despite the user-facing implication that BMP is supported, sharp’s WASM build can’t read any BMP. The actual upstream fixes are: ship sharp’s native libvips build (which has BMP support); ship a small BMP→PNG converter that doesn’t go through sharp at all; or shell out to ImageMagick or GDI+ on detection failure. Any of these obsoletes this entire bridge.

#3 isn’t hypothetical. The bridge’s log on this machine shows it directly, with timestamped lines like re-asserted clip-1.png (was: image/bmp,) after every Snipping Tool capture. Interestingly, synthetic Clipboard::SetImage calls from PowerShell never triggered it; only the Snipping Tool path did, which suggests WSLg keys off something specific in how Snipping Tool finalises its writes. A single re-assertion at +0.5 s catches it reliably; the three additional retries I tried earlier never fired.

#4 is hardcoded in a place that surprised me. Windows Terminal’s Ctrl+V handler isn’t in defaults.json (that file only binds Ctrl+Shift+V). It’s in ConHost’s windowio.cpp, where the inputKeyInfo check on 'V' with IsInVirtualTerminalInputMode and ShouldTakeOverKeyboardShortcuts swallows the keystroke before the inner program ever sees it. Tracked at microsoft/terminal#5790, open and on “Backlog” since 2020.

The kicker on #4 — Claude Code already defaults chat:imagePaste to Alt+V on native Windows. It just doesn’t apply that default in WSL, because WSL reports as Linux and the Windows-specific code never runs. The cleanest upstream fix isn’t even new functionality: detect “running in WSL inside Windows Terminal” at startup and apply the existing Windows Alt+V default there too. No keybinding file required from the user.

When this stops being needed

• WSL starts sending PNG to Linux → the Windows listener is no longer needed.
• Claude Code learns to read the BMP variant → the Windows listener is no longer needed.
• Windows Terminal stops grabbing Ctrl+V → the custom keybinding is no longer needed.

When all three happen, removing the workaround is one pkill, a couple of rms, and taking the relevant snippets out of .bashrc and ~/.claude/keybindings.json. Nothing else on the system depends on it.

Context streaming overlaps retrieval with prefill, reducing TTFT by beginning inference as chunks arrive.

For a single request, streaming context is straightforward and effective.

Now serve four requests at once. Each is streaming context at a different rate. Each holds KV cache blocks in GPU memory for its growing input. Memory fills up. The scheduler must decide: which request gets evicted? Should its cache be discarded or swapped to CPU? And what happens when a request’s input changes mid-flight because the search algorithm found better documents?

Prior streaming systems do not answer these questions – they evaluate single-request scenarios only. Stream2LLM extends vLLM to handle concurrent streaming, delivering up to 11x faster time-to-first-token (TTFT) while maintaining throughput parity. But there is a catch: naive streaming under memory pressure makes tail latency 5x worse than not streaming at all. Getting the scheduler right is the difference between an 11x win and a 5x regression.

Why Memory and Scheduling Matter

LLM inference has two phases. The prefill phase processes all input tokens in parallel, storing a key vector and value vector for every input token in GPU memory – the KV cache. The decode phase generates tokens one at a time, attending to the full cache at each step.

The cache is expensive. For Llama-3.1-8B with a 32K-token input, it is 4 GB per request in FP16. Serve four concurrent requests and you already have 16 GB of KV cache alone. Scale retrieval time further and memory runs out given the total requests kv state resident in given window of time. When it does, the inference system must evict requests: either discard their cache (recomputation) or move it to CPU (swapping). Both cost time.

Traditional inference waits for all documents before starting prefill. Time-to-first-token is retrieval time plus prefill time, and retrieval dominates – often seconds. Streaming eliminates this wait by feeding documents to the model as they arrive, but existing solutions only handle one request at a time. None address what happens when many requests stream simultaneously.

Two Kinds of Streaming

The complication is that context retrieval doesn’t follow a single pattern. There are two, and they break the KV cache in different ways:

• Append-mode (web crawlers): Documents arrive sequentially and extend the input. [c1, q] becomes [c1, c2, q]. The cached prefix stays valid, so only the new tokens need processing. Favors swapping to preserve reusable cache.
• Update-mode (vector search): The search algorithm refines its results, replacing documents. [c1, c3, q] becomes [c1, c2, q] – the cached KV pairs for c3 are now wrong. The longest common prefix (LCP) between old and new inputs determines how much cache survives. Favors recomputation to avoid retaining soon-invalid data.

Longest Common Prefix (LCP) invalidation for append-mode and update-mode streaming. Append mode preserves the full prefix; update mode may invalidate significant portions of the KV cache.

The figure above shows the difference concretely. Each row represents the token sequence at a point in time, with blocks showing which KV cache entries survive across updates. In append mode (left), the full prefix is preserved every time a new chunk arrives – the cache grows monotonically and nothing is wasted. In update mode (right), replacing a document in the middle invalidates everything after the longest common prefix. The marked blocks are cached KV pairs that must be discarded because the tokens they correspond to no longer exist in the new input.

A scheduler that treats these uniformly will either waste computation or serve stale cache. Stream2LLM handles both.

A Decoupled Scheduler

Stream2LLM splits the scheduling problem into two independent decisions. It targets the prefill instance in a disaggregated architecture (where prefill and decode run on separate GPU pools). TTFT and throughput are the relevant metrics; decode latency is handled by a separate instance.

The scheduler must answer two questions: which request gets the GPU next, and where do the evicted blocks go? Coupling these decisions makes both worse – fixed eviction rules prevent scheduling algorithms from expressing their priorities.

Two-Phase Scheduling

Stream2LLM separates these concerns into two phases:

Phase 1: Decide who matters most. Rank all unfinished requests by priority and check which ones can fit within the current token budget and GPU block capacity. No memory is allocated – this phase only produces an ordered list.

Phase 2: Make room. Attempt to allocate GPU blocks for the selected requests. If allocation fails, evict the lowest-priority request and use cost-based decisions to choose between recomputation and swapping.

The separation means you can swap in a different scheduling policy without touching the eviction logic, and vice versa.

Stream2LLM system design showing the two-phase scheduling architecture with streaming input support.

On the left, multiple clients stream context chunks into the system concurrently – each request’s input grows over time as retrieval progresses. These streaming inputs feed into the two-phase scheduler at the center.

In Phase 1, the scheduler ranks all active requests by the chosen scheduling policy (FCFS, LCAS, or MCPS) and determines which ones fit within the current token budget and available GPU block capacity. No memory is allocated yet – this phase produces only a priority-ordered list of requests to schedule.

In Phase 2, the scheduler attempts to allocate GPU memory blocks for the selected requests. When the KV cache pool is full, it evicts the lowest-priority request. The eviction decision – recompute from scratch or swap blocks to CPU – is made by the cost-based module on the right, which consults hardware-profiled latency models to pick the cheaper option. Evicted requests re-enter the waiting queue and are reconsidered in the next scheduling cycle.

The key insight is that the arrows between Phase 1 and Phase 2 go in one direction: the priority policy never needs to know about eviction mechanics, and the eviction module never needs to know about scheduling priorities. This decoupling is what makes it possible to swap in different policies without rewriting the memory management logic.

LCP-Based Cache Invalidation

A unique challenge for streaming inputs is that the token sequence itself changes dynamically. When a new chunk arrives, the scheduler must decide which cached KV blocks remain valid. Naive full-invalidation wastes memory and forces expensive recomputation; reusing blocks without verification risks incorrect output based on stale cache.

Stream2LLM computes the longest common prefix (LCP) between the old and new input token sequences – the portion that has not changed. Only KV cache blocks beyond this prefix are invalidated, preserving blocks for unchanged tokens.

For example, suppose a request previously computed KV cache for tokens [c1, c2, q, output1, output2], and an input update replaces this with [c1, c2', q, output1, output2] where c2' != c2. The LCP is [c1] (length 1). The scheduler invalidates cache blocks for tokens 1 onward while preserving the KV cache for token 0.

The LCP approach is optimal when input updates append new chunks or replace suffix tokens – typical in context retrieval.

Cost-Based Preemption

When GPU memory is exhausted, Stream2LLM chooses between recomputing tokens and swapping KV blocks to CPU. Both have hardware-specific costs – recomputing 30K tokens takes ~100ms on H200 but ~1000ms on A40 – so the scheduler profiles both offline on each target GPU and picks the cheaper option at eviction time.

Performance models for recomputation vs. total swap latency costs across token counts on H200 and A40. The scheduler selects the lower-cost strategy at preemption time.

Scheduling Policies

A note on labels used throughout the rest of the post: vLLM-NS is the unmodified vLLM baseline with no streaming, vLLM-S is vLLM with streaming but no custom scheduling, and the Stream2LLM-* variants are streaming combined with each of the custom scheduling policies introduced below.

Stream2LLM implements four scheduling algorithms:

Stream2LLM scheduling policies and their behavior under append-mode and update-mode streaming.

The core principle is to prioritize requests that just received fresh context. LCAS does this directly and handles both modes well. FCFS achieves the strongest results under memory pressure by cleanly separating complete from partial requests. MCPS looks reasonable in theory but fails in practice. It prioritizes by absolute computed token count – requests with the most tokens already processed go first. In append mode, a request that just received a fresh chunk has fewer computed tokens than one that has been processing longer, so fresh content sits idle while nearly-complete requests monopolize the GPU. Under memory pressure, these low-priority fresh-content requests are also the first to be evicted. In update mode it is worse: invalidation resets the computed count to near zero, dropping the request to lowest priority entirely.

Does It Work?

There are no public streaming workload traces. We built two – one for each retrieval pattern – and replayed them at varying queries per second (QPS).

Workload statistics for the vector search (update mode) and crawler (append mode) traces.

The update-mode trace comes from a disk-based approximate nearest neighbor search (ANNS) – a form of vector search – over a 372 GB corpus. The append-mode trace comes from a web crawler fetching pages up to depth 2. Both are high-latency, I/O-bound retrieval scenarios.

The workloads differ sharply in chunk arrival patterns:

Distribution of inter-chunk arrival times. Vector search chunks arrive with a median of 36.7ms; crawler chunks arrive with a median of 700.7ms with significantly higher variability.

Hardware: NVIDIA H200 (141GB) and H100 (80GB) GPUs with Llama-3.1-8B-Instruct, tensor parallelism of 2, and 80% GPU memory utilization target. All experiments target the prefill instance.

Latency: Up to 11x Faster

Each panel below shows what fraction of requests exceed a given TTFT – curves further left mean lower latency. The y-axis is log-scale, so differences at the bottom of each plot reflect tail behavior.

TTFT CCDF across load levels for the crawler (top) and vector search (bottom) workloads on H200. Streaming achieves up to 10.8-11.0x faster median latencies on the crawler workload and 2.49-2.63x P95 speedups on the vector search workload.

Crawler workload (append mode): Streaming improves TTFT at every load level. The gap widens with load: $\sim 4\times$ faster at low QPS, $\sim 11\times$ at high QPS. Scheduler choice matters only when page arrival rate approaches the prefill rate – at QPS 4, FCFS delivers $3.2\times$ P95 speedup over vLLM-S while MCPS degrades to $0.7\times$, deprioritizing requests with fresh content.

Crawler workload: TTFT (average and P95) vs. QPS on H200 across all schedulers.

Vector search workload (update mode): At low load, all streaming schedulers converge near $2.5\times$ P95 speedup. At QPS 2, differentiation emerges: FCFS achieves $2.3\times$, LCAS $1.8\times$, and MCPS drops to $1.5\times$. Despite significant cache invalidation, streaming still delivers $\sim 2\times$ faster TTFT than non-streaming.

vector search workload: TTFT (average and P95) vs. QPS on H200 across all schedulers.

Throughput Is Unaffected

The latency gains raise a natural question: does streaming create overhead that slows total job completion? No. Trace completion times are near-identical across all methods (within ~1%).

Trace completion time across QPS levels for both workloads. All scheduler variants achieve near-identical completion times, confirming throughput parity.

When Memory Runs Out

The H200’s 141 GB is generous enough that preemption never triggers at normal loads. To force the issue, we increased chunk delays ($10\times$ for crawler, $30\times$ for vector search), saturating the KV cache pool. This is where scheduler choice becomes critical. The numbers to watch are the P99 columns – that is where naive streaming collapses.

Speedup values are relative to the non-streaming baseline (first row). Values below 1.0x mean streaming is slower than not streaming.

Crawler workload (append mode, 4.0 QPS, 10x delays): TTFT speedups at P50 and P99 relative to the non-streaming baseline.

Vector search workload (update mode, 2.0 QPS, 30x delays): TTFT speedups at P50 and P99 relative to the non-streaming baseline.

Two key findings:

1. vLLM-S collapses under memory pressure. At P99, it degrades to $0.71\times$ (crawler) and $0.19\times$ (vector search) – streaming without a proper scheduling policy is actively harmful under contention.

2. Eviction strategy is hardware-dependent. Recompute-only FCFS reaches $10.03\times$ at P99 on the crawler workload but swap-only drops to $6.69\times$. The cost-based approach adapts to the hardware, achieving $8.62\times$ (FCFS) and $9.14\times$ (LCAS) by picking the cheaper option at each eviction.

What This Means

If you serve LLM requests backed by retrieval – web crawling, vector search, tool calls – you are paying a latency tax every time you wait for complete context before starting prefill.

Three takeaways:

1. Start prefilling on partial context. Median TTFT improves 4-11x for append-mode workloads. If your retrieval takes more than a second, this dominates every other optimization you could make.
2. Do not stream without a proper scheduling policy. vLLM-S under memory pressure produces P99 latencies 5x worse than not streaming. Use FCFS or LCAS.
3. Profile your eviction costs. Whether to recompute or swap depends on your GPU. A five-minute offline profile determines the right strategy.

The system, the traces, and the evaluation code are all public.

Paper: Stream2LLM (MLSys 2026)

Code: github.com/rajveerb/stream2llm

Data: HuggingFace: rbachkaniwala3/stream2llm-data

DOI: 10.5281/zenodo.18906769