Skip to content
Playbook
Install
The Playbook

x-likes

Your X likes in a local database, with image text and linked articles, and an MCP server for Claude.

The problem

Most of what I like on X is screenshots of code and text, and none of it was searchable. x-likes reads the likes from your X data archive into a SQLite file on your machine, fetches each post's text and images, keeps the readable text of every linked article and reads the text in the images. You search it by keyword or by meaning, and an MCP server lets Claude search it for you.

Matt Waite, founder

Get it

git clone https://github.com/excellent-so/x-likes.git

Source on GitHub

Version 0.1.1 · MIT license

With your real likes
cd x-likes && pnpm install
pnpm ingest ~/Downloads/twitter-2026-xxxx.zip   # reads the .zip directly
pnpm hydrate                                     # tweet text and images (resumable)
pnpm enrich                                      # articles, OCR, tags, embeddings
pnpm serve                                       # http://localhost:4321

How to use it

  1. Clone the repo and run pnpm install. It needs Node 22 or later and pnpm 11.
  2. Run the demo in the README first. It needs no account, key or archive.
  3. Download your data archive from X (Settings, then Your account), then run pnpm ingest on the zip, pnpm hydrate and pnpm enrich.
  4. Set ANTHROPIC_API_KEY before enrich to have Claude read the images. Without it, the offline mock reads no text from real photos.
  5. Register the MCP server as the README shows, and ask Claude for a post you remember liking.

Where it came from

I've liked 8,218 posts on X since 2013. The first time I ran x-likes on my own archive I had no API key set, and all 6,361 image rows in my database came from the offline mock, which reads nothing from a real photo.

The run finished, the summary said the images were analyzed, and the word mock sat in parentheses at the end of the line. A step that never ran looked like a step that did. The README now says plainly what the mock reads and what it can't.

Everything stays on your machine: the database, the images and the embeddings, which come from a small model that runs locally.

That gap between a step that ran and a step that says it ran is what Excellent checks for in agent work. excellent.so