pi-screenshots

A pi extension to browse, select, and attach screenshots to your prompts. Works on macOS and Linux.

No drag-and-drop, no file paths. Just /ss, pick, send.

Install

pi install https://github.com/affsantos/pi-screenshots

Usage

/ss — Screenshot Picker

Opens an interactive picker showing recent images from your screenshot directory.

──────────────────────────────────────────────────────────
 Screenshots (1/24)  ~/Desktop
 Screenshot 2026-03-20 at 15.40.22.png
 ▸ ○ Screenshot 2026-03-20 at 15.40…  9h ago   227 KB
   ○ Screenshot 2026-03-20 at 14.43…  10h ago    29 KB
   ✓ Screenshot 2026-03-20 at 14.42…  10h ago    24 KB
   ○ Screenshot 2026-03-20 at 13.59…  10h ago    19 KB
   ○ Screenshot 2026-03-20 at 13.39…  11h ago     8 KB
   ○ Screenshot 2026-03-20 at 11.40…  13h ago   884 KB
   ○ Screenshot 2026-03-20 at 11.39…  13h ago   695 KB
   ○ Screenshot 2026-03-20 at 11.37…  13h ago   1.6 MB
 ✓ 1 staged │ ↵ toggle • x clear all • o open • esc done
──────────────────────────────────────────────────────────

Keys:

| Key | Action | |-----|--------| | ↑ ↓ | Navigate | | Enter | Select / deselect screenshot | | x | Clear all selections | | o | Open in system viewer | | Esc | Close picker |

After closing, type your message and send — selected screenshots attach automatically.

/ss-capture — Take a Screenshot (macOS)

Triggers macOS region capture (screencapture -i). Select an area, and the screenshot is saved and staged in one step. Type your message and send.

/ss-clear — Clear Staged

Removes all staged screenshots without sending.

Ctrl+\ — Shortcut

Opens the picker. Works mid-typing — your editor text is preserved.

Configuration

By default, the extension auto-detects your screenshot directory:

• macOS: System screenshot location preference → ~/Desktop
• Linux: ~/Pictures/Screenshots → ~/Pictures → ~/Screenshots → ~/Desktop

To override, add to ~/.pi/agent/settings.json:

{
  "pi-screenshots": {
    "dir": "~/Pictures/Screenshots"
  }
}

Or set the PI_SCREENSHOTS_DIR environment variable.

Supported Formats

PNG, JPG, JPEG, and WebP files are shown. The 50 most recent files are listed, sorted by modification time.

License

MIT