Simple Twitter Tracker

Track the newest accounts followed by a list of X/Twitter handles, filter out large accounts, classify each new match with Gemini, OpenAI, or Claude, and write a local HTML report.

This is a very simple small standalone version of my more detailed X tracker meant for GitHub and public use. It does not include Telegram, dashboards, old reports, logs, automatic list cleanup, community/list tracking, sequential tracking.

You can join my telegram channel below. There I manually go through more detailed findings of my own bot and send them straight to the Telegram channel. https://t.me/twitter_X_tracker

This project does not use the official Twitter/X API as that is too expensive. It uses https://twitterapi.io/ which offers a cheaper and simpler endpoint. Referral:

What It Does

1. Reads handles from handles.txt.
2. Uses api.twitterapi.io to fetch up to 20 followings for each handle.
3. Keeps accounts with 5,000 followers or fewer by default.
4. Stores seen followings in a small SQLite database at data/tracker.sqlite3.
5. Sends only newly seen accounts to the AI provider you choose.
6. Writes reports/latest.html with Projects, Individuals, and Unclear accounts.

On the first run, every matching following is treated as new because the database is empty. Later runs only classify accounts that were not seen before for that source handle.

Setup

Use Python 3.10 or newer.

Install the packages from requirements.txt.

Copy .env.example to .env, then add your TWITTER_API_KEY.

Choose one AI provider in .env:

AI_PROVIDER=gemini with GEMINI_API_KEY

AI_PROVIDER=openai with OPENAI_API_KEY

AI_PROVIDER=claude with ANTHROPIC_API_KEY

AI_MODEL is optional. If you leave it blank, the script chooses a default model for the selected provider. Best is to use a cheaper model with a big daily limit.

Add Handles

Edit handles.txt and add one handle per line:

Blank lines and lines starting with # are ignored.

Run

Open the folder in your terminal, run python tracker.py, then open reports/latest.html.

Settings

These defaults are in .env.example:

FOLLOWINGS_LIMIT=20 means the script asks for up to 20 followings per source handle. If you run this almost daily, no reason to change this. Most accounts do not follow over 20 a day.

MAX_FOLLOWERS=5000 means accounts with more than 5,000 followers are skipped before AI classification. Easy way to filter out big accounts that might not have good opportunities to be early. Purely optional.

REQUEST_DELAY_SECONDS=3 adds a pause between source handles to reduce avoidable API pressure.

Files

handles.txt: the source accounts you want to track.

.env: private API keys and settings. Do not upload or share this file anywhere.

data/tracker.sqlite3: local SQLite database. Do not upload or share this file anywhere.

reports/latest.html: latest local report. Do not upload this unless you intentionally want to share the output.