x2masto

Collect your X/Twitter following data and build Mastodon import CSVs.

x2masto is a Node.js CLI toolkit that helps you:

1. browse your following list on X while a helper script reads visible profile cards,
2. extract likely Mastodon handles from profile text/links,
3. optionally run a second Mastodon search pass to discover more matches.

Why this project exists

X and Mastodon don't offer a direct follow migration path. This toolchain builds one from your own follow graph data.

How it works

The collect step does not automate scrolling or navigation. You browse your own following list manually in Chrome while the script passively reads whatever profile cards are currently visible on screen — like a clipboard that remembers what you've seen. You control the pace; the script just takes notes.

Install

As an npm package

npm install -g x2masto

Quickstart

1) Start Chrome with remote debugging

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.cache/browser-tools" \
  --no-first-run \
  --no-default-browser-check

Log into x.com in that Chrome window.

2) Collect your X following dataset

npm run collect:x-following -- --user <username>

The script opens your /following page and waits. Scroll through the list yourself at whatever pace you like. The script reads visible profile cards as you go. Press Enter in the terminal when you're done.

Output files:

• data/x-following-raw.csv
• data/x-following-raw.jsonl

3) Extract Mastodon handles

npm run match:mastodon

Output files:

• data/x-matches.csv
• data/x-mastodon-import.csv

Optional handle verification via WebFinger:

npm run match:mastodon -- --verify --verify-workers 8

4) Optional: search Mastodon instances for additional matches

npm run search:mastodon -- --max-accounts 500

Output files:

• data/x-search-matches.csv
• data/x-mastodon-import-search.csv
• data/x-mastodon-import-combined.csv

CLI commands

If installed globally from npm, you can use:

• x2masto-collect
• x2masto-match
• x2masto-search

Or keep using npm scripts from source:

• npm run collect:x-following -- ...
• npm run match:mastodon -- ...
• npm run search:mastodon -- ...

Development

npm ci
npm run check
npm pack --dry-run

Contributing & community

• Contributing
• Code of Conduct
• Security Policy
• License (MIT)

Notes

• X UI and anti-bot behavior can change; selectors may need updates.
• Login/CAPTCHA/MFA are intentionally manual; the collect step only reads visible data.
• Handle extraction is heuristic. Review generated CSVs before importing.