pi-screenshots-picker

A pi coding agent extension for quickly selecting and attaching screenshots to your prompts. Works on macOS and Linux. Browse recent screenshots with thumbnail previews, stage multiple images, then type your message - screenshots attach automatically when you send.

https://github.com/user-attachments/assets/365f6fa8-0922-4172-8611-141300aed7f6

Why

Attaching screenshots during development is tedious. You're constantly:

• Dragging files from Desktop/Finder
• Losing track of which screenshot is which
• Breaking your flow to find the right image

pi-screenshots-picker gives you a visual screenshot browser right in your terminal:

/ss

Install

pi install npm:pi-screenshots-picker

Quick Start

1. Press Ctrl+Shift+S or type /ss to open the picker
2. Navigate with ↑↓, press s or space to stage screenshots (✓ appears)
3. Press Enter to close the picker
4. Type your message in the prompt
5. Press Enter to send - staged images attach automatically

Commands

/ss

Opens the interactive screenshot picker UI. Browse your recent screenshots with thumbnail previews.

Keys:

• ↑↓ - Navigate through screenshots
• Ctrl+T - Cycle through source tabs (when multiple sources configured)
• z - Toggle zoom inspector mode
• + / - - Zoom in/out (inspector mode)
• ←↑→↓ - Pan image in inspector mode (Kitty/Ghostty/WezTerm); falls back to nav otherwise
• [ / ] - Previous/next screenshot in inspector mode
• 0 - Reset inspector zoom + pan (only after this you can select other screenshots)
• s / space - Stage/unstage current screenshot (✓ indicator appears)
• x - Clear all staged screenshots
• o - Open in Preview.app
• d - Delete screenshot from disk
• Enter - Close picker
• Esc - Cancel

/ss-clear

Clear all staged screenshots without sending.

Ctrl+Shift+S

Keyboard shortcut to open the picker (same as /ss).

Ctrl+Shift+X

Keyboard shortcut to clear all staged screenshots (same as /ss-clear).

Features

• Multiple sources with tabs - Configure multiple directories/patterns, switch with Ctrl+T
• Glob pattern support - Use patterns like **/*.png to match files flexibly
• Thumbnail previews - See what you're selecting (Kitty/iTerm2/Ghostty/WezTerm)
• Zoom inspector mode - Press z, then pan with arrows and zoom with +/-
• Multi-select - Stage multiple screenshots, they all attach when you send
• Relative timestamps - "2 minutes ago", "yesterday", etc.
• File sizes - Know what you're attaching
• Delete screenshots - Press d to remove unwanted screenshots from disk
• Staged indicator - Widget shows 📷 N screenshots staged below the editor
• Auto-detection - Finds your screenshot folder automatically when no config

Configuration

By default, the extension auto-detects your screenshot location based on your platform.

Multiple Sources with Tabs

Configure multiple screenshot sources in ~/.pi/agent/settings.json. Each source becomes a tab in the picker UI - use Ctrl+T to cycle through them:

{
  "pi-screenshots": {
    "sources": [
      "~/Desktop/ss",
      "~/Pictures/Screenshots",
      "/path/to/comfyui/output/**/thumbnail_*.png"
    ]
  }
}

Source Types

Plain directories - Scans for screenshot-named PNG files:

"~/Desktop/ss"

Glob patterns - Matches any image file (PNG, JPG, WebP) matching the pattern:

"/path/to/images/**/*.png"
"/mnt/Store/ComfyUI/Output/**/thumbnail_*.png"

Glob patterns support:

• * - Match any characters in a filename
• ** - Match any directories recursively
• ? - Match a single character
• [abc] - Match any character in brackets

Default Locations (when no config)

macOS:

1. System preferences (defaults read com.apple.screencapture location)
2. ~/Desktop

Linux:

1. ~/Pictures/Screenshots
2. ~/Pictures
3. ~/Screenshots
4. ~/Desktop

Environment Variable

You can also use the PI_SCREENSHOTS_DIR environment variable as a fallback:

export PI_SCREENSHOTS_DIR="/path/to/screenshots"

Priority

1. Config in ~/.pi/agent/settings.json (pi-screenshots.sources)
2. Environment variable (PI_SCREENSHOTS_DIR)
3. Platform default (see above)

Remote Development

When developing on a remote machine via SSH, you need a way to get screenshots from your local machine to the remote. Use one of these external tools:

Option 1: SSHFS (Simplest)

Mount a remote folder locally. Screenshots you take locally appear on the remote instantly.

On your local machine:

# Install sshfs
# macOS: brew install macfuse sshfs
# Linux: sudo apt install sshfs

# Create mount point
mkdir -p ~/remote-screenshots

# Mount (replace with your remote)
sshfs user@remote:~/Screenshots ~/remote-screenshots

# Configure macOS to save screenshots there
defaults write com.apple.screencapture location ~/remote-screenshots
killall SystemUIServer

On the remote, configure pi-screenshots to read from ~/Screenshots:

{
  "pi-screenshots": {
    "sources": ["~/Screenshots"]
  }
}

Option 2: Syncthing (Most Robust)

Syncthing provides continuous, bidirectional file sync. Better for unreliable connections.

1. Install Syncthing on both machines
2. Share your local screenshot folder with the remote
3. Configure pi-screenshots to read from the synced folder

Thumbnail Previews over SSH

To enable thumbnail previews over SSH, add your terminal to the remote's shell profile:

# Add to remote ~/.bashrc or ~/.zshrc
export TERM_PROGRAM=ghostty  # or: kitty, WezTerm, iTerm.app

Restart pi after (can't use ! inside pi).

Supported Screenshot Formats

The extension recognizes screenshots from various tools:

macOS:

• English: Screenshot ...
• French: Capture ...
• German: Bildschirmfoto ...
• Spanish: Captura ...
• Italian: Istantanea ...
• Dutch: Scherm...

Linux:

• GNOME Screenshot: 2024-01-30_12-30-45.png
• Flameshot: flameshot...
• KDE Spectacle: spectacle...
• Scrot: scrot...
• Maim: maim...
• Grim (Wayland): grim...
• Generic: screenshot...

Only PNG files matching these patterns are shown.

Requirements

• macOS or Linux
• Terminal with image support for thumbnails (Kitty, iTerm2, Ghostty, WezTerm)
  • Falls back gracefully on unsupported terminals

License

MIT