pi-atomic-images

A deliberately small Pi extension for native-feeling clipboard image attachments.

Behavior

1. Copy an image on macOS.
2. Press Pi's image-paste key, Ctrl+V by default.
3. The editor inserts [Image #01] instead of a temporary file path.
4. Left/right navigation treats the placeholder as one item.
5. Backspace or Delete anywhere inside or adjacent to the placeholder removes it in one action.
6. On submit, only placeholders still present in the message are converted to native image attachments. The submitted user turn keeps displaying [Image #01], while a non-destructive context projection replaces each placeholder with its corresponding native image block at the same position for the model.
7. If the selected model is text-only, submission is stopped, the draft is restored, and Pi shows a warning instead of silently dropping the image.

The extension intentionally has no compose-time image preview, commands, settings, image compression, cache, or persistence.

The attachment architecture follows the same separation used by mature CLI agents: an atomic editor placeholder is only the display/control surface, while model input is a structured sequence of text and image blocks. No placeholder or temporary path is sent as a file reference.

Install

From npm:

pi install npm:pi-atomic-images

Directly from GitHub:

pi install git:github.com/raosay/pi-atomic-images

Develop locally

From the directory containing this package:

pi -e ./pi-atomic-images/index.ts

Install it for the current project:

pi install -l ./pi-atomic-images

Security boundary

• No runtime dependencies.
• No network access or child processes.
• Reuses Pi's official clipboard reader and Ctrl+V keybinding.
• Reads only Pi-generated pi-clipboard-<uuid>.<ext> files directly inside the OS temp directory.
• Rejects symlinks, empty files, files over 20 MiB, and content without a supported PNG/JPEG/GIF/WebP signature.
• Keeps accepted image bytes in process memory and removes Pi's temporary file after reading it.
• Sends an image only when its placeholder is still present at submission time.

Like every native image attachment, submitted image bytes are sent to the model provider configured in Pi. The extension does not send local file paths to the model.

Before submitting, confirm the selected model reports yes in the images column:

pi --list-models

Compatibility

Designed and tested against @earendil-works/pi-coding-agent 0.82.x. It replaces Pi's input editor, so another extension that also replaces the editor may conflict depending on extension load order.

Test

npm test