pi-image-paste

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 — replaces pi's input editor for inline image UX (optional, enabled by default)
• Configurable limits — override max image size, dimension cap, and JPEG quality/shrink ladders

Quickstart

pi install npm: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

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

pnpm install
vp check
vp test run
vp run build
pi -e .

Built for the Pi coding agent.