clipboard-image-terminal

Clipboard Image to Terminal

Paste clipboard images as file paths — built for AI coding tools

AI coding tools (Claude Code, Aider, etc.) can't see an image you copy until it's a file on disk — and on WSL the Linux side can't even read the Windows clipboard. Copy any image; this saves it as a PNG (auto-downscaled to save vision tokens) and hands the AI tool its path. Works on WSL/Windows, macOS, and Linux.

🚀 Get started

CLI — for any terminal or AI tool:

npm install -g clipboard-image-terminal
claude "look at $(clipimg)"   # copy an image first, then run this

clipimg prints the saved path to stdout (pipe-friendly) and a colorful [img #n] line to stderr. Useful flags: -d ./shots (custom dir), -q (path only).

Optional background watcher. Bare clipimg captures once. To auto-save every new clipboard image in the background, run clipimg watch (and clipimg stop to end it); its captures show up in clipimg logs as [img #n] lines.

📦 Commands

Command	What it does
clipimg (alias paste, grab)	Capture the clipboard image and print its path (with an [img #n] line)
clipimg watch	Start a background watcher that auto-saves each new clipboard image
clipimg stop	Stop the background watcher
clipimg status (alias ls)	Show watcher state + the store: count, total size, and each image's dimensions, size, age, tokens, a thumbnail where supported, and a clickable file:// link
clipimg logs	Show the watcher's activity log, colorized (the on-disk log stays plain)
clipimg clear (alias clean)	Delete every saved image and reset the [img #n] counter
clipimg doctor (alias deps)	Check the clipboard tools your platform needs, with install hints for anything missing
clipimg help	Show the full help screen

VS Code extension — for working inside the editor:

code --install-extension muammar-yacoob.clipboard-image-terminal

Focus the terminal and press Ctrl+Alt+V (or right-click → Paste Clipboard Image to Terminal) to type the image path into it.

✨ Features

• Token-saving compression — oversized images are downscaled to a vision-token budget before saving (~66% fewer tokens on a 4K screenshot), then logged so you can see the cost of each paste
• Staged feedback & inline preview — the CLI shows each step as it works (◇ reading → ❖ compressing → ▸ saving), an [img #n] summary, and a small inline thumbnail in terminals that support it (VS Code, iTerm2, WezTerm); the extension mirrors it with a progress notification and status-bar badge
• Lossless PNG — keeps screenshots of code & text crisp for vision models
• Cross-platform — WSL/Windows, macOS, and Linux, each via its native clipboard tool
• Background watcher or one-shot — run bare clipimg to auto-save clipboard images in the background, or clipimg paste for a single capture
• Pipeable — clipimg paste prints just the path to stdout, perfect for $(clipimg paste)
• De-duplicated — images are named by content hash, so re-pasting the same image is a no-op
• Self-cleaning — saved images older than 7 days are pruned automatically
• Configurable output directory — -d flag (CLI) or a VS Code setting

⌨️ CLI options

Option	Description
-d, --dir <path>	Output directory (default /tmp/clipboard-images)
-q, --quiet	Print only the path — no staged UI or preview (errors still show)
-v, --version	Print version
-h, --help	Show help

Exits 1 and prints No image on clipboard when the clipboard holds no image. Respects NO_COLOR — set it to disable all ANSI color.

⚙️ Extension settings

Setting	Default	Description
clipboardImage.outputDir	/tmp/clipboard-images	Directory to save pasted images

Rebind the shortcut via Preferences: Open Keyboard Shortcuts → search clipboard-image.paste.

🖥️ Requirements

Node.js ≥ 20 (CLI only), plus a clipboard tool for your platform:

Platform	Tool
WSL / Windows	powershell.exe (default on all installs)
macOS	osascript (built-in), or pngpaste
Linux	wl-clipboard (Wayland) or xclip (X11)

On WSL, if Windows interop is broken (.exes fail with "exec format error"), clipimg falls back to reading the clipboard through WSLg — install wl-clipboard (or xclip) and it keeps working without an interop fix. clipimg doctor shows which path is active.

Compression uses each platform's native resizer — PowerShell on WSL/Windows, the built-in sips (or ImageMagick) on macOS, ImageMagick on Linux. If none is available, the image is still pasted at full size; only the token saving is skipped.

Why the extra tool on Linux (and sometimes macOS)? Node has no built-in way to read image bytes from the clipboard, so clipimg shells out to the OS. On Windows/WSL that's PowerShell + .NET (always present) and on macOS it's the built-in osascript — neither needs anything installed. Linux has no standard clipboard API; the reader is display-server-specific (wl-paste for Wayland, xclip for X11), and those aren't preinstalled on most distros. clipimg does not auto-install system packages — that needs root and differs per distro, which is a footgun for an npm/VS Code package — so instead it detects what's missing and tells you exactly what to install. Run clipimg doctor to see the status for your machine.

🛠️ Development

bun install
bun run build          # compile TypeScript → out/
node out/cli.js help   # try the CLI locally
# Press F5 in VS Code to launch the extension in a dev host

Script	Action
bun run build	Compile with tsc
bun run package	Build + vsce package (.vsix)
bun run publish:vscode	Publish to VS Code Marketplace
bun run publish:npm	Publish the CLI to npm

🌱 Support & Contributions

Star the repo ⭐ & I power up like Mario 🍄
Devs run on coffee ☕
contributions are welcome.

_{Released under MIT License | Privacy Policy}