ClaudeImage — paste clipboard images into your terminal with Cmd+V

A tiny native macOS menu-bar app (Swift, zero dependencies) that solves this problem:

CleanShot X (or anything else) copies a screenshot to the clipboard. Cmd+V pastes it into Word just fine, but pasting an image into iTerm2 / Terminal running Claude Code does nothing — you have to drag the file into the window to get it in as [Image #1].

How it works

Dragging a file into a terminal isn't magic — the terminal just inserts the file path as text, and Claude Code recognizes it as an image. This app does exactly the same thing, straight from the clipboard:

CleanShot X → Copy (image on the clipboard)
        │
   Cmd+V in iTerm2
        │
ClaudeImage (CGEvent tap intercepts Cmd+V)
        │
   Is a terminal frontmost?  ──no──▶ Cmd+V passes through unchanged
        │ yes
   Is there an image (and no text) on the clipboard?  ──no──▶ passes through
        │ yes
   1. saves a PNG to ~/Pictures/ClaudeImage/img-YYYYMMDD-HHMMSS.png
   2. temporarily swaps the clipboard for the file path
   3. sends a synthetic Cmd+V (the terminal pastes the path as text)
   4. restores the original image to the clipboard after 0.6 s
        │
Claude Code shows [Image #1] — exactly like drag & drop

The menu bar icon (between battery and Wi-Fi):

Key design points:

• Only acts in terminals (iTerm2, Terminal, Warp, kitty, Alacritty, WezTerm, Ghostty). Cmd+V in Word, Slack, etc. is untouched.
• Only acts when the clipboard holds a pure image (no text). Copied text pastes exactly as before.
• A copied image file (Cmd+C in Finder, or CleanShot "Copy file") is pasted directly as its path — nothing gets re-saved.
• The clipboard is restored after the paste, so you can immediately paste the same image into a GUI app.
• Saved screenshots older than 7 days are cleaned up on launch.
• The synthetic Cmd+V is tagged with a magic event-source value so the app's own tap lets it through (no interception loop).

Installation

A) Prebuilt app (Release): download ClaudeImage.app.zip from Releases, unzip, and move ClaudeImage.app to /Applications. The app is only ad-hoc signed, so macOS will warn about an unidentified developer on first launch — open it via right-click → Open, or clear the quarantine flag:

xattr -d com.apple.quarantine /Applications/ClaudeImage.app

B) Build from source (requires Xcode Command Line Tools):

./build.sh
open build/ClaudeImage.app

First launch — permissions

The app needs Accessibility access (to intercept and post keystrokes):

1. On first launch a system dialog appears → System Settings → Privacy & Security → Accessibility → enable ClaudeImage.
2. The app detects the grant within seconds — no restart needed.

After a rebuild (./build.sh), macOS may require the permission again — toggle ClaudeImage off/on in Accessibility, or remove (−) and re-add it.

Start at login: System Settings → General → Login Items → add ClaudeImage.app.

Usage

1. CleanShot X → screenshot → Copy.
2. Click into iTerm2 with Claude Code running.
3. Cmd+V → the file path is pasted and Claude Code shows [Image #1].

Use the menu bar icon to temporarily disable the app, open the images folder, or quit.

Troubleshooting

• Icon missing from the menu bar (macOS 26 + multiple displays): the system can park the status item off-screen (window frame with x < 0) when no preferred position is stored. The app seeds its own position on launch (NSStatusItem Preferred Position Item-0). If the icon ever disappears again, run: defaults write sk.dvoran.claudeimage "NSStatusItem Preferred Position Item-0" -float 200 and restart the app.
• Diagnostics: the app logs to /tmp/ClaudeImage.log (status item state, window position, screens, event tap).
• Cmd+V does nothing: check the Accessibility permission — every rebuild invalidates it (ad-hoc signature) and it must be toggled off/on in System Settings.

Limitations / notes

• When a terminal is frontmost but Claude Code isn't running in it (e.g. vim), Cmd+V with an image on the clipboard still pastes the file path as text. That's by design — the app can't see what runs inside the terminal. Disable it temporarily from the menu bar if needed.
• VS Code (integrated terminal) is intentionally not in the list — the app can't tell whether focus is in the editor or the terminal. Add bundle IDs in Sources/main.swift (terminalBundleIDs) if you want it.
• Independently of this app: recent versions of Claude Code can paste clipboard images natively with Ctrl+V (not Cmd+V). If that doesn't work for you, try updating Claude Code — this app additionally covers the muscle-memory Cmd+V and works in any terminal.

License

MIT