Codex Smart Image Paste
Use the normal macOS Cmd+V shortcut to paste clipboard images into Codex CLI
when it is running in the active VS Code integrated terminal.
No alternate paste shortcut. No permanent terminal-wide remapping. Native paste
continues to work everywhere else.
Why this extension exists
Codex CLI accepts clipboard images with Ctrl+V. In a macOS terminal, users
naturally expect Cmd+V. A global VS Code keybinding can translate the shortcut,
but it also breaks normal text paste in ordinary zsh terminals.
This extension watches VS Code terminal shell execution events and enables the
translation only while the active terminal is running Codex.
Behavior
| Context |
Cmd+V behavior |
| VS Code editor |
Native paste |
| Regular integrated terminal |
Native text paste |
| Active Codex terminal, image clipboard |
Codex clipboard-image paste |
| Active Codex terminal, text clipboard |
Native text paste |
| Another terminal while Codex runs elsewhere |
Native text paste |
| Same terminal after Codex exits |
Native text paste |
When smart paste is active, the status bar displays Codex: smart ⌘V.
The extension checks the macOS clipboard type on every paste. It sends Ctrl+V
to Codex only when an image format is present; ordinary text is delegated to VS
Code's native terminal paste command. If clipboard inspection fails, it safely
falls back to native paste.
Requirements
- macOS
- VS Code 1.93 or newer
- Codex CLI
- VS Code terminal shell integration enabled for the shell that launches Codex
VS Code enables shell integration for supported zsh terminals by default.
Installation
VS Code Marketplace
Search for Codex Smart Image Paste in the Extensions view after it is
published.
Install a VSIX
- Open the Command Palette with
Cmd+Shift+P.
- Run Extensions: Install from VSIX....
- Select the packaged
.vsix file.
- Run Developer: Reload Window.
Usage
- Open a new VS Code integrated terminal.
- Run
codex normally.
- Copy a screenshot or image to the macOS clipboard.
- Press
Cmd+V in the Codex composer.
- Copy some text and press
Cmd+V in the same Codex session to verify native
text paste still works.
- Exit Codex. The terminal remains on VS Code's native paste behavior.
Settings
Custom launch commands
codexSmartImagePaste.commandPattern controls how Codex launches are detected.
The default recognizes codex, absolute paths to codex, environment variable
assignments, and common env, sudo, or command prefixes.
If an alias named cx launches Codex:
{
"codexSmartImagePaste.commandPattern": "^cx(?:\\s|$)"
}
Status bar
Disable the status indicator with:
{
"codexSmartImagePaste.showStatusBar": false
}
Troubleshooting
If Codex is not detected, confirm that shell integration is enabled:
{
"terminal.integrated.shellIntegration.enabled": true
}
Then open a new terminal and launch Codex again. If the extension was installed
while Codex was already running, exit and relaunch Codex so the start event can
be observed.
Commands launched inside tmux may not be reported as Codex by VS Code shell
integration.
Documentation
License
MIT
