From 98e51c7e731e001bf2db1988536caad3aa65a0bf Mon Sep 17 00:00:00 2001
From: canvrno-oai <kbond@openai.com>
Date: Fri, 17 Apr 2026 11:56:08 -0700
Subject: [PATCH] fix(tui): clarify windows image paste shortcut

---
 codex-rs/tui/src/bottom_pane/footer.rs | 15 ++++++++++++---
 codex-rs/tui/src/chatwidget.rs         |  7 ++++++-
 codex-rs/tui/tooltips.txt              |  2 +-
 3 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/codex-rs/tui/src/bottom_pane/footer.rs b/codex-rs/tui/src/bottom_pane/footer.rs
index 958f5c2ead..918030f1ce 100644
--- a/codex-rs/tui/src/bottom_pane/footer.rs
+++ b/codex-rs/tui/src/bottom_pane/footer.rs
@@ -903,6 +903,7 @@ enum DisplayCondition {
     WhenShiftEnterHint,
     WhenNotShiftEnterHint,
     WhenUnderWSL,
+    WhenNativeWindows,
     WhenCollaborationModesEnabled,
 }
 
@@ -913,6 +914,7 @@ impl DisplayCondition {
             DisplayCondition::WhenShiftEnterHint => state.use_shift_enter_hint,
             DisplayCondition::WhenNotShiftEnterHint => !state.use_shift_enter_hint,
             DisplayCondition::WhenUnderWSL => state.is_wsl,
+            DisplayCondition::WhenNativeWindows => cfg!(target_os = "windows") && !state.is_wsl,
             DisplayCondition::WhenCollaborationModesEnabled => state.collaboration_modes_enabled,
         }
     }
@@ -1005,13 +1007,18 @@ const SHORTCUTS: &[ShortcutDescriptor] = &[
     },
     ShortcutDescriptor {
         id: ShortcutId::PasteImage,
-        // Show Ctrl+Alt+V when running under WSL (terminals often intercept plain
-        // Ctrl+V); otherwise fall back to Ctrl+V.
+        // Show Ctrl+Alt+V when running under WSL, Alt+V on native Windows, and
+        // Ctrl+V elsewhere. Windows terminals often intercept plain Ctrl+V
+        // before the TUI sees it.
         bindings: &[
             ShortcutBinding {
                 key: key_hint::ctrl_alt(KeyCode::Char('v')),
                 condition: DisplayCondition::WhenUnderWSL,
             },
+            ShortcutBinding {
+                key: key_hint::alt(KeyCode::Char('v')),
+                condition: DisplayCondition::WhenNativeWindows,
+            },
             ShortcutBinding {
                 key: key_hint::ctrl(KeyCode::Char('v')),
                 condition: DisplayCondition::Always,
@@ -1735,7 +1742,7 @@ mod tests {
     }
 
     #[test]
-    fn paste_image_shortcut_prefers_ctrl_alt_v_under_wsl() {
+    fn paste_image_shortcut_uses_platform_specific_binding() {
         let descriptor = SHORTCUTS
             .iter()
             .find(|descriptor| descriptor.id == ShortcutId::PasteImage)
@@ -1754,6 +1761,8 @@ mod tests {
 
         let expected_key = if is_wsl {
             key_hint::ctrl_alt(KeyCode::Char('v'))
+        } else if cfg!(target_os = "windows") {
+            key_hint::alt(KeyCode::Char('v'))
         } else {
             key_hint::ctrl(KeyCode::Char('v'))
         };
diff --git a/codex-rs/tui/src/chatwidget.rs b/codex-rs/tui/src/chatwidget.rs
index 260691b3c6..e310e5d594 100644
--- a/codex-rs/tui/src/chatwidget.rs
+++ b/codex-rs/tui/src/chatwidget.rs
@@ -5062,8 +5062,13 @@ impl ChatWidget {
                     }
                     Err(err) => {
                         tracing::warn!("failed to paste image: {err}");
+                        #[cfg(target_os = "windows")]
+                        let guidance = "If you're on Windows, try Alt+V first; some terminals intercept Ctrl+V. If that still fails, save the image to a file and paste the file path instead.";
+                        #[cfg(not(target_os = "windows"))]
+                        let guidance =
+                            "Try saving the image to a file and paste the file path instead.";
                         self.add_to_history(history_cell::new_error_event(format!(
-                            "Failed to paste image: {err}",
+                            "Failed to paste image: {err}. {guidance}",
                         )));
                     }
                 }
diff --git a/codex-rs/tui/tooltips.txt b/codex-rs/tui/tooltips.txt
index 7bb91d5ba6..dc5d20af24 100644
--- a/codex-rs/tui/tooltips.txt
+++ b/codex-rs/tui/tooltips.txt
@@ -20,6 +20,6 @@ You can run any shell command from Codex using `!` (e.g. `!ls`)
 Type / to open the command popup; Tab autocompletes slash commands.
 When the composer is empty, press Esc to step back and edit your last message; Enter confirms.
 Press Tab to queue a message when a task is running; otherwise it sends immediately (except `!`).
-Paste an image with Ctrl+V to attach it to your next message.
+Paste an image with Ctrl+V to attach it to your next message. On Windows, try Alt+V if Ctrl+V is intercepted.
 You can resume a previous conversation by running `codex resume`
 Use /copy or press Ctrl+O to copy the latest agent response as Markdown.