Automated Instagram engagement bot using GramAddict v3.2.12 for organic growth through targeted interactions with relevant audiences.

✅ Human-like Behavior

• Randomized action timings (0.86s - 3.72s delays)
• Variable content engagement (watch times, like counts, story viewing)
• Natural profile exploration and interaction patterns
• 25% slower than default speed for authenticity

✅ Smart Filtering

• Automatic private account detection and skipping
• Empty/low-quality account filtering
• Built-in already-liked post detection
• Bot/spam account detection via follower ratios

✅ Targeted Growth

• Hashtag top likers targeting
• Competitor post likers engagement
• Multiple source mixing for variety
• Personalized hashtag rotation (backend/DevOps niche)

✅ Safety & Control

• Session limits (interactions, likes, follows)
• Debug mode for filter validation
• Comprehensive logging
• Automatic session completion

• Python 3.13+ (tested on 3.13.5)
• Android Device/Emulator with Instagram installed
• ADB (Android Debug Bridge) installed and accessible

# Clone repository
git clone <repository-url>
cd instabot

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Create .env file in project root:

# Instagram Credentials
INSTAGRAM_USER_A=your_username
INSTAGRAM_PASS_A=your_password

# Device Configuration
DEVICE=fbc9d1f30eb2  # Replace with your device ID

Physical Android Device (Recommended):

# Enable USB debugging on your device
# Connect via USB
# Authorize USB debugging when prompted

# Verify connection
adb devices
# Should show: fbc9d1f30eb2    device

MEmu Emulator (Alternative):

# Connect to MEmu (default ports: 21503, 21513, 21523)
adb connect 127.0.0.1:21533

# Verify connection
adb devices

Install Recommended Instagram Version:

• Download Instagram v313 (tested and working)
• Install: adb install instagram313.apk
• Login to your account manually
• Keep app logged in

Important: Instagram v313 doesn't have "Recent" tab, so bot uses "Top" tab for hashtags.

# Quick 3-minute test session
python test_like.py

Expected Results:

• 8 interactions total
• 2-3 likes
• 0-1 follows
• 0-1 story watches
• Duration: ~3-8 minutes
• Automatic filtering of private/empty accounts

accounts/test_like_enhanced.yml - Generated by test_like.py

• 3-minute test sessions
• Mix of hashtag likers + competitor post likers
• Enhanced human-like behavior
• Debug mode enabled

Daily Growth - accounts/strategy_growth.yml

# Target competitor post likers
blogger-post-likers: [realpython, freecodecamp, thepracticaldev]

# Daily limits (conservative)
total-likes-limit: 100
total-follows-limit: 30
total-interactions-limit: 150

# Human-like behavior
speed-multiplier: 0.85
likes-count: 1-3
follow-percentage: 35

Weekly Cleanup - accounts/strategy_cleanup.yml

# Unfollow non-mutuals
unfollow-non-followers: 150
unfollow-delay: 5

# Protect whitelisted accounts
whitelist:
  - important_account_1
  - important_account_2

accounts/filters.yml - Quality filtering

skip_business: true
skip_if_private: true
min_followers: 50
max_followers: 5000
min_posts: 3

python test_like.py

• Generates test config automatically
• Runs 3-minute session
• Logs to logs/gramaddict_test_like.log
• Check results in logs/maxhaider.dev.log

# Daily growth strategy
python runner.py growth

# Weekly cleanup
python runner.py cleanup

# Activate virtual environment first
.venv\Scripts\activate

# Run specific config
gramaddict run --config accounts/strategy_growth.yml

Log Locations:

• Test runs: logs/gramaddict_test_like.log
• Session logs: logs/maxhaider.dev.log (or your username)
• Crashes: crashes/latest/

Monitoring Progress:

# Watch live updates
powershell -Command "Get-Content logs/maxhaider.dev.log -Wait -Tail 50"

# Check last session stats
powershell -Command "Get-Content logs/maxhaider.dev.log -Tail 100 | Select-String -Pattern 'TOTAL|Session finished'"

• total-interactions-limit: 8 - Stop after N interactions (controls duration)
• total-likes-limit: 6 - Maximum likes per session
• total-follows-limit: 2 - Maximum follows per session
• total-sessions: 3 - Number of sessions to run

• speed-multiplier: 0.75 - Overall speed (<1 = slower, >1 = faster)
• likes-count: 1-3 - Like 1-3 posts per user (randomized)
• likes-percentage: 50-80 - Like 50-80% of the time
• follow-percentage: 30-50 - Follow 30-50% of interacted users
• watch-video-time: 5-30 - Watch videos 5-30 seconds
• watch-photo-time: 2-6 - Watch photos 2-6 seconds
• stories-count: 0-2 - Watch 0-2 stories per user
• stories-percentage: 20-50 - Watch stories 20-50% of the time

• hashtag-likers-top: [python, django, fastapi] - Top post likers
• blogger-post-likers: [realpython, freecodecamp] - Competitor post likers
• blogger-followers: [username1, username2] - Follower lists
• blogger-following: [username1, username2] - Following lists

GramAddict v3.2.12 uses FLAT YAML format:

• ❌ NO jobs: wrapper
• ❌ NO time-limit parameter
• ✅ Use total-interactions-limit for session duration

• Already-liked detection - Built-in, skips liked posts automatically
• Action delays - Built-in randomization, use speed-multiplier to adjust
• Range randomization - All ranges (e.g., 1-3) are automatically randomized

• Recommended: v313 (tested and working)
• Issues: v408+ may have UI changes causing crashes
• Note: v313 lacks "Recent" tab, bot uses "Top" tab instead

• Physical Device (Mi A3): Recommended, more stable, no emulator overhead
• MEmu Emulator: Alternative, official GramAddict recommendation
• BlueStacks 5: Not recommended, UIAutomator2 compatibility issues

Error: Unknown arguments: --interact-blogger-post-likers Fix: Use correct parameter name blogger-post-likers (not interact-blogger-post-likers)

# Check device connection
adb devices

# Reconnect if needed (USB devices auto-connect)
# For emulators only:
adb connect 127.0.0.1:21533

• Verify Instagram is installed: adb shell pm list packages | findstr instagram
• Check app version: Should be v313 or compatible
• Ensure Instagram is logged in manually first

• Normal: 60-75% rejection rate for private/empty accounts
• Expected: 2-3 successful interactions out of 8 attempts
• Review: Check logs/maxhaider.dev.log for filter decisions

• Shorter: Reduce total-interactions-limit
• Longer: Increase total-interactions-limit
• Rule of thumb: Each interaction = ~10-60 seconds

instabot/
├── accounts/                      # Configuration files
│   ├── test_like_enhanced.yml    # Auto-generated test config
│   ├── strategy_growth.yml       # Daily growth strategy
│   ├── strategy_cleanup.yml      # Weekly cleanup strategy
│   └── filters.yml               # Quality filters
├── docs/                          # Documentation
│   └── phase2-targeted-growth.md # Detailed strategy guide
├── logs/                          # Session logs (gitignored)
├── crashes/                       # Crash dumps (gitignored)
├── test_like.py                   # Test runner script
├── runner.py                      # Production task selector
├── .env                           # Environment variables (gitignored)
├── requirements.txt               # Python dependencies
├── CLAUDE.md                      # Claude Code guidance
└── README.md                      # This file

• Likes: 100-150 per day
• Follows: 20-50 per day
• Unfollows: 100-150 per day
• Sessions: 3-5 per day

1. Start slow: Use test sessions for first week
2. Monitor logs: Check for warning messages
3. Respect limits: Don't exceed recommended daily limits
4. Use filters: Maintain high-quality interactions
5. Vary timing: Don't run at exact same times daily
6. Human patterns: Avoid running 24/7

Always maintain strict filters to avoid:

• Spam/bot accounts
• Business accounts
• Empty profiles
• Low-quality followers

This is a personal automation project. For issues or improvements:

1. Review logs first
2. Check GramAddict documentation
3. Test with debug mode enabled
4. Share detailed error logs

This project uses GramAddict (open source). Review GramAddict's license and Instagram's Terms of Service before use.

Use at your own risk. Automated Instagram interactions may violate Instagram's Terms of Service. This bot is for educational purposes and personal use only. The authors are not responsible for any account restrictions or bans.

• GramAddict Documentation
• GramAddict GitHub
• Configuration Examples
• Project Documentation: docs/phase2-targeted-growth.md