Codex TUI should support image paste via Cmd-V / terminal paste, not only Ctrl-V

Current clipboard-image paste is handled by an explicit v shortcut path with Ctrl/Alt modifiers: the TUI advertises Ctrl+V and, under WSL, Ctrl+Alt+V; that path calls paste_image_to_temp_png() and attaches the PNG. Terminal paste events currently arrive as crossterm::Event::Paste(String) / TuiEvent::Paste(String), so the normal paste path only receives text before passing it to ChatComposer::handle_paste. On macOS/iTerm2, Cmd+V behaves like the terminal paste action for text, so clipboard images do not hit the image-read path today. Supporting this likely needs either a Super/Meta key path or an explicit clipboard-image check from the paste path. The keymap config also only accepts ctrl / alt / shift modifiers today, so cmd-v / meta-v is not configurable.

🔧 Proposed Solution

Root Cause

The TUI's image paste handler is bound to Ctrl-V only, while text paste uses the terminal's native paste mechanism (which responds to Cmd-V). On macOS, Cmd-V is the standard paste gesture, making Ctrl-V for images confusing and undiscoverable.

The issue is that terminal applications on macOS cannot directly intercept Cmd-V because the terminal emulator consumes them first.

Fix

1. Add Cmd-V handling via terminal key sequence (meta+v) in the input handler
2. Enable bracketed paste mode for better paste data handling
3. Add clipboard image detection on paste — check clipboard for image data regardless of key combination
4. Add visual hint when clipboard contains an image
5. Update help text to document both Cmd-V and Ctrl-V for image paste

Files to Modify

• src/tui/input-handler.ts — Add Cmd-V + bracketed paste handling
• src/tui/terminal-setup.ts — Enable bracketed paste mode
• src/tui/prompt-hints.ts — Add visual hints for image paste
• src/tui/help-overlay.ts — Update help text

Complexity: Medium (3-5 hours, macOS-specific)

Full solution document: codex-24322-tui-image-paste-cmdv-fix.md

Adding another macOS data point for the screenshot-to-clipboard workflow.

Environment:

• Codex CLI: codex-cli 0.133.0
• Platform: macOS
• Terminal: VS Code integrated terminal (TERM_PROGRAM=vscode, TERM=xterm-256color)

Workflow that currently feels broken:

1. Take a screenshot to the clipboard with macOS, e.g. Control + Shift + Command + 4.
2. Return to an active Codex TUI session.
3. Press Command + V, expecting the screenshot image to be attached.

Observed:

• The clipboard image is not attached/pasted into the Codex session.
• Drag-and-drop of an image file works, so the image/model side is fine.
• Workarounds like saving via pngpaste and then attaching a file path work, but they are much slower for screenshot-heavy UI debugging.

Expected:

• Codex should support pasting clipboard screenshots/images directly in-session on macOS, matching the normal macOS paste gesture where possible.
• If terminal limitations prevent Command + V from carrying image data, the TUI should expose a clear in-session shortcut or command such as "attach clipboard image" that saves the pasteboard image to a temp file and attaches it automatically.
• A visible hint when the clipboard contains an image would also help discoverability.

This is especially noticeable because Claude Code handles this workflow more ergonomically, while Codex already supports adjacent flows like drag-and-drop and -i/--image file attachment.

Still reproducible with codex-cli 0.147.0 on macOS 26.5.2 in tmux 3.7c. Cmd+V does not attach a screenshot copied to the clipboard in an active TUI session.

-i/--image only helps when starting a session, so it does not replace the screenshot-heavy in-session workflow. Claude Code supports this workflow directly.

Please support native Cmd+V where the terminal allows it, or provide a discoverable in-session "attach clipboard image" command and hint.

Update: confirmed working with codex-cli 0.148.0 on macOS 26.5.2 in tmux 3.7c. Clipboard images attach successfully in an active TUI session using Ctrl+V. The remaining request is discoverability and native Cmd+V support on macOS.