🦀 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
  • Platform Support
  • Automation Capabilities
  • Integration Options
• Architecture
• Workflow
  • Human Simulation
  • Automation Best Practices
• Security
• Installation
  • Prerequisites
  • Quick Start (Human)
  • AI Agent Instructions
  • Docker
• Usage
  • CLI Commands
  • REST API Examples
  • Programmatic Usage
• API Reference
• Configuration
  • Environment Variables
  • Rate Limits
• Disclaimer
• Contributing
• License

---

✨ Features

Platform Support

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

---

🏗️ 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   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

1. Warm-up: Scrolls feed 3-5 times with random pauses (mimics checking notifications)
2. Navigate: Goes to target with natural page load timing
3. Think: Pauses 2-5s (simulates reading/deciding)
4. 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     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

1. Research First: Scrape or search to build a queue of targets before engaging
2. Store Results: Save to JSON/database — never scrape and act in the same session
3. Spread Actions: Distribute engagement across multiple cron jobs throughout the day
4. Repeat When Needed: Re-run research periodically to refresh your queue

Platform-Specific Guidelines

⚠️ 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:

1. Agent reads the content — tweet, article, post
2. Agent reads VOICE.md — your personal style guide
3. Agent generates unique comment — references something specific
4. 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

---

📦 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!)
# ⚠️ 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:
AUTH_TOKEN=your_auth_token
CT0=your_ct0_token
#
# 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

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

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

LinkedIn Endpoints

Twitter Endpoints

System Endpoints

---

⚙️ Configuration

Environment Variables

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)

Week 1 Warm-Up Limits (New Accounts)

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

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.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---