SocialCrabs is a robust, web-based automation tool built with Playwright. It simulates human-like behavior to interact with Instagram, Twitter/X, and LinkedIn safely and efficiently. Give it to your OpenCrabs and watch the magic happen! Compatible with OpenClaw
🦀 SocialCrabs
Web-based social media automation tool with human-like behavior simulation built with Playwright
Post, like, comment, follow/connect, unfollow and DM on Instagram, Twitter/X, and LinkedIn. Reddit is comming soon!
Features • Architecture • Workflow • Installation • Usage • API • Configuration
📑 Table of Contents
- Platform Support - Automation Capabilities - Integration Options - Human Simulation - Automation Best Practices - Prerequisites - Quick Start (Human) - AI Agent Instructions - Docker - CLI Commands - REST API Examples - Programmatic Usage - Environment Variables - Rate Limits✨ Features
Platform Support
| Platform | Login | Like | Comment | Follow | DM | Connect | Search | Status | |----------|:-----:|:----:|:-------:|:------:|:--:|:-------:|:------:|--------| | Instagram | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | Production Ready | | LinkedIn | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Production Ready | | Twitter/X | ✅ | ✅ | ✅ | ✅ | ❌ | — | ✅ | Production Ready | | Reddit | 🔜 | 🔜 | 🔜 | 🔜 | 🔜 | — | — | Planned |
Status Key: "Production Ready" = tested & verified. "Implemented" = code complete. "Planned" = on roadmap.
Automation Capabilities
- 🤖 Human-like Behavior
- 🛡️ Safety Features
- 📊 Platform-Specific
Integration Options
| Interface | Description | |-----------|-------------| | CLI | Command-line interface for quick actions | | REST API | Full HTTP API on port 3847 | | WebSocket | Real-time bidirectional communication on port 3848 | | Programmatic | TypeScript/JavaScript SDK | | Notifications | Telegram, Discord, or webhook notifications on action completion |
🏗️ Architecture
┌─────────────────────────────────────────────────────────────┐
│ SocialCrabs │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ CLI │ │ REST │ │ WS │ Interfaces │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ └────────────┼────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ Command Router │ │
│ └─────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ Rate Limiter │ │
│ └─────────────────┬───────────────────┘ │
│ ▼ │
│ ┌──────────┬──────────┬──────────┐ │
│ │Instagram │ LinkedIn │ Twitter │ Platform Handlers │
│ └────┬─────┴────┬─────┴────┬─────┘ │
│ │ │ │ │
│ └──────────┼──────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ Browser Manager │ │
│ │ (Playwright + Stealth Mode) │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘Key Components:
- Interfaces: Multiple ways to interact (CLI, REST, WebSocket)
- Command Router: Routes requests to appropriate handlers
- Rate Limiter: Enforces daily limits per platform/action
- Platform Handlers: Instagram, LinkedIn, Twitter-specific logic
- Browser Manager: Playwright with stealth mode and session persistence
🔄 Workflow
Human Simulation
SocialCrabs automatically simulates human behavior for every action:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Warm-up │ ──▶ │ Navigate │ ──▶ │ Think │ ──▶ │ Action │
│ (3-5 scrolls) │ to Target │ │ (2-5s) │ │ + Typing │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘- Warm-up: Scrolls feed 3-5 times with random pauses (mimics checking notifications)
- Navigate: Goes to target with natural page load timing
- Think: Pauses 2-5s (simulates reading/deciding)
- Action: Performs action with natural typing speed (30-100ms/char)
Automation Best Practices
Follow this research-first workflow to avoid rate limits and bans:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Research │ ──▶ │ Store │ ──▶ │ Spread │ ──▶ │ Repeat │
│ (scrape/ │ │ Results │ │ Actions │ │ When │
│ search) │ │ (JSON/DB) │ │ Over Time │ │ Needed │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘- Research First: Scrape or search to build a queue of targets before engaging
- Store Results: Save to JSON/database — never scrape and act in the same session
- Spread Actions: Distribute engagement across multiple cron jobs throughout the day
- Repeat When Needed: Re-run research periodically to refresh your queue
Platform-Specific Guidelines
| Platform | Scraping | Notes | |----------|----------|-------| | LinkedIn | ⚠️ Very strict | Search keywords → store HTML → extract results → then engage. Small batches only. Direct profile URLs are safer than search scraping. | | Instagram | ⚠️ Careful | Scrape followers or hashtags slowly in small batches (5-10 per session). Wait hours between scrape sessions. | | Twitter/X | ✅ Built-in GraphQL | Use x search for research. Less restrictive but still pace yourself. |
⚠️ Golden Rule: Never scrape and engage in the same session. Research in one job, engage in separate jobs spread over hours.
Agent-Driven Comments (CRITICAL)
Never use hardcoded comment templates. The whole point of having an AI agent is dynamic, contextual responses.
How It Works:
- Agent reads the content — tweet, article, post
- Agent reads VOICE.md — your personal style guide
- Agent generates unique comment — references something specific
- Comment is logged — prevents repetition
VOICE.md Example:
## Core Rules
- 8th grade reading level
- Max 2 sentences, 10-25 words
- Ask questions when natural
✅ DO
"That's wild. What stack are you running?"
"Spot on 💯"
"Smart move. Did it work first try?"
❌ DON'T
"Fascinating approach!"
"Great insights!"
"This is fire! 🔥"Comment Storage:
# Log to avoid repetition
echo "2026-02-06 15:30 | @user | Your comment" >> ~/clawd/x-comments.txtSee src/examples/CRONJOB_TEMPLATE.md for full workflow.
🔐 Security
| Feature | Description | |---------|-------------| | No Hardcoded Credentials | All secrets via environment variables | | Session Encryption | Optional encryption for stored cookies | | Local Binding | Server binds to 127.0.0.1 by default | | API Authentication | Optional API key for remote access | | Stealth Mode | Browser fingerprint protection, anti-bot detection | | Rate Limiting | Prevents accidental platform bans |
📦 Installation
Prerequisites
- Node.js 24+ (LTS)
- npm or pnpm
Quick Start (Human)
# Clone the repository
git clone https://github.com/adolfousier/socialcrabs.git
cd socialcrabs
Install dependencies
npm install
Install Playwright browsers
npx playwright install chromium
Copy environment file and configure
cp .env.example .env
Edit .env with your credentials
Build
npm run build
Start server
npm start⚠️ Important Notice
This software is for educational and experimental purposes only.
Expect this tool to break without further notice. Follow AUTOMATION_RULES.md for best performance>
Read AUTOMATION_RULES.md before using.>
| Platform | Status |
|----------|--------|
| Instagram | 🟡 Production - use responsibly |
| LinkedIn | 🟡 Production - use responsibly |
| Twitter/X | 🟡 Production - use responsibly (likes, follows, replies via Playwright; search/read via built-in GraphQL client) |
🤖 AI Agent Instructions
For AI agents (OpenClaw, Claude, etc.) — Here's how to use SocialCrabs:
⚠️ Always usenode dist/cli.jsinstead ofnpm run cli --. Build first withnpm run build. The tsx runtime adds overhead and causes browser launch hangs under load.
Quick Commands
# Build first (required once after code changes)
npm run build
Login (headless - uses .env credentials)
node dist/cli.js session login <platform>
Check session status
node dist/cli.js session status
Instagram
node dist/cli.js ig like <post-url>
node dist/cli.js ig comment <post-url> "Your comment"
node dist/cli.js ig dm <username> "Your message"
node dist/cli.js ig follow <username>
node dist/cli.js ig followers <username> -n 10 # Scrape followers
node dist/cli.js ig posts <username> -n 3 # Get recent posts
LinkedIn
node dist/cli.js linkedin like <post-url>
node dist/cli.js linkedin comment <post-url> "Your comment"
node dist/cli.js linkedin dm <profile-url> "Your message"
node dist/cli.js linkedin connect <profile-url> # Works for 3rd degree too
node dist/cli.js linkedin search <query> # Search posts/articles
node dist/cli.js linkedin engage --query=<query> # Full engagement session
Twitter/X - Write (Playwright)
node dist/cli.js x like <tweet-url>
node dist/cli.js x tweet "Your tweet"
node dist/cli.js x follow <username>
node dist/cli.js x reply <tweet-url> "Your reply"
Twitter/X - Read (GraphQL, no browser needed)
node dist/cli.js x search "query" -n 10 # Search tweets
node dist/cli.js x home -n 5 # Home timeline
node dist/cli.js x mentions -n 5 # Your mentions
node dist/cli.js x whoami # Show authenticated account
node dist/cli.js x read <tweet-url> # Read a specific tweet
node dist/cli.js x search "query" --json # JSON output for automation🔄 Autonomous Engagement
SocialCrabs supports fully autonomous engagement when paired with an AI agent scheduler (e.g., OpenClaw cron):
- Auto-replenish: When content pool runs dry, jobs automatically scrape fresh content
- Session monitoring: Cron checks session health every 6h, triggers re-auth if expired
- User alerts: Agent pings all channels when 2FA approval is needed
- Self-healing: After user approves auth, jobs resume automatically
src/docs/CRONJOB_TEMPLATE.md for the full autonomous engagement playbook with cron schedules, auto-replenish scripts, and session health checks.
Required Environment Variables
# Instagram
INSTAGRAMUSERNAME=yourusername
INSTAGRAMPASSWORD="yourpassword"
LinkedIn (supports MFA - approve in app when prompted)
LINKEDINEMAIL=youremail
LINKEDINPASSWORD="yourpassword"
Twitter/X - Cookie auth (required!)
⚠️ IMPORTANT: Twitter requires COOKIE auth, NOT username/password!
#
TWO OPTIONS - Pick ONE:
#
OPTION 1 (RECOMMENDED): Just set env vars - sessions/twitter.json will be auto-generated!
1. Open x.com in Chrome/Edge (logged in as your account)
2. Open DevTools (F12) → Application tab → Cookies → x.com
3. Copy the "auth_token" and "ct0" values (the token strings, NOT the whole cookie)
4. Add to .env:
AUTHTOKEN=yourauth_token
CT0=yourct0token
#
That's it! SocialCrabs will auto-create sessions/twitter.json on first run.
#
OPTION 2: Manual session file - create sessions/twitter.json with full cookie objects
(see sessions/twitter.json.example in docs)
#
⚠️ DO NOT use username/password - Twitter blocks API login!
Twitter/X - Uses COOKIES (see section above)
Session Files
| Path | Description | |------|-------------| | ./sessions/{platform}.json | Stored session cookies | | ./browser-data/ | Browser profile data | | ./sessions/debug-*.png | Debug screenshots | | ./db/ | State files (engaged profiles, etc.) |
Multi-Action Sequences
When performing multiple actions on the same profile (e.g., DM then comment), SocialCrabs automatically applies a 2-3 minute cooldown between actions.
Docker
# Build image
docker build -t socialcrabs .
Run container
docker run -d \
--name socialcrabs \
-p 3847:3847 \
-p 3848:3848 \
-v $(pwd)/sessions:/app/sessions \
-v $(pwd)/browser-data:/app/browser-data \
--env-file .env \
socialcrabs🚀 Usage
CLI Commands
Session Management
# Interactive login (opens browser)
npm run cli -- session login instagram
Headless login (uses .env credentials)
npm run cli -- session login linkedin --headless
Check all sessions
npm run cli -- session status
Logout
npm run cli -- session logout instagramnpm run cli -- ig like https://instagram.com/p/ABC123
npm run cli -- ig comment https://instagram.com/p/ABC123 "Great post!"
npm run cli -- ig follow username
npm run cli -- ig dm username "Hello!"
npm run cli -- ig followers username -n 10
npm run cli -- ig posts username -n 5
npm run cli -- ig profile usernamenpm run cli -- linkedin like https://linkedin.com/posts/xxx
npm run cli -- linkedin comment https://linkedin.com/posts/xxx "Insightful!"
npm run cli -- linkedin connect https://linkedin.com/in/username
npm run cli -- linkedin dm https://linkedin.com/in/username "Hi there"
npm run cli -- linkedin search "AI automation"
npm run cli -- linkedin engage --query="OpenClaw"
npm run cli -- linkedin profile usernamenpm run cli -- twitter like https://twitter.com/user/status/123
npm run cli -- twitter tweet "Hello world!"
npm run cli -- twitter reply https://twitter.com/user/status/123 "Great point!"
npm run cli -- twitter follow usernameNotifications
npm run cli -- notify status # Check notification config
npm run cli -- notify test # Send test notification
npm run cli -- notify test telegram # Test specific channel
npm run cli -- notify send "Your message" # Send custom message
Agent-friendly: Send formatted notification with context
npm run cli -- notify report twitter like https://twitter.com/user/status/123 \
--cGlobal CLI Flags
| Flag | Description | Example | |------|-------------|---------| | --retries <n> | Retry failed actions (1-10, default: 3) | --retries 5 | | --context '<json>' | Pass JSON context to notifications | --c |
The --context flag accepts JSON with these optional fields:
author— Username/handle of content authorpreview— First ~100 chars of contentlanguage— Content language (en/es/pt)behaviors— Actions taken (e.g., "Home feed viewed, search performed")
REST API Examples
# Like an Instagram post
curl -X POST http://localhost:3847/api/instagram/like \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"url": "https://instagram.com/p/ABC123"}'
Send LinkedIn connection
curl -X POST http://localhost:3847/api/linkedin/connect \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"profileUrl": "https://linkedin.com/in/username"}'
Get rate limit status
curl http://localhost:3847/api/status \
-H "X-API-Key: your-api-key"Programmatic Usage
import { SocialCrabs } from 'socialcrabs';
const claw = new SocialCrabs({ headless: true, sessionDir: './sessions', });
await claw.initialize();
// Instagram const ig = claw.instagram; await ig.login(); await ig.like('https://instagram.com/p/ABC123'); await ig.follow('username'); await ig.comment('https://instagram.com/p/ABC123', 'Nice!');
// LinkedIn const linkedin = claw.linkedin; await linkedin.login(); await linkedin.connect('https://linkedin.com/in/username');
// Cleanup await claw.shutdown();
📡 API Reference
Instagram Endpoints
| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/instagram/like | Like a post | | POST | /api/instagram/comment | Comment on a post | | POST | /api/instagram/follow | Follow a user | | POST | /api/instagram/unfollow | Unfollow a user | | POST | /api/instagram/dm | Send a direct message | | GET | /api/instagram/profile/:username | Get profile data |
LinkedIn Endpoints
| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/linkedin/like | Like a post | | POST | /api/linkedin/comment | Comment on a post | | POST | /api/linkedin/connect | Send connection request | | POST | /api/linkedin/message | Send a message | | GET | /api/linkedin/profile/:username | Get profile data |
Twitter Endpoints
| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/twitter/like | Like a tweet | | POST | /api/twitter/tweet | Post a tweet | | POST | /api/twitter/reply | Reply to a tweet | | POST | /api/twitter/retweet | Retweet | | POST | /api/twitter/follow | Follow a user |
System Endpoints
| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/status | System and rate limit status | | GET | /api/health | Health check | | POST | /api/session/login/:platform | Initiate login | | POST | /api/session/logout/:platform | Logout |
⚙️ Configuration
Environment Variables
| Variable | Default | Description | |----------|---------|-------------| | PORT | 3847 | HTTP server port | | WS_PORT | 3848 | WebSocket server port | | HOST | 127.0.0.1 | Server bind address | | LOG_LEVEL | info | Logging level | | BROWSER_HEADLESS | true | Run browser headless | | BROWSERDATADIR | ./browser-data | Browser profile directory | | SESSION_DIR | ./sessions | Session storage directory | | DELAYMINMS | 1500 | Minimum delay between actions | | DELAYMAXMS | 4000 | Maximum delay between actions | | TYPINGSPEEDMIN_MS | 30 | Min typing delay per character | | TYPINGSPEEDMAX_MS | 100 | Max typing delay per character |
Platform Credentials
# Instagram
INSTAGRAMUSERNAME=yourusername
INSTAGRAMPASSWORD="yourpassword"
LinkedIn
LINKEDINEMAIL=youremail
LINKEDINPASSWORD="yourpassword"
Twitter (optional)
TWITTERUSERNAME=yourusername
TWITTERPASSWORD="yourpassword"⚠️ Note: For passwords with special characters, wrap in quotes: PASSWORD="my*pass(word"
Rate Limits
⚠️ Important: New accounts need a warm-up period. See Warm-Up Guide for the full 5-week scaling schedule.
Production Limits (After 5-Week Warm-Up)
| Platform | Action | Default | Env Variable | |----------|--------|---------|--------------| | Instagram | Like | 100/day | RATELIMITINSTAGRAM_LIKE | | Instagram | Comment | 30/day | RATELIMITINSTAGRAM_COMMENT | | Instagram | Follow | 50/day | RATELIMITINSTAGRAM_FOLLOW | | Instagram | DM | 50/day | RATELIMITINSTAGRAM_DM | | LinkedIn | Like | 100/day | RATELIMITLINKEDIN_LIKE | | LinkedIn | Comment | 30/day | RATELIMITLINKEDIN_COMMENT | | LinkedIn | Connect | 15/day | RATELIMITLINKEDIN_CONNECT | | LinkedIn | Message | 40/day | RATELIMITLINKEDIN_MESSAGE |
Week 1 Warm-Up Limits (New Accounts)
| Action | Max/Day | |--------|---------| | Likes | 20 | | Comments | 14 | | Follows/Connects | 10 | | DMs | 10 |
Increase by 25% each week until reaching production limits at week 5.
Action Timing Rules
- Minimum 10 minutes between comments
- Minimum 15 minutes between connection requests
- Use odd minutes (:03, :17, :33, :51) not round numbers
- Vary gaps — don't make timing predictable
- Distribute actions across active hours (8am-10pm)
Notifications
SocialCrabs can send notifications via Telegram, Discord, or custom webhooks when actions complete or fail.
Notification Environment Variables
| Variable | Default | Description | |----------|---------|-------------| | NOTIFY_ENABLED | false | Enable notifications | | NOTIFYTELEGRAMBOT_TOKEN | - | Telegram bot token | | NOTIFYTELEGRAMCHAT_ID | - | Telegram chat ID to send to | | NOTIFYDISCORDWEBHOOK | - | Discord webhook URL | | NOTIFYWEBHOOKURL | - | Custom webhook URL | | NOTIFYWEBHOOKMETHOD | POST | Webhook HTTP method | | NOTIFYWEBHOOKHEADERS | - | JSON headers for webhook | | NOTIFYBRANDFOOTER | SocialCrabs Automation | Footer text for notifications | | NOTIFYONCOMPLETE | true | Notify on action success | | NOTIFYONERROR | true | Notify on action failure | | NOTIFYONLOGIN | false | Notify on login events | | NOTIFYONRATELIMIT | true | Notify on rate limit exceeded | | SOCIALCRABS_SILENT | - | Set to 1 to suppress auto-notifications (for combined reports) |
Example .env for Telegram Notifications
NOTIFY_ENABLED=true
NOTIFYTELEGRAMBOT_TOKEN=123456:ABC-DEF...
NOTIFYTELEGRAMCHAT_ID=7711740248
NOTIFYBRANDFOOTER="SocialCrabs LinkedIn Automation"⚖️ Disclaimer
This is an open-source experimental tool for educational and research purposes.
By using this software, you acknowledge:
- Automating interactions may violate platform Terms of Service
- You accept full responsibility for any account restrictions or bans
- You will not use this for spam, harassment, commercial services, or illegal activities
The authors are not responsible for any misuse or consequences of use.
🤝 Contributing
Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ by Adolfo Usier
