TweetNook

TweetNook is a self-hosted archive for your Twitter/X bookmarks, likes, and tweets. Run it on your own computer or server, import an archive downloaded from Twitter/X, keep it updated with automated syncs, and browse everything in a Web UI from your network. Search by words, author, date, or tag to find something you saved without scrolling through your account.

Features

• Archive your tweets: save bookmarks, likes, and your own tweets, along with replies and quoted tweets
• Import existing data: bring in an official Twitter/X archive.
• Browse in your browser: read saved threads, view photos and videos, and explore quoted tweets and articles.
• Search and organize: combine search filters, add your own tags, and edit local descriptions.
• Automated tagging: with an optional add-on, you can use Gemini to suggest tags and describe media.
• Keep it up to date: run a sync from the web app or terminal, or schedule regular syncs.
• Unavailable-tweet recovery: periodically recheck for unavailable tweets that might return.
• Export your collection: save tweet data as JSON for use in other tools.

Project background

This project began as a fork of the upstream project, which provides the foundation for this work. This version is developed independently.

Thanks to rrika for sharing their archive like-order research.

[!NOTE] If you are upgrading from an older upstream installation that uses LanceDB, see the migration instructions.

The original project provides the foundation for syncing, archive imports, media downloads, thread expansion, article retrieval, and link previews. This fork is developed independently and continues to build on that foundation.

Getting started

You need macOS or Linux and Python 3.12 or newer. Live syncing also needs a browser signed in to your Twitter/X account. You can import a downloaded archive without connecting to Twitter/X first.

1. Install

Install TweetNook with pip:

python3 -m pip install tweetnook

To include automated tagging support:

python3 -m pip install "tweetnook[automated-tagging]"

2. Install the service

For a persistent homelab/server installation, install TweetNook as a system service:

sudo tweetnook service install

This installs and enables the TweetNook service so it starts automatically at boot and keeps running in the background.

Check its status with:

tweetnook service status

You can also manage it with:

sudo tweetnook service restart
sudo tweetnook service stop
sudo tweetnook service start

3. Open TweetNook

After the service starts, open the Web UI using the address shown by TweetNook, for example:

http://192.168.1.50:8000

On first launch, the Web UI will guide you through setup.

Everyday use

Keep your archive up to date

Run tweetnook sync again whenever you want to save new bookmarks and likes. To automate it, open Settings → Schedule, choose when to run, and save. The TweetNook server/service must stay running for scheduled syncs to work; the browser can be closed. Your own tweets still use the separate tweetnook sync tweets command.

A sync page normally contains up to 20 tweets; --limit counts pages, not tweets. The limit does not bound all follow-up work. Run one archive job at a time and read the final summary for any downloads or lookups that need another attempt.

Use Stop Task in the web app or Ctrl+C in the terminal to interrupt a job. Wait for it to finish stopping before starting another. Stopping TweetNook also asks its active Web or scheduled job to stop gracefully, preserving already committed work.

Search saved tweets

Type words and filters together in the web app's search box:

The same queries work in the terminal:

tweetnook search '"night sky" has:image' --sort newest --limit 20

Dates use UTC, and until excludes the date entered. See Search for all filters and search limits.

Add tags

Open a tweet's menu in the web app to add tags or a description. Click a tag to find related tweets. Settings → Tags lets you merge or delete tags across your archive.

Fill in missing details

Normal sync handles follow-up work automatically. You can also run individual jobs when you need them:

tweetnook import enrich
tweetnook threads expand
tweetnook media download --retry-failed

These commands fill in eligible missing details, expand saved conversations, and retry media downloads. Run only the jobs you need. See Enrichment for articles and link previews too.

Optional Gemini tagging

Gemini can suggest tags for text and media tweets and add media descriptions. To install support in the active pip environment:

python -m pip install "tweetnook[automated-tagging]"

Restart the TweetNook server afterward. For a systemd installation, use the service restart command; for a foreground tweetnook serve process, stop and start it again. Developers using uv can install the extra once with uv sync --extra automated-tagging. No runtime --extra flag is needed.

Open Settings → Automated Tagging, enable the controls, enter your Gemini API key, choose a model and Free or Paid mode, and set the usage limits. Try one archived tweet with Test run, then save when you want tagging enabled.

Once saved and enabled, tagging runs after sync. To tag existing eligible tweets without syncing:

tweetnook tag

Tagging sends selected content to Google. Test runs also use real requests and can consume quota or incur charges, though they do not save generated tags. Read Automated tagging for setup, privacy, and spend controls.

Your files and backups

The folder contains the archive database, downloaded media, tags, and activity history. Configuration explains custom locations.

To back up, stop the app and all archive jobs, then copy the complete data folder and your configuration. Keep original Twitter/X downloads separately. Backups and maintenance covers restoring and checking a backup.

To export tweet data for analysis or another tool:

tweetnook export json --out my-tweets.json

JSON exports do not include media files or everything needed to restore an archive. Use a full folder backup for recovery.

Documentation and help

Use tweetnook --help to list commands or add --help to a command, such as tweetnook sync --help.

License

Apache License 2.0. See upstream for the original project.