feat: paste clipboard images into terminals with ⌘V (Claude Code integration)

[iOSDevSK]

What

When a terminal app (iTerm2, Terminal, Warp, kitty, Alacritty, WezTerm, Ghostty) is frontmost and the clipboard holds a pure image (no text), plain ⌘V now pastes the image's shell-escaped file path instead — Claude Code picks it up as [Image #1], exactly like drag & drop.

BetterShot already copies every screenshot to the clipboard (Copy to clipboard after saving), but pasting an image into a terminal running Claude Code does nothing — you have to drag the file into the window. This closes that gap: screenshot → ⌘V → done.

How it works

⌘V in a terminal
  → existing CGEvent tap in ShortcutService (no second tap, no new permissions)
  → TerminalPasteService: is the frontmost app a terminal? is the clipboard a pure image?
  → swallow ⌘V, put the file path on the clipboard, post a synthetic ⌘V
  → restore the original clipboard 0.6 s later

• Screenshots captured by BetterShot reuse the already-saved file — the pasteboard changeCount is tracked when the app copies after save, so no duplicate PNG is written
• Images copied from other apps are saved to ~/Pictures/BetterShot (paste-*.png, cleaned up after 7 days)
• Copied text is never affected; copied image files paste as their existing paths
• Synthetic ⌘V events carry an event-source marker so the app's own tap lets them through (no interception loop)
• The original clipboard is restored right after the paste, so the image can still be pasted into GUI apps
• Settings → General → Claude Code toggle, enabled by default

Scope

• New: Sources/Services/TerminalPasteService.swift
• Hook in ShortcutService event tap callback, one-line hooks in CaptureOrchestrator (copy-after-save) and BetterShotDelegate (launch cleanup)
• Preference + settings UI; CHANGELOG.md entry under Unreleased
• No version bump (left to the maintainer), no new permissions (Accessibility is already required for shortcuts)

Testing

• make release builds clean
• Manually verified: BetterShot screenshot → ⌘V in iTerm2 running Claude Code inserts the saved file's path and Claude Code attaches it as [Image #1]; image copied from a browser gets saved and pasted; copied text pastes normally; toggle off restores stock ⌘V behavior; clipboard still holds the image after the paste

Note: on the newest Xcode toolchains main itself doesn't compile — see the companion PR #80 with minimal Swift 6 concurrency fixes. This PR is independent of it.

🤖 Generated with Claude Code

[vercel]

Someone is attempting to deploy a commit to the knox projects Team on Vercel.

A member of the Team first needs to authorize it.

[tembo]

readObjects(forClasses:) here often comes back as [NSURL] (bridged), so casting directly to [URL] can be flaky.

Suggested change

	) as? [URL], !urls.isEmpty {
	if let nsUrls = pb.readObjects(
	forClasses: [NSURL.self],
	options: [.urlReadingFileURLsOnly: true]
	) as? [NSURL], !nsUrls.isEmpty {
	let urls = nsUrls.map { $0 as URL }
	let images = urls.filter { imageExtensions.contains($0.pathExtension.lowercased()) }
	guard images.count == urls.count else { return nil }
	let text = images.map { shellEscape($0.path) }.joined(separator: " ") + " "
	return (text, images.count == 1 ? images[0] : nil)
	}

[tembo]

If CGEventSource(...) fails, this returns before the restore timer is scheduled, leaving the clipboard overwritten with the path. I’d schedule the restore before the guard (or use defer) so the original clipboard always comes back.

Suggested change

	pb.clearContents()
	pb.setString(text, forType: .string)
	guard let source = CGEventSource(stateID: .combinedSessionState) else { return }
	source.userData = Self.syntheticEventUserData
	let vKey = CGKeyCode(kVK_ANSI_V)
	if let down = CGEvent(keyboardEventSource: source, virtualKey: vKey, keyDown: true),
	let up = CGEvent(keyboardEventSource: source, virtualKey: vKey, keyDown: false) {
	down.flags = .maskCommand
	up.flags = .maskCommand
	down.post(tap: .cghidEventTap)
	up.post(tap: .cghidEventTap)
	}
	// Restore the original clipboard (the image) after the terminal has pasted.
	DispatchQueue.main.asyncAfter(deadline: .now() + 0.6) { [weak self] in
	pb.clearContents()
	pb.writeObjects(saved)
	if let self, let fileURL {
	// Restoring bumps changeCount — re-note the backing file so a
	// repeated ⌘V reuses it instead of saving a duplicate PNG.
	self.noteCopiedToClipboard(fileURL)
	}
	}
	pb.clearContents()
	pb.setString(text, forType: .string)
	// Restore the original clipboard (the image) after the terminal has pasted.
	DispatchQueue.main.asyncAfter(deadline: .now() + 0.6) { [weak self] in
	pb.clearContents()
	pb.writeObjects(saved)
	if let self, let fileURL {
	// Restoring bumps changeCount — re-note the backing file so a
	// repeated ⌘V reuses it instead of saving a duplicate PNG.
	self.noteCopiedToClipboard(fileURL)
	}
	}
	guard let source = CGEventSource(stateID: .combinedSessionState) else { return }
	source.userData = Self.syntheticEventUserData
	let vKey = CGKeyCode(kVK_ANSI_V)
	if let down = CGEvent(keyboardEventSource: source, virtualKey: vKey, keyDown: true),
	let up = CGEvent(keyboardEventSource: source, virtualKey: vKey, keyDown: false) {
	down.flags = .maskCommand
	up.flags = .maskCommand
	down.post(tap: .cghidEventTap)
	up.post(tap: .cghidEventTap)
	}

[tembo]

MainActor.assumeIsolated is easy to accidentally make unsafe later (if the tap ever moves off the main run loop). Adding a cheap debug-time check makes this a lot easier to reason about.

Suggested change

	if keyCode == UInt32(kVK_ANSI_V), carbonMods == UInt32(cmdKey) {
	let handled = MainActor.assumeIsolated {
	TerminalPasteService.shared.interceptCommandV()
	}
	if handled { return nil }
	}
	if keyCode == UInt32(kVK_ANSI_V), carbonMods == UInt32(cmdKey) {
	assert(Thread.isMainThread, "Event tap callback must run on main thread")
	let handled = MainActor.assumeIsolated {
	TerminalPasteService.shared.interceptCommandV()
	}
	if handled { return nil }
	}