Save Your Twitter Bookmarks Before They Vanish

If you're like me, you use Twitter's bookmark feature as a catch-all for interesting threads, code snippets, and resources you plan to read "later." The problem? "Later" often never comes, and those bookmarks are locked inside a platform that's increasingly volatile. What if the feature changes, the API breaks, or you just want to search and organize them on your own terms?

That's where Smaug comes in. It's a simple, open-source tool that quietly backs up your Twitter (or X) bookmarks to plain markdown files on your own machine. No more platform dependency, just your data in a format you can actually use.

What It Does

Smaug is a Python script that uses the official Twitter API to fetch your bookmarked tweets. It then processes each one, extracting the core text, the author, the date, and any linked media, and saves it all into a structured markdown file. Each bookmark becomes a section in the file, making it easy to read, search, and archive.

Why It's Cool

The clever part is in the output. Smaug doesn't just dump JSON. It creates human-readable markdown, which is the perfect format for developers. You can throw the generated file into any note-taking app that supports markdown (like Obsidian, VS Code, or even a simple GitHub repo), and instantly have a searchable, permanent knowledge base.

It handles threads correctly, stitching together a conversation into a single, coherent entry. It also respects your privacy and control—the data lives with you, not on some third-party server. The implementation is straightforward and hackable, so if you want to tweak the output format or add a filter for certain types of tweets, it's just a Python script away.

How to Try It

Getting started is a few terminal commands away. You'll need a Twitter Developer account to get API keys.

1. Clone the repo:

   git clone https://github.com/alexknowshtml/smaug
   cd smaug
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up your Twitter API credentials in the environment variables as shown in the project's README.

4. Run the script:

   python smaug.py
   

Check the output/ directory for your new bookmarks.md file. The project's GitHub repository has all the detailed setup instructions.

Final Thoughts

In an era where platform features can disappear overnight, taking ownership of your data is a small act of developer resilience. Smaug is a practical, no-fuss tool that solves a specific problem well. It's the kind of utility you run once a month to keep a local backup, giving you peace of mind and a more useful archive of the gems you've found online. It's not a massive app; it's a focused script that does its job and gets out of the way—which is often exactly what you need.

Follow for more cool projects: @githubprojects