instacircle

Self-hosted scripts that read your Instagram feed, stories, and DMs, sort everything by whether it's from a mutual friend (someone who follows you and who you follow back), and forward the results to Discord via webhooks.

Two scripts, one shared login session:

• digest.py — runs once a day. Pulls your home feed and stories tray, splits results into "friend" vs "everyone else", and posts a friends-first digest to a Discord channel.
• monitor.py — runs every 10–20 minutes. Checks your Instagram DM inbox for new messages and posts an alert to a separate Discord channel.

⚠️ Before you use this

• Both scripts use instagrapi, an unofficial Instagram API client. This is against Instagram's Terms of Service and carries a real, non-zero risk of your account being flagged, rate-limited, or restricted. Consider using a secondary account if you're not comfortable with that risk on your main one.
• Never commit .env or session.json — see Security below.

How it works

digest.py

• Computes your mutual friends from 2 lightweight calls (your following list ∩ your followers list) — no per-profile scraping.
• Pulls your home feed (sampled across a few refresh rounds) and your stories tray, then classifies every item as friend / not-friend.
• Rule: if you have 10+ friend posts, show all of them as-is. If you have fewer than 10, show all of them and pad up to 10 with non-friend content. Same rule for stories — multiple stories from one account still count as a single entry.
• Posts the result to Discord as embeds, automatically split across multiple embeds/messages if the count exceeds Discord's limits.

monitor.py

• Checks your inbox for new DMs and alerts on anything new since the last run, tracked in state.json.
• Skips your entire existing message history on its very first run so you don't get flooded with old messages.
• Skips itself entirely for a short window around when digest.py runs (configurable at the top of the file), so the two scripts never touch the shared login session at the same time.

Setup

1. Install dependencies:

   pip install -r requirements.txt

2. Copy the example environment file and fill in your own values:

   cp .env.example .env

3. Both scripts default to /opt/instagram-monitor/ for their .env, session.json, state.json, and lock file. If you're using a different path, update the constants near the top of each script (ENV_FILE, SESSION_FILE, STATE_FILE, LOCK_FILE).

4. Run each script once by hand to confirm login works and a session file gets created:

   python3 monitor.py
   python3 digest.py

5. Add both to cron:

   */10 * * * * /path/to/venv/bin/python3 /opt/instagram-monitor/monitor.py >> /var/log/monitor.log 2>&1
   0 18 * * *   /path/to/venv/bin/python3 /opt/instagram-monitor/digest.py  >> /var/log/digest.log  2>&1

Configuration

Each script has a small block of tunable constants near the top — recency windows, how many posts/stories to target, feed refresh rounds, request timeout, and the digest blackout window. Adjust to taste.

Security

• .env, session.json, state.json, and .ig_session.lock all hold sensitive data — credentials, a live session token, and message history — and are excluded via .gitignore. Don't remove them from .gitignore or commit them.
• If session.json is ever exposed, change your Instagram password immediately; this invalidates the leaked session token.

License

Add a LICENSE file with whichever license you prefer (MIT is a common default for personal tooling like this).