@jordyvd/pi-image-attachments

A distributable Pi extension package that brings image attachment behavior to Pi without any external runtime dependency beyond Pi itself.

Features

• Ctrl+V clipboard images attach as draft images instead of leaving temp-file paths in the editor.
• Dragging or pasting a local image path into the editor attaches it.
• Draft images are shown as [Image #N] placeholders.
• Placeholders are stripped from the submitted text; only the image content is sent.
• Drafts containing only image placeholders are sent as image-only user messages.
• Screenshot tool results that save to filePath are promoted into inline image content so the agent can inspect them agentically.
• The extension nudges Pi to prefer inline screenshots when the agent needs to inspect the image itself.

Demo

Watch the screen recording demo

Install

From npm (recommended):

pi install npm:@jordyvd/pi-image-attachments

From source:

git clone https://github.com/jordyvandomselaar/pi-image-attachments.git
pi install ./pi-image-attachments

Try without installing:

pi -e npm:@jordyvd/pi-image-attachments

You can also point Pi at a local checkout while developing the extension.

Package structure

This package uses Pi's pi.extensions manifest in package.json, so Pi can load it from npm, git, or a local path.

The npm publish is intentionally limited by the files whitelist in package.json, so repo-only assets like media/pi-image-attachments-demo-2026-03-17.mp4 are kept out of the published package.

Custom editor composability

pi-image-attachments targets Pi 0.71+ and uses the composable custom-editor API: it reads ctx.ui.getEditorComponent() before installing its own editor with ctx.ui.setEditorComponent().

• If another extension installed an editor first, this package wraps that editor instance so its class and behavior remain active while image placeholders are layered on top.
• If no editor is installed yet, this package wraps Pi's default CustomEditor behavior.
• Load order still matters: install editor extensions that should be preserved before pi-image-attachments. A later extension that does not compose with getEditorComponent() can still replace the editor chain.
• Older Pi versions without getEditorComponent() are not supported by this package version; there is intentionally no fallback or compatibility shim.

Tests

bun test
bun test --coverage --coverage-reporter=text --coverage-reporter=lcov