Image attachment and preview extension for the Pi coding agent.
pi-image-tools lets you attach clipboard images or recent screenshots to your next user message, then preview them inline in the TUI before the message is sent.
- Clipboard image attach with
/paste-imageand keyboard shortcuts - Recent image picker for screenshots and cached clipboard images
- Inline preview rendering in the TUI chat before the message is sent
- Cross-platform recent image discovery for Windows, Linux, and macOS
- Multiple clipboard backends with platform-specific fallbacks
- Recent-cache persistence so clipboard images also appear in the recent picker
- Terminal image safety that preserves inline image protocol rows during width fitting
| Platform | Clipboard paste | Recent image picker | Notes |
|---|---|---|---|
| Windows | Yes | Yes | Uses native clipboard module first, then PowerShell fallback |
| Linux | Yes | Yes | Requires a graphical session; uses wl-paste or xclip, then native module fallback |
| macOS | Yes* | Yes | Clipboard paste depends on @mariozechner/clipboard being available |
| Termux / headless Linux | No | Limited | Clipboard image paste is disabled without a graphical session |
* macOS clipboard image support relies on the optional native clipboard module.
Place this folder in one of these locations:
| Scope | Path |
|---|---|
| Global | ~/.pi/agent/extensions/pi-image-tools |
| Project | .pi/extensions/pi-image-tools |
Pi auto-discovers extensions in those paths.
pi install npm:pi-image-toolspi install git:github.com/MasuRii/pi-image-tools/paste-image clipboard
or simply:
/paste-image
This reads an image from your clipboard and queues it for attachment. A marker ([ Image Attached]) is inserted into your draft. When you send the message, the marker is removed and the image payload is attached.
Remove all markers from the draft before sending if you want to discard pending images.
/paste-image recent
This opens an interactive picker showing recent screenshots and cached clipboard images.
Example entry:
01. Screenshot 2026-03-02 142233.png • 2m ago • 412 KB • C:\Users\...\Pictures\Screenshots\...
Selecting an entry queues that image for your next message.
| Platform | Shortcuts |
|---|---|
| Windows | Alt+V, Ctrl+Alt+V |
| Linux / macOS | Ctrl+V, Alt+V, Ctrl+Alt+V |
| Variable | Description | Default |
|---|---|---|
PI_IMAGE_TOOLS_RECENT_DIRS |
Semicolon-separated directories to search for recent images | Platform defaults listed below |
PI_IMAGE_TOOLS_RECENT_CACHE_DIR |
Custom cache directory for clipboard-pasted images | OS temp dir + pi-image-tools/recent-cache |
Example:
$env:PI_IMAGE_TOOLS_RECENT_DIRS = "C:\Users\me\Pictures\Screenshots;D:\Shares\Screens"A config file can be placed at:
~/.pi/agent/extensions/pi-image-tools/config.json
Starter template:
{
"enabled": true
}See config/config.example.json for the same template.
- Cache directory for clipboard-pasted images
~/Pictures/Screenshots~/OneDrive/Pictures/Screenshots~/Desktopfiltered to screenshot-like names
- Cache directory for clipboard-pasted images
~/Pictures/Screenshots~/Picturesfiltered to screenshot-like names~/Downloadsfiltered to screenshot-like names~/Desktopfiltered to screenshot-like names
- Cache directory for clipboard-pasted images
~/Desktopfiltered to screenshot-like names~/Downloadsfiltered to screenshot-like names~/Pictures/Screenshots~/Picturesfiltered to screenshot-like names
Supported image formats:
.png.jpg.jpeg.webp.gif.bmp
When you queue one or more images, the extension renders an inline preview inside the user message area.
Preview behavior:
- up to 3 images are previewed per message
- Sixel rendering is attempted on Windows when available
- native TUI image rendering is used as the fallback
- inline width fitting now preserves Sixel, Kitty, and iTerm image protocol rows instead of truncating them like plain text
pi-image-tools uses the first available clipboard backend for the current platform:
- Windows
@mariozechner/clipboard- PowerShell
System.Windows.Forms.Clipboard
- Linux
wl-paste(wl-clipboard) in Wayland sessionsxclipin X11 sessions@mariozechner/clipboardfallback
- macOS
@mariozechner/clipboard
If a platform-specific reader exists but no image is currently on the clipboard, the command returns a normal “No image found in clipboard” message. If no usable reader exists at all, the extension surfaces a setup-oriented error.
pi-image-tools/
├── index.ts # Root entrypoint for Pi auto-discovery
├── src/
│ ├── index.ts # Extension bootstrap and message flow
│ ├── commands.ts # /paste-image command registration
│ ├── clipboard.ts # Cross-platform clipboard image reading
│ ├── recent-images.ts # Recent image discovery and cache management
│ ├── image-preview.ts # Preview building and Sixel/native rendering
│ ├── inline-user-preview.ts # Inline preview patching for user messages
│ ├── keybindings.ts # Keyboard shortcut registration
│ ├── temp-file.ts # Temporary file management and cleanup
│ └── types.ts # Shared TypeScript types
├── config/
│ └── config.example.json # Starter runtime config
└── asset/
└── pi-image-tools.png # README preview image
| Issue | Solution |
|---|---|
No image found in clipboard |
Confirm you copied an actual image, not text or a file path |
| Linux clipboard paste fails | Make sure you are in a graphical session and install wl-clipboard or xclip |
| Recent picker is empty | Add directories via PI_IMAGE_TOOLS_RECENT_DIRS or paste images from clipboard first so they enter the recent cache |
/paste-image recent says it requires interactive mode |
Run Pi in interactive TUI mode |
| Sixel preview warning appears | On Windows, install the PowerShell Sixel module and restart Pi |
Manual Sixel installation:
Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber# Type-check
npm run build
# Run tests
npm run test
# Full verification
npm run check- pi-tool-display — Compact tool rendering and diff visualization
- pi-hide-messages — Hide older chat messages without losing context
- pi-startup-redraw-fix — Fix terminal redraw glitches on startup
- pi-smart-voice-notify — Multi-channel TTS and sound notifications
MIT