Pil

Your Instagram saved posts — deep-read by AI, searchable forever, on your machine.

Get started · How it works · Other AI tools · What's inside

mcp-name: io.github.pjpoulose/pil

Get PIL in 3 steps

1. Copy-paste this into Muse:

Code

Copy

    Clone https://github.com/pjpoulose/PIL into your workspace and follow its
    SKILL.md to set up my Personal Instagram Library. Work through it step by
    step — install, build the library from my saved posts, and hand me the
    installable app.

2. When it asks, link your Instagram (one tap in your browser).

3. Download the app file it sends you → unzip → double-click Start PIL → click Install.

That's the whole thing. Your Muse does the setup, the reading, and the building. Want it on your phone too? Just ask your Muse — it handles that as well.

Prefer to do it yourself? One command sets everything up.

• Mac / Linux: curl -fsSL https://raw.githubusercontent.com/pjpoulose/PIL/master/bootstrap.sh | bash
• Windows (PowerShell): irm https://raw.githubusercontent.com/pjpoulose/PIL/master/bootstrap.ps1 | iex

Then build your library with the commands in Manual setup.

Every day you save posts you'll never find again. PIL (Personal Instagram Library) turns your Instagram saved collection into a private knowledge base on your own machine: every post deep-read by vision AI — narrative summaries, key points, how-to steps, links it discusses, automatic tags — searchable in seconds and queryable live from your AI coding tools.

Code is shared, data stays home. This repo contains only code, the database schema, config examples, and docs. Your saved posts, captions, and account details never leave your computer — ingestion, extraction, search, and the MCP server all run locally. A .gitignore blocks databases, configs, and exports from ever being committed.

Concept mockup with sample data — your library looks like this, with your posts.

Want your Claude, Codex, or Cursor to access this?

Connect the read-only MCP server and your other AI tools can query your library live — always current, nothing to re-upload. Your Muse can wire it up for you. How to connect →

How it works

flowchart LR
    A["Instagram saved posts"] -->|"ingest"| B["Local SQLite on your machine"]
    B -->|"vision AI<br/>deep read"| C["Summaries, key points, how-tos, links, tags"]
    C --> D["Query two ways"]
    D --> E["MCP server — Cursor, Claude Code, Desktop"]
    D --> F["Static JSON export — any AI tool"]

Manual setup (do it yourself)

# 1a. Install from PyPI (recommended — no clone needed)
pip install personal-instagram-library
# gives you: pil-mcp pil-ingest pil-extract pil-tag
#            pil-export-web pil-export-html pil-export-pwa pil-publish-pwa

# 1b. Or get the code
git clone https://github.com/pjpoulose/PIL.git pil && cd pil

# 2. Configure (your data lives in data_dir, default ~/.local/share/pil)
cp pil.config.example.json ~/.config/pil/pil.config.json
# edit it: set account_id to your user_fbid from `instagram-cli accounts`

# 3. MCP server dependency
pip install "mcp<2"

cd bin
python3 ingest_saved.py      # collections + saved posts
python3 extract_content.py   # vision-AI deep read (batches of 25)
python3 tag_all.py           # programmatic tags for untagged posts
python3 export_web.py        # static JSON export -> <data_dir>/web_data.json
python3 export_html.py       # searchable HTML dashboard -> <data_dir>/pil_library.html
python3 export_pwa.py        # installable PWA bundle -> <data_dir>/pwa/

python3 bin/mcp_server.py    # read-only, stdio — Ctrl-C to stop

Why not just scroll your saved tab?

Ask your library from other AI tools

Live (recommended): MCP. Point any MCP-compatible assistant at the read-only server and every question reads your current database — always up to date, no exports, no re-uploads:

python3 /path/to/pil/bin/mcp_server.py    # stdio; Ctrl-C to stop

Wiring for Claude Code, Claude Desktop, and Cursor: references/mcp_clients.md. Any MCP-compatible client works — and your Muse can connect it for you if you'd rather not touch configs. Available tools:

The server opens the database with SQLite mode=ro and exposes SELECT-only tools — it cannot modify your library. (Attack-tested: SQL injection, write attempts, and limit abuse all verified blocked.)

Snapshot: file upload. Ask your Muse to send you the web_data.json file (built with export_web.py): every post with its deep-read knowledge in one file. Attach it to any AI chat (Claude, ChatGPT, …) and ask questions like any document. It's frozen at export time — a snapshot, not a live connection — so ask your Muse for a fresh copy after you save new posts.

Directly (advanced). The database is plain SQLite at <data_dir>/pil.sqlite (schema in schema.sql). Open it read-only with any SQLite tool.

These files hold your personal Instagram data — keep them on your own machine and only share them with tools you trust.

Your library as an app

Your Muse builds the app for you and sends it to you — for your computer and your phone. Just ask:

• "Send me my PIL app" — download the file it sends you, unzip, double-click Start PIL, click Install. It lives on your computer like any other app and works fully offline.
• "Put PIL on my phone" — it handles the publishing and gives you a QR code to scan. Tap Install (Android) or Share → Add to Home Screen (iPhone).

No commands, no hosting setup, no terminal — your Muse takes care of all of it.

Signal Deck — the visual dashboard (v1.2.0)

Prefer exploring over querying? The Signal Deck (dashboard/) builds a self-contained HTML dashboard from your local PIL database: a topic-ring hero over everything you saved, search → synthesis (The Brief), a sources rail, a sticky index, and a full archive grid. One file, works offline, your data never leaves your machine.

cd dashboard
PIL_DB=~/.local/share/pil/pil.sqlite python3 build-signal.py
# open pil-signal-deck.html in Chrome/Safari

See dashboard/README.md for details, PWA notes, and the QA suite.

What's inside