Twitter/X Following Cleanup

Clean up your Twitter following list automatically. Unfollow accounts outside your niche while protecting mutual follows.

Why?

A high following/follower ratio (e.g. 1000 following / 150 followers) signals "spam account" to visitors. Cleaning up to a healthy ratio (< 2:1) is one of the highest-leverage things you can do for follower growth.

Doing it manually takes hours. This script does it in ~20 minutes.

How It Works

1. Fetches your full Following list via Twitter's internal API
2. Fetches your Followers to detect mutual follows
3. Categorizes every account by name + bio keywords (AI, builder, tech, VC, design, etc.)
4. Protects mutuals and accounts in your chosen niche categories
5. Shows you the full plan — nothing is unfollowed until you confirm
6. Unfollows the rest with smart rate-limit handling

Quick Start

This is a single-file script. No installs, no dependencies, no build step.

Step 1: Copy the script

Open twitter-unfollow-cleanup.js and copy all the contents (Ctrl+A then Ctrl+C).

Step 2: Open the browser console on X

1. Go to x.com and make sure you are logged in
2. Open DevTools:
   • Chrome/Edge: Press F12 or Ctrl+Shift+J (Mac: Cmd+Option+J)
   • Firefox: Press F12 or Ctrl+Shift+K (Mac: Cmd+Option+K)
3. Click the Console tab

Step 3: Allow pasting (Chrome/Edge only)

Chrome blocks pasting in the console by default. You will see a warning like:

Warning: Don't paste code into the DevTools Console that you don't understand...

Type allow pasting and press Enter. This enables pasting for the current session.

Step 4: Paste and run

1. Paste the script (Ctrl+V) and press Enter
2. It auto-starts: runs a preflight check, fetches your accounts, categorizes them, and shows a plan
3. Review the plan:
   • tuc.showKeep() — see who you're keeping
   • tuc.showUnfollow() — see who will be unfollowed
4. When you're satisfied, type tuc.execute() and press Enter to start unfollowing

Commands

Command	Description
tuc.run()	Fetch accounts, categorize, show plan
tuc.execute()	Start unfollowing (only after reviewing the plan)
tuc.stop()	Pause mid-run
tuc.resume()	Continue from where you paused
tuc.status()	Check progress
tuc.showKeep()	Table of accounts being kept
tuc.showUnfollow()	Table of accounts to be unfollowed
tuc.exportUnfollowList()	Download unfollow list as JSON
tuc.preflight()	Re-run login/session check

Configuration

Edit the config before running, or modify it live via tuc.config:

// Categories to keep (accounts in these categories won't be unfollowed)
tuc.config.KEEP_CATEGORIES = ['ai', 'builder', 'tech', 'vc', 'design'];

// Add/remove categories dynamically
tuc.addKeepCategory('crypto');
tuc.removeKeepCategory('design');
tuc.recategorize(); // re-run with new config

// Timing (milliseconds)
tuc.config.UNFOLLOW_DELAY_MS = 8000;          // 8s between unfollows
tuc.config.RATE_LIMIT_COOLDOWN_MS = 720000;    // 12 min on rate limit

// Always protect mutual follows
tuc.config.ALWAYS_KEEP_MUTUALS = true;

Custom Niche Keywords

The script categorizes accounts by matching name + bio text against keyword lists. Customize tuc.config.CATEGORY_KEYWORDS to match your niche:

tuc.config.CATEGORY_KEYWORDS.ai.push('robotics', 'autonomous');
tuc.config.CATEGORY_KEYWORDS.builder.push('no-code', 'low-code');

Rate Limits

Twitter limits unfollows to ~30 per burst. The script handles this automatically:

• 8 second delay between each unfollow (avoids triggering limits too fast)
• 12 minute cooldown when rate-limited (Twitter's reset window)
• 3 retries per account before skipping
• ~20 min per 100 unfollows including rate limit pauses

Total time for 500 unfollows: roughly 1.5-2 hours. Start it and let it run.

Safety

• Mutuals are always protected — anyone who follows you back is never unfollowed
• Dry run by default — the script shows you the full plan before unfollowing anything
• Pause anytime — tuc.stop() pauses, tuc.resume() continues
• No tokens or API keys needed — runs using your existing browser session
• Nothing is installed — just a script in your browser console

Gotchas

• Don't close the tab while it's running — progress is lost if you close it
• GraphQL endpoint hashes rotate when X deploys updates — the script auto-detects current hashes from the page, and falls back to stable REST endpoints if GraphQL fails
• New accounts you follow between runs aren't included — re-run tuc.run() for a fresh scan
• Works on desktop browsers only (Chrome, Firefox, Edge)

For Contributors

The package.json, eslint.config.cjs, and checks/ folder are development-only tooling. End users don't need them.

To run the dev checks locally:

npm install
npm test        # lint + smoke check

The smoke check runs a mock end-to-end test (fake data, no real API calls) to verify the script loads and categorizes correctly.

License

MIT