Pi Image Paste 📋

First-class image attachments for the Pi coding agent.
Paste, drop, or clipboard-paste images — auto-optimized and attached instantly.

---

Why This Exists

Terminal image workflows are awkward. Dragging a screenshot into a terminal inserts a raw file path. Pasting from clipboard requires special handling. Even when the model could inspect a file through tools, that adds friction and wastes context budget.

Pi Image Paste makes image input feel native in pi interactive mode — paste a path, get a placeholder, submit with the image already attached and optimized.

Features

• Instant attach — paste or drag an image path and it becomes a [#image 1] placeholder immediately
• Auto-optimize on ingest — images are compressed to JPEG (q95 → q60 ladder) and resized to a 2MB target before you hit submit
• Magic-byte detection — supports PNG, JPEG, WebP, and GIF regardless of file extension
• Cross-platform paths — handles absolute, relative, home-relative (~/), quoted, shell-escaped, Windows, and WSL paths
• Chat previews — submitted images render inline in conversation history (raw or collapsible)
• Cursor preview — hover over a placeholder to see the image above the editor
• Atomic placeholder deletion — backspace/delete removes the whole [#image N] block, not character-by-character
• Clipboard paste — paste images directly from macOS or Windows clipboard via pi's image paste keybinding
• Custom editor integration — decorates an existing pi editor when one is installed, preserving its input and submit behavior
• Configurable limits — override max image size, dimension cap, and JPEG quality/shrink ladders

Quickstart

pi install git:ssh://git@forge.elephanthand.com:41004/turnercore/pi-image-paste

That's it. The extension auto-loads in pi interactive mode — paste any image path and it gets replaced with a placeholder. On submit, the image is attached alongside your text.

Architecture

The package does not claim Pi's editor slot. A cooperating editor, such as the inline-commands extension, emits pi-image-paste:decorate-editor with its already-created editor. This package decorates that instance in place, so the cooperating editor remains the only caller of setEditorComponent().

flowchart LR
    A[Paste / Drop path] --> B[Ingest Pipeline]
    B --> C[Path Parser]
    C --> D[File Loader]
    D --> E[Attachment Store]
    E --> F[Placeholder in editor]
    D -.->|fire-and-forget| G[Optimizer]
    G -.->|JPEG q95→60, resize| E
    F --> H[Submit]
    H --> I{Await pending optimizations}
    I --> J[Attach images to message]

Optimization runs at ingest time (fire-and-forget async), so images are already compressed by the time you submit. The submit handler just awaits any stragglers.

Development

npm install
npm run check
npm test -- --run
npm run build
pi -e .

---

Built for the Pi coding agent.