🦀 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

Features
Architecture
Workflow
- Human Simulation
- Automation Best Practices
Security
Installation
Usage
API Reference
Configuration
- Environment Variables
- Rate Limits
Disclaimer
Contributing
License

✨ 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
- Warm-up browsing (scrolls feed before actions)
- Randomized delays (1.5-4s between actions)
- Natural typing speed (30-100ms per character)
- Thinking pauses (2-5s before complex actions)
- Action cooldown (2-3 min between multiple actions)
🛡️ Safety Features
- Built-in rate limiting per platform
- Session persistence across restarts
- Stealth mode (anti-detection measures)
- Automatic error recovery with exponential backoff
- Text sanitization: Auto-cleans em-dashes, en-dashes, and other style violations before posting on all platforms
📊 Platform-Specific
- Instagram: Follower scraping, post engagement, DMs
- LinkedIn: Connection requests (including 3rd degree via More dropdown), post engagement, search & engage
- Twitter/X: Tweet posting, likes, replies, follows

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.txt

See 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 use node dist/cli.js instead of npm run cli --. Build first with npm 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

See 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
INSTAGRAM_USERNAME=your_username
INSTAGRAM_PASSWORD="your_password"

# LinkedIn (supports MFA - approve in app when prompted)
LINKEDIN_EMAIL=your_email
LINKEDIN_PASSWORD="your_password"

# Twitter/X - Cookie auth (required for ALL methods!)
# ⚠️ IMPORTANT: Twitter requires COOKIE auth, NOT username/password!
# Get cookies from browser:
# 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
# 4. Save them to sessions/twitter.json (see below) OR set as env vars:
AUTH_TOKEN=your_auth_token
CT0=your_ct0_token

# ⚠️ DO NOT use username/password - Twitter blocks API login!
# The session will fail with "login" or "auth" errors if you use wrong method.

# 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 instagram

Instagram

npm 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 username

LinkedIn

npm 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 username

Twitter

npm 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 username

Notifications

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 \
  --context='{"author":"@username","preview":"Tweet text here","language":"en"}'

Global CLI Flags

Flag	Description	Example
`--retries <n>`	Retry failed actions (1-10, default: 3)	`--retries 5`
`--context '<json>'`	Pass JSON context to notifications	`--context='{"author":"@user"}'`

The --context flag accepts JSON with these optional fields:

author — Username/handle of content author
preview — First ~100 chars of content
language — 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
`BROWSER_DATA_DIR`	./browser-data	Browser profile directory
`SESSION_DIR`	./sessions	Session storage directory
`DELAY_MIN_MS`	1500	Minimum delay between actions
`DELAY_MAX_MS`	4000	Maximum delay between actions
`TYPING_SPEED_MIN_MS`	30	Min typing delay per character
`TYPING_SPEED_MAX_MS`	100	Max typing delay per character

Platform Credentials

# Instagram
INSTAGRAM_USERNAME=your_username
INSTAGRAM_PASSWORD="your_password"

# LinkedIn
LINKEDIN_EMAIL=your_email
LINKEDIN_PASSWORD="your_password"

# Twitter (optional)
TWITTER_USERNAME=your_username
TWITTER_PASSWORD="your_password"

⚠️ 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	`RATE_LIMIT_INSTAGRAM_LIKE`
Instagram	Comment	30/day	`RATE_LIMIT_INSTAGRAM_COMMENT`
Instagram	Follow	50/day	`RATE_LIMIT_INSTAGRAM_FOLLOW`
Instagram	DM	50/day	`RATE_LIMIT_INSTAGRAM_DM`
LinkedIn	Like	100/day	`RATE_LIMIT_LINKEDIN_LIKE`
LinkedIn	Comment	30/day	`RATE_LIMIT_LINKEDIN_COMMENT`
LinkedIn	Connect	15/day	`RATE_LIMIT_LINKEDIN_CONNECT`
LinkedIn	Message	40/day	`RATE_LIMIT_LINKEDIN_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
`NOTIFY_TELEGRAM_BOT_TOKEN`	-	Telegram bot token
`NOTIFY_TELEGRAM_CHAT_ID`	-	Telegram chat ID to send to
`NOTIFY_DISCORD_WEBHOOK`	-	Discord webhook URL
`NOTIFY_WEBHOOK_URL`	-	Custom webhook URL
`NOTIFY_WEBHOOK_METHOD`	POST	Webhook HTTP method
`NOTIFY_WEBHOOK_HEADERS`	-	JSON headers for webhook
`NOTIFY_BRAND_FOOTER`	SocialCrabs Automation	Footer text for notifications
`NOTIFY_ON_COMPLETE`	true	Notify on action success
`NOTIFY_ON_ERROR`	true	Notify on action failure
`NOTIFY_ON_LOGIN`	false	Notify on login events
`NOTIFY_ON_RATELIMIT`	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
NOTIFY_TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
NOTIFY_TELEGRAM_CHAT_ID=7711740248
NOTIFY_BRAND_FOOTER="*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

This project is similar to other browser automation tools (Playwright, Puppeteer, Selenium) used for testing and research. It is not a commercial service.

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

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

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)

Folders and files

Latest commit

History

Repository files navigation

🦀 SocialCrabs

📑 Table of Contents

✨ Features

Platform Support

Automation Capabilities

Integration Options

🏗️ Architecture

🔄 Workflow

Human Simulation

Automation Best Practices

Platform-Specific Guidelines

Agent-Driven Comments (CRITICAL)

How It Works:

VOICE.md Example:

Comment Storage:

🔐 Security

📦 Installation

Prerequisites

Quick Start (Human)

⚠️ Important Notice

🤖 AI Agent Instructions

Quick Commands

🔄 Autonomous Engagement

Required Environment Variables

Session Files

Multi-Action Sequences

Docker

🚀 Usage

CLI Commands

Session Management

Instagram

LinkedIn

Twitter

Notifications

Global CLI Flags

REST API Examples

Programmatic Usage

📡 API Reference

Instagram Endpoints

LinkedIn Endpoints

Twitter Endpoints

System Endpoints

⚙️ Configuration

Environment Variables

Platform Credentials

Rate Limits

Production Limits (After 5-Week Warm-Up)

Week 1 Warm-Up Limits (New Accounts)

Action Timing Rules

Notifications

Notification Environment Variables

Example .env for Telegram Notifications

⚖️ Disclaimer

🤝 Contributing

📄 License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages