Paste an image-only clipboard as a temporary file path

[Lysak]

Hi,

I would like to ask about a small paste improvement before preparing a PR.

Problem

agterm can paste text and local file paths.

But when I copy a screenshot or another image to the macOS clipboard, Cmd+V cannot pass that image to a local CLI tool such as Claude Code.

I must first save the image manually and then paste its file path.

Proposal

For normal Cmd+V only:

• Keep the current behavior when the clipboard has text, a URL, HTML, RTF, or RTFD.
• When the clipboard has image data only, save it as a small temporary local PNG file.
• Paste its shell-escaped path into the terminal.
• Remove temporary files created by the app later.

Not included

• No inline image rendering.
• No Kitty graphics protocol.
• No SSH or remote tmux upload.
• No new setting, control API command, or drag-and-drop change.

This would only help local CLI tools receive an image through Cmd+V.

Would this fit agterm before I prepare a small PR?

[umputun]

this already works, just with a different key.

Claude Code's own docs list Ctrl+V as the way to paste an image: "Copy an image and paste it into the CLI with Ctrl+V. On macOS, Cmd+V also works in iTerm2." Nothing in agterm binds ctrl+v, so the keystroke goes straight through to the program, which reads the clipboard itself. The terminal never touches the image.

Cmd+V is the odd one out in that sentence, not the standard. As far as I know no terminal turns an image clipboard into a paste: ghostty doesn't, kitty doesn't. What iTerm2 does is exactly what you propose here, writing the image to a temp file and pasting the path. So this isn't a gap in agterm, it's an iTerm2 extra.

on the mechanism, in case the Cmd+V ergonomics still appeal: it can't be scoped to "normal Cmd+V only". The clipboard read arrives through a single libghostty callback, read_clipboard_cb, and its only argument says standard vs selection. Nothing tells the host whether a human pressed Cmd+V or a program issued an OSC 52 clipboard read. The image branch would fire for both, including a program on the far side of an ssh session, and it would write that PNG before the user answers the confirmation prompt for the read. Right-click paste and agtermctl session paste run the same binding, so they'd pick up the new behavior too.

the temp file is the other half of it. Everything agterm writes to /tmp today is consumed by a process agterm spawned and deleted when that surface tears down. A pasted path goes to an arbitrary program that may read it seconds later, or after a resume, so "remove them later" has no owner: delete at quit and you break a transcript still holding the path, keep them and screenshots pile up.

same boundary as #43, the image belongs to the program in the pane rather than to the paste handler. Ctrl+V is that working as intended.