›_ Codex Issues
Codex Issues / #10523

macOS: image paste shortcut documented as Ctrl+V (Windows behavior) — should support/document ⌘+V (Command+V)

Open 💬 6 comments Opened Feb 3, 2026 by canyangliunian
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What version of Codex is running?

codex-cli 0.94.0

What subscription do you have?

plus

Which model were you using?

_No response_

What platform is your computer?

Darwin 24.6.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

_No response_

What issue are you seeing?

In issue #2730, it’s mentioned that images can be pasted via Ctrl+V. This matches Windows/Linux clipboard conventions, but on macOS the standard paste shortcut is ⌘+V (Command+V). The current wording is misleading for macOS users: I initially thought Codex did not support image pasting at all and that the only way to include an image in context was via file path.

What steps can reproduce the bug?

  1. Platform: macOS, Codex: [codex-cli ].
  2. Copy an image to the clipboard (e.g., take a screenshot with ⌘+Shift+4, or copy an image from a browser).
  3. Focus the Codex input field (the interactive chat prompt).
  4. Press ⌘+V (Command+V) to paste.
  5. Actual: [describe what happens: nothing happens /only text is pasted / an empty placeholder appears / it only works with Ctrl+V / etc.].
  6. Expected: On macOS, image paste should work with ⌘+V. If the intended shortcut differs, the docs/UI should clearly state platform-specific shortcuts (Windows/Linux: Ctrl+V; macOS: ⌘+V).

What is the expected behavior?

• On macOS, pasting an image from clipboard should work with ⌘+V, consistent with system conventions; and/or
• Documentation/UI hints should clearly distinguish shortcuts per platform (e.g., “Windows/Linux: Ctrl+V; macOS: ⌘+V”), including any prerequisites.

Additional information

Why this matters
This is a discoverability/usability issue: macOS users may incorrectly believe image paste is unsupported and fall back to path-based workflows. If ⌘+V already works, this is a docs/UI hint bug; if not, it’s a platform shortcut/clipboard handling bug.

Proposed fix
• Update docs/tooltips to show platform-specific paste shortcuts.
• Ensure macOS clipboard image paste is supported via ⌘+V (or document required conditions if there are any).

View original on GitHub ↗

6 Comments

jordanmiguel · 4 months ago

Pasting images is broken on macOS.

etraut-openai contributor · 4 months ago

@jordanmiguel, does ctrl-V not work for you? If not, please file a new bug report. This bug report is about documentation, not the product.

alxsthrlnd · 4 months ago

Reproduced on a newer CLI build with a concrete terminal-specific data point.

Environment:

  • Codex CLI: codex-cli 0.111.0
  • Subscription: Pro
  • Model: gpt-5.4
  • Platform: Darwin 25.3.0 arm64 arm
  • Terminal: Hyper 3.4.1
  • TERM=xterm-256color
  • No tmux / zellij

Observed behavior:

  • In the Codex CLI TUI on macOS inside Hyper, Cmd+V does not attach a clipboard image.
  • In the same environment, Ctrl+V does attach the clipboard image successfully.
  • On the same machine and in the same Hyper terminal app, Claude Code accepts Cmd+V for clipboard-image paste as expected.

Why this seems Codex-specific rather than terminal-global:

  • Codex CLI docs currently say images can be pasted into the interactive composer.
  • Codex on this machine has previously created codex-clipboard-*.png attachments, so clipboard-image ingestion exists.
  • Hyper has no custom keymap override here; the mismatch is specifically Cmd+V in Codex vs Cmd+V working in Claude Code.

Expected:

  • On macOS, normal paste (Cmd+V) should attach the clipboard image in the Codex CLI TUI.
  • If platform-specific shortcuts are still required internally, the docs/UI should state them explicitly per platform.
s1korrrr · 4 months ago

I prepared a fix for this on a public fork branch:

Root cause: the footer shortcut descriptor only exposed the WSL-specific Ctrl+Alt+V binding and a generic Ctrl+V fallback, and the key-hint renderer had no explicit SUPER / Command-key display support. On macOS that leaves users with Windows-style guidance for image paste.

Fix summary: add SUPER / Command rendering support and a super_() helper in both TUI frontends, then update the PasteImage shortcut descriptor to prefer ⌘+V on macOS while keeping Ctrl+Alt+V under WSL and Ctrl+V elsewhere. The footer test is updated in both frontends to assert the platform-specific binding.

Validation:

  • just fix -p codex-tui
  • just fix -p codex-tui-app-server
  • cargo test -p codex-tui paste_image_shortcut_prefers_platform_specific_binding
  • cargo test -p codex-tui-app-server paste_image_shortcut_prefers_platform_specific_binding
  • ./tools/argument-comment-lint/run.sh

I tried to open a PR, but GitHub rejected PR creation because openai/codex currently reports pull_request_creation_policy: collaborators_only. If a maintainer wants this as an invited PR, I can open it immediately from the branch above.

hqhq1025 · 3 months ago

For macOS users: the Cmd+V issue can be fixed with clipaste.

The root cause is that macOS screenshots put only raw image data on the clipboard — no file URL. Terminals like Ghostty can only Cmd+V paste text/file URLs, so there's nothing to paste. clipaste is a background daemon that auto-saves screenshot images to temp files and registers the file path, making both Cmd+V and Ctrl+V work.

brew install hqhq1025/clipaste/clipaste
brew services start clipaste

Tested with Codex CLI + Ghostty 1.3.1.

elizhabiboullah · 3 months ago

@etraut-openai

I investigated this locally and prepared a tested fix on my fork.

What I found:

  • On macOS, text paste via Cmd+V works, but clipboard images do not

attach.

  • In the TUI, image paste is currently wired to Ctrl+V / Alt+V, not the

normal macOS Cmd+V path.

  • This matches the reports here that Ctrl+V works while Cmd+V does

nothing.

Proposed fix:

  • Treat Cmd+V on macOS as an image-paste shortcut using the existing

clipboard image path.

  • Update the footer/key hint to show ⌘ + v on macOS.
  • Keep existing Ctrl+Alt+V behavior under WSL and Ctrl+V elsewhere.

I implemented this on my fork:

  • Branch: elizhabiboullah:fix/macos-cmd-v-image-paste
  • Commit: f0b2e11fd

Local validation:

  • `CARGO_INCREMENTAL=0 ~/.cargo/bin/cargo test -j 1 -p codex-tui

image_paste_shortcut -- --nocapture`

  • `CARGO_INCREMENTAL=0 ~/.cargo/bin/cargo test -j 1 -p codex-tui

paste_image_shortcut_prefers_ctrl_alt_v_under_wsl -- --nocapture`

-
chatwidget::tests::image_paste_shortcut_keeps_ctrl_v_and_adds_cmd_v_on_mac
os
-
chatwidget::tests::image_paste_shortcut_attaches_returned_clipboard_image
-
bottom_pane::footer::tests::paste_image_shortcut_prefers_ctrl_alt_v_under_
wsl

If this approach aligns with the intended direction, I’d be happy to open a PR if invited.