---
name: pinpin
description: Query and use the user's Pin Pin screenshot/asset library from Claude Code. Pin Pin is a macOS app that stores saved images, GIFs, and videos in a local SQLite database with folders and tags. TRIGGER when the user says "pinpin", "pin pin", "my pins", "from pin pin", "pins tagged X", "screenshots I saved", "images in my pinpin", "grab a gif from pinpin", "what's in pinpin", or otherwise references their saved visual library. Use this before scraping the web — if the user has assets pinned, use them. Supports search by tag, folder, search_term, media_type, and keyword. Returns file paths ready to feed into video editors, Blender, ffmpeg, image tools, or other skills.
---


# 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

```sql
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

```bash
python3 scripts/pinpin.py stats
```

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

### Search

```bash
# 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`:

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

Prints one absolute path per line.

### Tag management

```bash
# 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.