🎯 Twitter Sniper v13

Autonomous Twitter/X engagement engine for open source growth

Twitter Sniper is a drip-mode engagement engine that autonomously promotes your open source repos on Twitter/X.
It uses AI to craft genuine, context-aware replies — not spam. One micro-action at a time, spread across the day like a real human.

Getting Started · How It Works · Configuration · Architecture

---

✨ Features

Feature	Description
🤖 AI-Powered Content	Gemini Flash generates context-aware tweets, replies, and quote tweets
💧 Drip Mode	One micro-action per run — no burst behavior, pure organic pacing
🔵 Verified-Only Follows	Only follows blue-check accounts for quality network growth
🕐 Fresh Content Only	Engages only with tweets < 24 hours old — no necro-posting
🧠 Topic Matching	Maps conversation topics to relevant repos automatically
🚫 Anti-Spam Guard	Banned phrases, anti-repetition, language enforcement
📡 Trend Discovery	Uses Brave Search to find trending conversations in your niche
😴 Organic Sleep	Random pauses, dead-hour detection, anti-burst throttling
📊 Daily Tracking	Tracks likes, replies, follows, tweets, and quote tweets per day

🚀 Getting Started

Prerequisites

• Node.js 18+
• Google Chrome with remote debugging enabled
• Twitter/X account logged in on Chrome
• Gemini API key (get one free)
• Brave Search API key (get one here)

Installation

# Clone the repo
git clone https://github.com/SovranAMR/twitter-sniper.git
cd twitter-sniper

# Install dependencies
npm install

# Configure your environment
cp .env.example .env
# Edit .env with your API keys and Twitter username

Start Chrome with Remote Debugging

google-chrome --remote-debugging-port=18800

Make sure you're logged into Twitter/X in that Chrome instance.

Run

# Dry run (no real actions — safe testing)
npm run dry-run

# Test specific actions
npm run test:like
npm run test:reply
npm run test:tweet
npm run test:follow
npm run test:quote

# Live run (real engagement)
npm start

# Force a specific action
node src/sniper.mjs --action=tweet

Set Up Cron (Autonomous Mode)

# Run every 8 minutes — the engine handles organic pacing internally
crontab -e

# Add this line:
*/8 * * * * cd /path/to/twitter-sniper && node src/sniper.mjs >> /tmp/sniper.log 2>&1

🧠 How It Works

The Drip Strategy

Unlike traditional bots that spam 50 tweets in a minute, Sniper uses drip mode — one micro-action per execution, spread naturally across the day:

06:00 ─── 😴 sleep
06:08 ─── ❤️ like (3 tweets)
06:16 ─── 😴 sleep (organic gap)
06:24 ─── 💬 reply (with repo link)
06:32 ─── 😴 sleep
06:40 ─── ❤️ like (2 tweets)
06:48 ─── 📝 tweet (mentions repo)
...

Action Distribution

The engine picks actions based on time of day:

Time	Behavior
01:00–06:00	85% sleep, 15% light likes
06:00–09:00	More likes, fewer heavy interactions
09:00–12:00	Peak — more replies, quotes, tweets
12:00–14:00	Normal mix
14:00–18:00	Peak — aggressive engagement
18:00–01:00	Normal mix with organic gaps

Content Generation Pipeline

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Brave Search │────▶│ Trend Queries │────▶│ Twitter      │
│ (news/trends)│     │ (via Gemini) │     │ Search (live)│
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                          ┌───────▼───────┐
                                          │  Tweet Filter  │
                                          │  - Fresh (<24h)│
                                          │  - Not liked   │
                                          │  - Min engage  │
                                          └───────┬───────┘
                                                  │
                      ┌───────────────────────────▼───────────────────┐
                      │              Action Router                     │
                      ├──────┬──────┬──────┬──────┬──────────────────┤
                      │ Like │Reply │Quote │Follow│ Tweet             │
                      │      │(AI)  │(AI)  │(✓)   │ (AI + repo link) │
                      └──────┴──────┴──────┴──────┴──────────────────┘

Anti-Spam Safeguards

• Language Lock: English only — Turkish/Arabic auto-detected and blocked
• Banned Phrases: "check this out", "game-changer", "mind blown", etc.
• Anti-Repetition: Hash-based dedup prevents engaging same tweet twice
• Hashtag Limit: Max 1 hashtag per post (prefer zero)
• Verified-Only Follows: Won't follow non-blue-check accounts
• Organic Gaps: Random sleep cycles between actions

⚙️ Configuration

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	✅	Google Gemini API key for content generation
BRAVE_API_KEY	✅	Brave Search API key for trend discovery
CDP_URL	❌	Chrome DevTools Protocol URL (default: http://127.0.0.1:18800)
TWITTER_USERNAME	❌	Your Twitter handle without @ (default: your_username)
MAX_TWEET_AGE_HOURS	❌	Max tweet age to engage with (default: 24)

Customizing Repos

Edit the REPOS object in src/sniper.mjs:

const REPOS = {
  myproject: {
    url: 'https://github.com/you/project',
    short: 'github.com/you/project',
    name: 'My Project',
    desc: 'what it does in one line'
  },
};

Topic-to-Repo Mapping

Map conversation topics to your repos for intelligent matching:

const TOPIC_REPO_MAP = {
  'AI agent': 'myproject',
  'automation': 'myproject',
  'neural network': 'myotherproject',
};

Knowledge Base

Create a kb/ directory with text files for each repo. The engine uses these for context-aware content:

mkdir kb
echo "Technical details about your project..." > kb/myproject.txt

🏗️ Architecture

twitter-sniper/
├── src/
│   └── sniper.mjs          # Main engine (930 LOC)
├── data/                    # Runtime state & logs (gitignored)
│   ├── state.json           # Daily counters & engagement history
│   ├── tweets.log           # Posted tweets
│   ├── engagements.log      # Likes, replies, quotes
│   ├── follows.log          # Followed accounts
│   └── drip.log             # Action timeline
├── kb/                      # Knowledge base (gitignored)
├── .env                     # API keys (gitignored)
├── .env.example             # Template for .env
├── .gitignore
├── package.json
├── LICENSE
└── README.md

Core Modules

Module	Lines	Description
Language Enforcement	~25	Turkish char/word detection, English-only filter
Anti-Repetition	~30	Banned phrases, hash dedup, hashtag limiter
State Management	~30	Daily reset, JSON persistence, engagement tracking
Gemini AI	~25	Content generation with retry logic
Brave Search	~12	Trend discovery with freshness filter
Browser (Playwright)	~120	Twitter search, like, reply, follow, post, quote
Trend Discovery	~50	AI-powered query generation from news
Action Picker	~35	Time-of-day weighted random selection
Drip Actions	~300	Like, Reply, Quote, Follow, Tweet implementations

📈 Expected Daily Output

With */8 * * * * cron schedule:

Metric	~Daily
❤️ Likes	40-80
💬 Replies	8-15
🔄 Quotes	3-8
👤 Follows	3-8 (verified only)
📝 Tweets	5-12 (each with repo link)
😴 Sleep cycles	~35% of runs

⚠️ Disclaimer

This tool automates Twitter/X engagement. Use responsibly:

• Respect Twitter's Terms of Service
• Don't spam — the drip mode exists for a reason
• Monitor your account — adjust frequency if needed
• Be genuine — the AI generates real insights, not template spam

📄 License

MIT — do whatever you want with it.

---

Built with 🔥 by SovranAMR

"The best marketing is a great product. The second best is telling people about it — one conversation at a time."