pinpin

Query the user's local Pin Pin library — a macOS screenshot/asset manager that stores pinned images, GIFs, and videos in SQLite.

Before scraping the web or generating new assets, check Pin Pin first. The user curates their library by theme — there's a good chance the aesthetic they're asking for is already pinned.

Database location

Pin Pin writes to one of two locations (check both, prefer the first that exists):

1. ~/Library/Application Support/pin-pin/data/pinpin.db — shared location (newer versions)
2. ~/Downloads/Pin Pin 2.app/Contents/Resources/app/data/pinpin.db — bundled DB (older versions)
3. ~/Downloads/Pin Pin.app/Contents/Resources/app/data/pinpin.db — even older

The helper at scripts/pinpin.py picks the right one automatically.

Schema

pins(id, pin_id, media_type, source_url, media_url, title, search_term, file_path, folder_path, file_size, downloaded_at)
folders(id, path, name, last_used)
tags(id, pin_id, tag)  -- FK to pins.id

• media_type is one of image, gif, video
• file_path is the absolute local path to the pinned file
• folder_path is the directory the user pinned it into
• search_term is what the user searched for when they saved it (rich signal)
• tags is a join table — a pin can have many tags

Usage

The helper script handles everything. Pick the invocation for what the user asked for:

List what's in the library

python3 scripts/pinpin.py stats

Returns total pins, breakdown by media_type, folder list, and top tags.

Search

# by tag
python3 scripts/pinpin.py search --tag "cyberpunk" --limit 20

# by keyword (matches title, search_term, tags)
python3 scripts/pinpin.py search --keyword "neon"

# by media type
python3 scripts/pinpin.py search --media gif --limit 50

# by folder
python3 scripts/pinpin.py search --folder "/Users/black/Desktop/Moodboard"

# combine filters (AND)
python3 scripts/pinpin.py search --tag "horror" --media video --limit 10

# random pick (good for generative workflows)
python3 scripts/pinpin.py search --tag "glitch" --random --limit 5

Output is JSON on stdout: [{"id", "file_path", "media_type", "title", "search_term", "folder_path", "tags": [...]}, ...]. Missing files are filtered out automatically.

Just the file paths (for piping into ffmpeg/etc)

Add --paths:

python3 scripts/pinpin.py search --tag "fire" --media gif --paths

Prints one absolute path per line.

Tag management

# add a tag to a pin (by id)
python3 scripts/pinpin.py tag --id 42 --add "moodboard-2026"

# remove a tag
python3 scripts/pinpin.py tag --id 42 --remove "old-tag"

How to use this from other skills/tasks

• Video generation (visualizer, music-video, etc): call search --tag X --media gif --paths to get a list of files to feed in. The visualizer skill already integrates with Pin Pin directly, but other skills can use this as a source.
• Image edits (flicky, canvas-design): use search --keyword X --media image --limit 5 then Read the file_path to inspect, and pass to the image pipeline.
• Moodboards / style refs: use search --folder "/path" to pull an entire curated folder.
• Finding deep cuts: if the user says "use that one thing I pinned about X", try search --keyword X first. The search_term field often contains the exact phrase the user typed when they saved it.

Behavior rules

• Always check the DB is present and reachable before reporting empty results. If missing, tell the user to open Pin Pin at least once.
• Never modify pins / folders tables — only tags is safe to write. The app owns the rest.
• File paths may be stale (user deleted files outside the app). The helper filters missing paths; callers can trust what comes back exists on disk.
• If the user asks "what did I pin about X" and results are empty, don't hallucinate — say the library has nothing matching and offer to widen the search.