pi-screenshots

Screenshot picker for pi — browse, select, and attach screenshots to your prompts

Packages

Package details

extension

Install pi-screenshots from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-screenshots
Package
pi-screenshots
Version
1.0.0
Published
Mar 21, 2026
Downloads
232/mo · 14/wk
Author
affsantos
License
MIT
Types
extension
Size
16.2 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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