Ak-Maintenance-IG

Instagram account maintenance bot — find non-followers, clean up likes, track growth, detect ghost followers, and score engagement before taking action.

Built with instagrapi, an unofficial Python library that uses Instagram's private mobile API.

---

Setup

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in your IG username & password
python main.py get-me  # verify login works

---

Dashboard (browser UI)

A dark-themed control panel at http://localhost:5050 — no terminal required for day-to-day use.

python dashboard/app.py

Tabs:

Tab	What you see
Overview	Follower/following/post counts, candidate file status cards
Workflows	Every workflow as a clickable button; Actions show Dry Run / Live toggle
Growth	Chart.js line chart of followers & following over time

---

CLI Usage

python main.py --list                                        # show all workflows
python main.py find-non-followers                            # analyze
python main.py dry-run                                       # preview all candidate files
python main.py unfollow-non-followers --limit 5              # dry-run (safe)
python main.py unfollow-non-followers --live --limit 5       # real run
python main.py track-growth                                  # log a growth snapshot
python main.py find-ghost-followers --limit 50               # detect disengaged followers
python main.py check-engagement --limit 30                   # score non-followers before unfollowing

---

Workflow Reference

Utility

Workflow	What it does
get-me	Quick profile check — followers, following, post count
inspect	Read-only account overview
dry-run	Preview all candidate JSON files without touching the account

Analysis (read-only, generates candidate files)

Workflow	Output file	What it does
find-non-followers	non_follower_candidates.json	Accounts you follow that don't follow back
find-liked-posts	like_candidates.json	Your recently liked posts (Instagram caps at ~50)
find-posts-by-date	post_delete_candidates.json	Your posts older than N days
track-growth	logs/growth_log.csv	Appends a timestamped snapshot of follower/following/posts/ratio
find-ghost-followers	ghost_follower_candidates.json	Followers with zero engagement across your last N posts
check-engagement	engagement_scores.json	Scores non-followers by likes (+1) and comments (+2) on your posts

Actions (modify account — dry-run by default, add --live to execute)

Workflow	What it does
bulk-unlike	Unlike recently liked posts directly
bulk-unlike-candidates	Unlike from like_candidates.json
bulk-unfollow	Unfollow accounts directly
bulk-unfollow-non-followers	Unfollow from non_follower_candidates.json
bulk-remove-followers	Remove accounts from your followers list
bulk-delete-posts	Delete posts from post_delete_candidates.json

---

Feature Details

Ghost Follower Detection

Fetches your last N posts, collects all accounts that liked or commented, then flags followers with zero interaction as "ghosts." Configure in ig_config.py:

GHOST_FOLLOWER_MIN_POSTS = 10            # minimum posts to analyze
GHOST_FOLLOWER_ENGAGEMENT_THRESHOLD = 0  # zero interactions = ghost

Engagement Scoring Before Unfollow

Before bulk-unfollowing non-followers, score each account by their activity on your posts:

• Likes = +1 point
• Comments = +2 points

Accounts above MIN_ENGAGEMENT_SCORE_TO_KEEP are saved to a "keep" list automatically. Results saved to engagement_scores.json.

Growth Tracker

Run track-growth on a schedule (cron or manually) to build a time-series of your account metrics. The dashboard's Growth tab charts this data automatically from logs/growth_log.csv.

Follow-Back Grace Period

Non-follower detection skips accounts you followed within the last FOLLOW_BACK_GRACE_DAYS days (default: 7), giving new follows time to reciprocate before appearing as candidates.

Bio Keyword Whitelist

Add keywords to BIO_WHITELIST_KEYWORDS in ig_config.py to permanently protect accounts from candidate files regardless of follow-back status.

---

Safety

• All action workflows default to dry-run — nothing changes until you add --live
• Randomized delays (5–15s) between actions to avoid spam detection
• Stop immediately if ChallengeRequired — handle in the Instagram app first
• Every action is logged to logs/ as CSV
• protected_accounts.json hard-protects specific accounts from all workflows
• Keep daily unfollow counts under 150–200

Two-Step Pattern

Every destructive workflow follows the same safe pattern:

1. Analyze → generates a *_candidates.json file (read-only, nothing changes)
2. Review → open the JSON, delete entries you want to keep
3. Act → dry-run first, then --live

---

⚠️ Important

This bot uses Instagram's private API. Use responsibly:

• Don't run multiple sessions simultaneously
• If Instagram requests phone verification, stop and verify manually
• Delete session.json and re-authenticate if you get LoginRequired errors