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.