Pi Shotbasket

Collect screenshots in Pi, then send them as separate images in one message. No separate app, menu-bar service, clipboard workflow or automatic message sending.

Installation

Install from npm:

pi install npm:pi-shotbasket

Or install the public repository locally:

git clone https://github.com/pasakaan/pi-shotbasket.git
pi install ./pi-shotbasket

If Pi is already running, send any queued screenshots before /reload: reloading clears the basket. Runtime installation does not require running npm install inside this package.

Update

Run these in your shell, not inside Pi:

pi update --extension npm:pi-shotbasket   # this package only
pi update --extensions                    # all installed packages

A version-pinned install (for example npm:pi-shotbasket@0.4.3) stays on that version; reinstall with pi install npm:pi-shotbasket@<version>. For a local git install, run git pull in the clone. pi list shows how the package was installed. Then send queued screenshots and run /reload or restart Pi.

Disable or remove

Inside Pi, run /shots off. It disables the extension in Pi's settings (the same change as unchecking it in pi config) and reloads Pi, so /shots, the shortcut and the status line are gone right away and stay off after restart. Queued screenshots are discarded by the reload. To turn it back on, run pi config in your shell, check pi-shotbasket again, then /reload or restart Pi. /shots off only works when installed as a Pi package (pi install), not when loaded with pi -e.

From your shell:

pi config                          # uncheck pi-shotbasket (Tab switches global/project scope)
pi remove npm:pi-shotbasket        # uninstall completely
pi --no-extensions                 # one session without any extensions

After pi config or pi remove, run /reload or restart Pi. To keep the extension on but stop only the keyboard shortcut, run /shots shortcut off and /reload; /shots stays available.

Requirements

• Node.js 24+ and Pi 0.85.1–0.85.x.
• An authenticated model that accepts images, with Pi running in an interactive terminal.
• macOS: allow the terminal or hosting app running Pi in System Settings → Privacy & Security → Screen Recording (Screen & System Audio Recording on newer macOS). Restart that app/Pi if needed. No Accessibility permission is required.
• Windows 10/11: experimental, not verified on real Windows hardware. Requires native Windows Node/Pi, Windows PowerShell 5.1 and .NET Framework desktop components (WinForms/System.Drawing). PowerShell 7 alone is insufficient.
• Linux, WSL, remote/headless sessions and locked/secure desktops are unsupported.

Usage

1. Run /shots or press Ctrl+Alt+S (Ctrl+Option+S on macOS).
2. On macOS, first-use setup appears before capture. Choose Open System Settings, Continue — permission already enabled, or Cancel. Opening settings does not capture; return and run /shots when ready.
3. Release the shortcut modifiers, then select a screen region. Escape cancels.
4. Repeat to collect more images. The status line shows Shots: N.
5. Write a nonempty prompt and press Enter. The screenshots are attached separately.

No extra paste step is needed. The submitted batch is consumed when the matching user message starts; subsequent captures form a new batch. Empty Enter does not submit images. Wait until the model is idle before capturing/submitting; streaming/steering submissions are unsupported.

Command	Action
/shots	Capture a region
/shots permissions	Reopen macOS Screen Recording setup without capturing
/shots status	Show count, limits, active/saved shortcut and saving state
/shots off	Disable the extension (like pi config) and reload Pi; re-enable with pi config
/shots clear	Clear the basket and cancel an ongoing capture
/shots save	Show whether captures are also saved to disk (off by default)
/shots save on [dir]	Also save each new capture as a PNG (default ~/Pictures/pi-shotbasket)
/shots save off	Stop saving; already saved files are kept
/shots shortcut	Open the keyboard recorder
/shots shortcut ctrl+alt+x	Save an explicit shortcut
/shots shortcut reset	Save the default shortcut
/shots shortcut off	Disable the shortcut after reload; /shots remains available

Setup acknowledgement lasts only for this Pi session; /reload or a new session shows it again. This is guidance, not a permission check: macOS cancellation and missing output cannot reliably identify denied permission. If no image appears unexpectedly, use /shots permissions. The extension never grants permissions or reads/resets privacy settings.

Record your shortcut

/shots shortcut opens a bordered SHORTCUT RECORDER panel. Press the actual key combination—do not type or paste its name. Check the selected shortcut, then press Enter to save or Escape to cancel. The panel shows Detected key: ... from Pi's decoded terminal input, independently of the selected candidate. Unknown input shows Unrecognized input; bracketed paste shows Paste ignored. Invalid input clears the candidate; Enter without a valid selection does not save. Raw input/pasted content is never displayed or logged. This reports what reached Pi, not necessarily the physical combination you pressed.

Changes do not rebind immediately. Send queued images first, then run /reload or restart Pi. Saving or cancelling does not clear the basket; reloading does. Active and saved bindings are displayed separately.

Settings live in shotbasket.json under Pi's user agent directory (PI_CODING_AGENT_DIR, or ~/.pi/agent). This does not modify package source or Pi's keybindings.json. Broken configuration warns and falls back without automatically overwriting the file.

Use terminal KeyId names such as ctrl+alt+x or f6. In text commands use alt, not option, and super, not cmd. Shotbasket accepts any syntactically valid KeyId, including plain letters, ctrl+c, ctrl+v and existing Pi bindings. These choices can interrupt typing/editing or conflict with other actions; they are your responsibility. Malformed names/modifiers are still rejected; off stores null.

Enter and Escape remain save/cancel controls inside the recorder. To configure them, use /shots shortcut enter or /shots shortcut escape directly. /shots and /shots shortcut off are command fallbacks. If your binding prevents command entry, set "shortcut": null in the settings file and restart Pi.

Accepted configuration/registration does not guarantee delivery. Pi retains its own runtime safety and priority: reserved built-in conflicts may be skipped (for example, a key bound to interrupt); nonreserved conflicts may override with warnings. Other extensions and OS/terminal interception can also affect dispatch. Check Pi's warnings and /hotkeys after reload. No Pi bindings or runtime safeguards are modified. This is not a global keyboard or mouse listener, and the cause of any previously failed physical key combination remains unverified.

Saving screenshots (optional)

By default nothing is kept on disk: captures live only in the in-memory basket and their temporary files are removed right away. Run /shots save on to also keep a copy of every new capture in ~/Pictures/pi-shotbasket, or /shots save on /absolute/dir (~/... works) for another folder. The change applies to the next capture; no reload needed.

Files are named shot-YYYYMMDD-HHMMSS-mmm.png, created with owner-only permissions, and never overwritten. /shots save off stops saving. The extension never deletes saved files: remove them yourself when you no longer need them. If a save fails, the capture stays in the basket and a warning is shown.

The setting is stored as "saveDir" in shotbasket.json (null = off). An invalid value warns at startup, leaves saving off and does not rewrite the file.

Limits and privacy

• Maximum 6 images, 8 MiB per PNG, 20 MiB total raw image data. Existing attachments count toward combined limits; providers may impose lower limits.
• The basket is in memory. Captures use an owned temporary directory, cleaned after success, cancellation or failure. Abrupt process/system termination can leave temporary files. Nothing else is written to disk unless you enable /shots save on.
• PNG structure and CRCs are checked; validation is not a full pixel decoder.
• Captures time out after 120 seconds. Cleanup waits for the child process to close. Windows also has a selector lifetime limit.
• On macOS, holding Control during region selection can redirect capture to the clipboard: release modifiers first.
• Windows captures the desktop to memory before displaying its selection overlay; only the selected region is saved as PNG. Temporary-directory ACLs are restricted before pixel writes.
• Session changes, /new, /fork, /reload, tree navigation and shutdown clear the basket.
• Failed preflight retains basket images. Ordinary Pi-pasted attachments may need reattachment if Pi rejects a submission. If the provider fails after the user message starts, images are already part of that message.
• Existing input images are preserved. Other extensions that remove or change screenshot bytes can prevent safe batch consumption; check /shots status before retrying.
• Submitted images enter Pi session history and are sent to the selected model provider. Do not capture sensitive material you do not intend to share.

Experimental Windows support

Drag with the left mouse button, then release to select. Escape or a zero-area selection cancels. Multiple monitors, negative coordinates and mixed DPI are implemented but not runtime-verified on Windows. See WINDOWS-CHECKLIST.md.

PowerShell execution policy, downloaded-file restrictions, AppLocker/WDAC or constrained language mode may block the helper. Failures are reported rather than treated as cancellation. Inspect Get-ExecutionPolicy -List and ask your administrator to approve/sign the reviewed helper where required. The package does not bypass policy, remove download markers or change security settings.

Development

npm ci
npm test
npm run typecheck
npm run smoke
npm pack --dry-run

The test suite covers queue/input transactions, shortcut recording, rendering and injected capture subprocess behavior. The current macOS-specific capture tests are intended for macOS; running the full suite on Windows is not yet supported. Loader smoke starts isolated Pi without a model request or screenshot. Native Windows GUI, DPI, ACL and policy behavior still require manual verification. No generated build tools or personal settings belong in the public package.

License

MIT — see LICENSE.