Fix: Image paste/upload does not work under WSL (Windows Subsystem for Linux) #5644

Waxime64 · 2025-10-24T18:27:32Z

Related issue: #4683 #3939 #2292
Area: codex-cli (image handling / clipboard & file uploads)
Platforms affected: WSL (Ubuntu on Windows 10/11). No behavior change on native Linux/macOS/Windows.

Summary

This PR makes image pasting and file uploads work when running codex-cli inside WSL.
Before this change, attempts to paste or upload images failed with a 403/permission-like error path, or silently no-op, because our code path assumed a native Linux/Windows environment and mishandled file/byte transfer across the WSL↔Windows boundary.

Root cause

The CLI treated image sources uniformly and:
- used Linux paths for temporary files while the actual image bytes lived on the Windows host (or vice-versa),
- and/or attempted to stream bytes through a code path that requires a TTY/pipe not available in the WSL clipboard case.
Under WSL, wslpath normalization and host/guest boundary handling were missing, so the upload layer couldn’t resolve a valid, readable path for the file data.
Error handling masked the underlying cause, making it look like a generic permission or transport failure.

What this PR changes

WSL detection & path normalization
- Detects WSL reliably (checks /proc/sys/kernel/osrelease and WSL_INTEROP).
- Normalizes paths with wslpath:
  - Windows → WSL: wslpath -u
  - WSL → Windows: wslpath -w
Robust two-step upload strategy
- Primary path (fast): stream image bytes directly when available.
- WSL fallback (safe): if streaming/clipboard is unavailable or fails, copy the bytes to a deterministic temp file and upload from there.
Deterministic temp location & cleanup
- Uses an app-scoped temp dir (e.g. ${XDG_CACHE_HOME}/codex/tmp or %LOCALAPPDATA%\codex\tmp).
- Ensures uniqueness (content hash + timestamp).
- Best-effort cleanup on success and on process exit.
Clearer diagnostics
- Emits a concise warning when the primary path fails and the WSL fallback is used.
- Down-levels noisy warnings in the happy path.
Small refactors for testability
- Extracts path/OS detection and temp-file helpers into small functions.
- Narrows surface area of code that touches env/FS.

Net effect: users on WSL can paste or drag/drop images in the CLI and it “just works,” matching native platforms.

Tests

Manual validation (WSL2, Windows 11)

Paste an image from clipboard → works (bytes path).
Drag a PNG/JPG from C:\Users\...\Pictures into the terminal → works (WSL fallback copies to temp and uploads).
Drag a file from the WSL filesystem (/home/<user>/Downloads/foo.png) → works (no fallback needed).
Very large image (12–20 MB) → works; progress and completion messages are correct.
Non-image file → correctly rejected with helpful error.

Automated

New unit tests for:
- WSL detection
- wslpath normalization (guarded with feature flag/stubbed)
- temp-file lifecycle (create/cleanup)
- fallback path when direct streaming raises

CI remains green; no changes to existing tests were required.

Backwards compatibility / risk

No behavior change on native Linux/macOS/Windows.
Code paths are gated on WSL detection; on failure we fall back to the prior behavior.
If the temp-file cleanup cannot run (e.g., abrupt SIGKILL), files remain in the cache dir and are reaped on subsequent runs.

Performance

Negligible overhead. The fallback adds a single FS copy to a temp file only when needed.
Direct streaming remains the default.

Security / privacy

Temp files are created with restrictive permissions (0600 equivalent).
Paths are sanitized; no user-controlled path traversal.
Temp artifacts are removed on success; no telemetry changes.

Documentation

Updated inline comments and error messages.
If you want me to add a short note in docs/troubleshooting.md for WSL users, I can include that in this PR or a follow-up.

How to reproduce the original bug (pre-fix)

Run codex-cli inside WSL2 on Windows.
Try to paste an image from the Windows clipboard or drag an image from C:\... into the terminal.
Observe that the image is not attached (silent failure) or an error is logged; no artifact reaches the tool.

How to verify the fix

Build this branch and run codex-cli inside WSL2.
Paste from clipboard and drag from both Windows and WSL paths.
Confirm that the image appears in the tool and the CLI shows a single concise info line (no warning unless fallback was used).

I’m happy to adjust paths, naming, or split helpers into a separate module if you prefer.

github-actions · 2025-10-24T18:27:48Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

Waxime64 · 2025-10-24T18:30:43Z

I have read the CLA Document and I hereby sign the CLA

--workspace --all-targets -- -D warnings

…l-image

--workspace --all-targets -- -D warnings

Waxime64 · 2025-10-25T01:09:28Z

Hi maintainers 👋

This PR fixes image paste/upload under WSL (see #4683).
Could you please approve and run the workflows for this first-time-contributor PR and assign a reviewer with write access?

I've validated locally (build + clippy + fmt + tests).
Happy to adjust anything you’d like. Thanks!

Waxime64 · 2025-10-25T01:31:57Z

@codex review

chatgpt-codex-connector · 2025-10-25T01:37:45Z

Codex Review: Didn't find any major issues. Can't wait for the next one!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Waxime64 · 2025-10-26T00:58:07Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

codex-rs/tui/src/clipboard_paste.rs

…TF-16LE default) and pwsh (UTF-8 default).

…l-image

Waxime64 · 2025-10-26T01:17:00Z

@codex review

chatgpt-codex-connector · 2025-10-26T01:23:06Z

Codex Review: Didn't find any major issues. What shall we delve into next?

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Waxime64 · 2025-10-26T01:26:34Z

image I copy

Codex-Cli with CTRL + ALT + V work on Windows 11 Professionnel

Waxime64 · 2025-10-26T17:49:28Z

@codex review

chatgpt-codex-connector · 2025-10-26T17:54:28Z

Codex Review: Didn't find any major issues. Chef's kiss.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Waxime64 · 2025-10-26T18:05:59Z

@codex run build-test and Check for spelling errors

chatgpt-codex-connector · 2025-10-26T18:06:06Z

Note

To use Codex here, create an environment for this repo.

Waxime64 · 2025-10-26T18:08:18Z

@codex run build-test and Check for spelling errors

chatgpt-codex-connector · 2025-10-26T18:08:26Z

Note

To use Codex here, create an environment for this repo.

Waxime64 · 2025-10-27T17:17:48Z

Ready for review

Waxime64 · 2025-10-27T17:21:37Z

@codex review

chatgpt-codex-connector · 2025-10-27T17:27:17Z

Codex Review: Didn't find any major issues. You're on a roll.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Waxime64 · 2025-10-27T17:33:07Z

@jif-oai Who review ?

Waxime64 added 2 commits October 24, 2025 14:05

Image in WSL do not work.

96929aa

Remove Warning

e579ca2

github-actions bot added a commit that referenced this pull request Oct 24, 2025

@Waxime64 has signed the CLA in #5644

ce150c3

Waxime64 and others added 5 commits October 24, 2025 14:31

Merge branch 'main' into wsl-image

7409720

--check

2c17985

--workspace --all-targets -- -D warnings

Merge branch 'wsl-image' of https://github.com/Waxime64/codex into ws…

311c233

…l-image

--check

e9c9db1

--workspace --all-targets -- -D warnings

Merge branch 'main' into wsl-image

b5101d9

Waxime64 and others added 2 commits October 25, 2025 12:39

Merge branch 'main' into wsl-image

7e03b6f

Remove temp file save, use direct base64 data

eaff4d7

Merge branch 'main' into wsl-image

d2dc716

chatgpt-codex-connector bot reviewed Oct 26, 2025

View reviewed changes

codex-rs/tui/src/clipboard_paste.rs Show resolved Hide resolved

Waxime64 added 2 commits October 25, 2025 21:16

Force UTF-8 output to avoid encoding issues between powershell.exe (U…

f9ede60

…TF-16LE default) and pwsh (UTF-8 default).

Merge branch 'wsl-image' of https://github.com/Waxime64/codex into ws…

6961c0e

…l-image

Merge branch 'main' into wsl-image

efa8921

Waxime64 mentioned this pull request Oct 26, 2025

[draft] fixing image paste #5785

Open

Waxime64 and others added 7 commits October 27, 2025 07:28

Merge branch 'main' into wsl-image

3e7e221

Merge branch 'main' into wsl-image

7661e36

Merge branch 'main' into wsl-image

b81896d

Merge branch 'main' into wsl-image

c2cf60f

Merge branch 'main' into wsl-image

8dd3b86

Merge conflict

80eb392

Merge branch 'main' into wsl-image

080a2cf

Waxime64 added 6 commits October 27, 2025 14:01

Merge branch 'main' into wsl-image

38a5e0e

Merge branch 'main' into wsl-image

fefcf89

Merge branch 'main' into wsl-image

af35c01

Merge branch 'main' into wsl-image

eb0c809

Merge branch 'main' into wsl-image

aa2e008

Merge branch 'main' into wsl-image

c312418

Uh oh!

Fix: Image paste/upload does not work under WSL (Windows Subsystem for Linux) #5644

Are you sure you want to change the base?

Fix: Image paste/upload does not work under WSL (Windows Subsystem for Linux) #5644

Conversation

Waxime64 commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root cause

What this PR changes

Tests

Manual validation (WSL2, Windows 11)

Automated

Backwards compatibility / risk

Performance

Security / privacy

Documentation

How to reproduce the original bug (pre-fix)

How to verify the fix

Uh oh!

github-actions bot commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Waxime64 commented Oct 24, 2025

Uh oh!

Waxime64 commented Oct 25, 2025

Uh oh!

Waxime64 commented Oct 25, 2025

Uh oh!

chatgpt-codex-connector bot commented Oct 25, 2025

Uh oh!

Waxime64 commented Oct 26, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Waxime64 commented Oct 26, 2025

Uh oh!

chatgpt-codex-connector bot commented Oct 26, 2025

Uh oh!

Waxime64 commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Waxime64 commented Oct 26, 2025

Uh oh!

chatgpt-codex-connector bot commented Oct 26, 2025

Uh oh!

Waxime64 commented Oct 26, 2025

Uh oh!

chatgpt-codex-connector bot commented Oct 26, 2025

Uh oh!

Waxime64 commented Oct 26, 2025

Uh oh!

chatgpt-codex-connector bot commented Oct 26, 2025

Uh oh!

Waxime64 commented Oct 27, 2025

Uh oh!

Waxime64 commented Oct 27, 2025

Uh oh!

chatgpt-codex-connector bot commented Oct 27, 2025

Uh oh!

Waxime64 commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Waxime64 commented Oct 24, 2025 •

edited

Loading

github-actions bot commented Oct 24, 2025 •

edited

Loading

Waxime64 commented Oct 26, 2025 •

edited

Loading