BatthewZ Terminal Image Paste

Built for WSL2, Linux, MacOS and Windows.

Paste clipboard images or copy/paste files into your VS Code terminal as file paths. Designed for CLI tools like Claude Code that accept image paths as input.

Copy a screenshot, press Ctrl+Alt+V, and the image is saved to your workspace with the path inserted at your terminal cursor — ready to send.

Features

• Clipboard paste — Press Ctrl+Alt+V (Cmd+Alt+V on macOS) to save a clipboard image and insert its path into the active terminal
• File paste — Copy an image file in your OS file manager, press Ctrl+Alt+V, and the file path is inserted into the terminal (works on all platforms)
• Explorer context menu — Right-click any image file and select "Send Image Path to Terminal"
• Multi-format support — Reads PNG, JPEG, GIF, BMP, WebP, and TIFF from the clipboard; auto-detects format. On macOS, WebP is not detected; on Windows/WSL, images are always read as PNG
• Format conversion — Optionally convert all images to PNG or JPEG on save
• Configurable filenames — Use patterns with {timestamp}, {date}, {time}, {n}, {hash} placeholdersd
• Folder organization — Store images flat, or in daily/monthly subdirectories
• Auto-cleanup — Oldest images are automatically deleted when the count exceeds maxImages
• Auto .gitignore — The image folder is added to .gitignore on first save
• Image preview — Optionally preview clipboard images before saving (opt-in, 10-second auto-cancel)
• Shell-aware quoting — Paths are quoted correctly for bash, zsh, fish, PowerShell, and cmd
• Remote terminal awareness — Warns when pasting in SSH/container terminals where local paths may not be accessible
• Diagnostic debug mode — Run "Show Diagnostics" to inspect platform, clipboard, storage, and terminal state
• Public extension API — Other extensions can call pasteFromClipboard(), sendPathToTerminal(), and subscribe to onImagePasted

Getting Started

Install

Search for BatthewZ Terminal Image Paste in the VS Code Extensions panel, or install from the command line:

code --install-extension BatthewZTools.batthewz-terminal-image-paste

Platform Prerequisites

The extension uses native clipboard tools to read image data. Most platforms work out of the box — macOS and Linux need a small install:

On macOS, osascript is used as a fallback if pngpaste is unavailable. On WSL2 with WSLg, native Linux tools (xclip/wl-paste) are preferred with PowerShell as fallback. On Linux, the extension tries both X11 and Wayland tools with automatic fallback.

The extension checks for the required tool on startup and shows a warning if it's missing.

Usage

Paste a Clipboard Image

1. Copy an image to your clipboard (screenshot, right-click "Copy image", etc.) — or copy an image file in your OS file manager
2. Focus a VS Code terminal
3. Press Ctrl+Alt+V (macOS: Cmd+Alt+V)

The image is saved to your workspace and the quoted file path appears at your terminal cursor. By default no newline is sent, so you can append additional text before pressing Enter.

Example with Claude Code:

> '/home/you/project/.tip-images/img-2026-02-27T14-30-45-123.png' what does this diagram show?

Send an Existing Image

Right-click any image file (PNG, JPG, JPEG, GIF, BMP, WebP, SVG) in the VS Code Explorer and select Send Image Path to Terminal. The quoted path is inserted into the active terminal.

Commands

All commands are available from the Command Palette (Ctrl+Shift+P).

Configuration

All settings live under the terminalImgPaste namespace. Open Settings and search for "Terminal Image Paste", or edit settings.json directly:

Filename Pattern Placeholders

If the pattern contains no uniqueness placeholder ({timestamp}, {n}, or {hash}), a timestamp is appended automatically to prevent filename collisions.

Extension API

Other VS Code extensions can consume the Terminal Image Paste API:

const tipExtension = vscode.extensions.getExtension(
  "BatthewZTools.batthewz-terminal-image-paste",
);
const api = tipExtension?.exports;

if (api) {
  // Paste from clipboard and get the saved path
  const result = await api.pasteFromClipboard();
  if (result) {
    console.log(`Saved to: ${result.path} (${result.format})`);
  }

  // Send a path to the active terminal
  api.sendPathToTerminal("/path/to/image.png");

  // Get the image storage folder
  const folder = api.getImageFolder();

  // Subscribe to paste events
  api.onImagePasted((result) => {
    console.log(`Image pasted: ${result.path}`);
  });
}

How It Works

1. Clipboard read — The extension invokes a platform-native CLI tool (pngpaste, xclip, wl-paste, or PowerShell) to read raw image data from the system clipboard. If the clipboard contains a copied file path instead of raw image data, the file is read from disk.
2. Format detection — The clipboard format is auto-detected from magic bytes (PNG, JPEG, GIF, BMP, WebP, TIFF).
3. Optional preview — If showPreview is enabled, a webview panel shows the image with Paste/Cancel buttons. The preview auto-cancels after 10 seconds if no action is taken.
4. Optional conversion — If saveFormat is set to png or jpeg, the image is converted before saving.
5. Save to disk — The image buffer is written to the configured folder with a filename generated from the filenamePattern setting.
6. Insert path — The absolute file path, quoted for the active terminal's shell type, is sent to the terminal via terminal.sendText().
7. Auto-cleanup — If the image count exceeds maxImages, the oldest files are deleted. Empty subdirectories are removed.
8. Auto-gitignore — On first save, the image folder is appended to .gitignore (unless disabled).

The extension has zero runtime dependencies — it ships as a single bundled JS file with no node_modules.

Troubleshooting

Run Terminal Image Paste: Show Diagnostics from the Command Palette to see a full report of your platform, clipboard tools, storage state, and terminal info. This is the best first step for debugging any issue.

"Clipboard tool not found" warning

Install the required tool for your platform (see Platform Prerequisites), then reload VS Code.

"No image found in clipboard"

Your clipboard contains text, not image data. Copy an image (screenshot, right-click → Copy Image) and try again.

"No active terminal"

Open a terminal (`Ctrl+``) before pasting. The extension inserts the path into whichever terminal is currently focused.

"No workspace folder is open"

The extension needs an open workspace to save images. Open a folder or workspace in VS Code first.

Images aren't being cleaned up

Check that terminalImgPaste.maxImages is set to a positive integer. Image files (.png, .jpg, .jpeg, .gif, .tiff, .bmp, .webp) in the image folder are counted and cleaned up.

WSL2-specific issues

The extension accesses the Windows clipboard from WSL by invoking powershell.exe through WSL interop. If this fails:

• Verify WSL interop is enabled: cat /proc/sys/fs/binfmt_misc/WSLInterop should exist
• Check that powershell.exe is accessible from your WSL shell
• With WSLg installed, the extension prefers native Linux tools (xclip/wl-paste) which are faster and more reliable

Remote terminal warning

When connected to a remote workspace (SSH, container, WSL), images are saved on the local filesystem. The pasted path may not exist on the remote machine. Disable the warning with terminalImgPaste.warnOnRemote: false if you understand the limitation.

Development

# Install dev dependencies
npm install

# Build the extension
npm run compile

# Watch for changes during development
npm run watch

# Run tests
npm test

# Run integration tests
npm run test:integration

# Lint
npm run lint

# Package as .vsix
npm run package

License

MIT