Terminal Image Paste
Paste clipboard images into coding-agent terminals as project-local file paths.
Install from the Marketplace
- Open the Extensions view in the local desktop VS Code window that owns your clipboard.
- Search for Terminal Image Paste by Alloy from publisher Alloy Systems (
alloycx).
- Select
alloycx.terminal-screenshot-paste, then choose Install.
For Remote-SSH, install and enable the extension on the Local/UI side, not on the remote host. Linux clipboard helpers are also required on the desktop UI machine where VS Code runs. Screenshot files are still written to the selected remote workspace through VS Code.
Behavior
With an integrated terminal focused, press Ctrl+V on Windows/Linux or Cmd+V on macOS. While the intercepted paste is pending, an animated Pasting… indicator appears in the VS Code status bar. Plain text uses VS Code's normal terminal paste. A clipboard image is saved in the selected workspace, and its absolute path is sent directly to the terminal that received the shortcut without pressing Enter. A successful image paste leaves the clipboard unchanged. The paste flow does not open or focus Explorer, so it preserves the current workbench layout. Successful image and plain-text pastes do not show notifications.
The screenshot directory is selected in this order:
- use an existing
<workspace-root>/.docs/screenshots directory;
- if
<workspace-root>/.alloy exists as a directory, use or create .alloy/screenshots inside it;
- otherwise use or create
<workspace-root>/.screenshots.
Owned files use canonical names such as terminal-image-paste_2026-09-22T14-30-52.123Z_550e8400-e29b-41d4-a716-446655440000.png. The extension may delete an owned screenshot only after both its embedded timestamp and filesystem modification time are older than seven full 24-hour days. Owned temporary files use their modification time. Legacy Screenshot_N.* files, README.md, malformed names, and unrelated files are preserved. A managed-directory README explains the policy when the extension creates it; an existing README is never overwritten.
The extension registers its paste command with VS Code's terminal keybinding dispatcher. A standard installation does not require a manual settings.json change. If an explicit user or workspace setting overrides interception, the extension shows an action that repairs only the conflicting terminal settings after confirmation.
The deepest matching workspace root is selected from the active terminal's current working directory. A single open root is the fallback; ambiguous multi-root workspaces prompt for a root.
Requirements
- VS Code 1.93 or newer on Windows, macOS, or Linux desktop.
- A trusted local or Remote-SSH workspace.
- Linux Wayland:
wl-paste from the wl-clipboard package.
- Linux X11:
xclip.
Linux installation examples
sudo apt install wl-clipboard
sudo apt install xclip
Install the package appropriate for the active Wayland or X11 session.
The extension checks for these helpers on the local Linux UI machine. If neither is installed, an actionable notification offers to open a dedicated terminal with the detected package-manager command already inserted. The command is not executed until Enter is pressed. A second action copies the exact command, and remains available if the terminal cannot be opened.
The extension never runs a package manager or sudo silently. In a Remote-SSH window on a Linux desktop, it offers only Copy Install Command because the public terminal API cannot guarantee that a newly created terminal is local. Run the copied command in a local desktop terminal; the extension never inserts it into the active remote coding-agent terminal.
Install from a VSIX (fallback)
Use a VSIX only for development or recovery when Marketplace installation is unavailable:
- Open the local desktop VS Code window that owns your clipboard.
- Run Extensions: Install from VSIX... from the Command Palette.
- Select the
terminal-image-paste-<version>.vsix file and restart VS Code when prompted.
Privacy
The extension reads the clipboard only when its terminal paste command runs. It performs no uploads, network requests, telemetry, or background clipboard monitoring.
Troubleshooting
- If no workspace matches the terminal directory, select the intended root when prompted.
- If Linux image paste reports a missing helper, use Open Install Terminal or Copy Install Command in the notification, then restart VS Code after installation.
- If terminal settings explicitly send all keybindings to the shell, use Enable Terminal Paste Interception in the warning notification.
- If direct terminal insertion is unavailable after saving, the extension copies the safe path to the clipboard and asks you to paste it manually. A successful automatic insertion does not replace clipboard content.
Engineering Documentation
Contributors should start with the project documentation index.
