xbm — Local X/Twitter Bookmark Search Engine

A local-first CLI tool for searching, tagging, and organizing your X/Twitter bookmarks using hybrid BM25 + vector search and LLM auto-categorization. All data stays on your machine.

Setting up via an AI agent? See AGENT_SETUP.md for step-by-step instructions your agent can follow.

Prerequisites

• Bun >= 1.0.0 (or Node.js with npm)

Install

bun install
bun run build

This compiles TypeScript into dist/ and makes the xbm command available.

For development without building:

bun run dev -- <command>

Quick Start

# 1. Import bookmarks from an X data export
xbm import ~/Downloads/bookmarks.json

# 2. Search your bookmarks
xbm search "machine learning papers"

# 3. See stats
xbm stats

On first run, xbm automatically downloads two small models (~1 GB total) to ~/.cache/xbm/models/ for embeddings and auto-categorization.

Commands

Command	Description
fetch	Fetch bookmarks from X via bird CLI (browser cookies)
import <file>	Import bookmarks from X/Twitter JSON export
search <query>	Hybrid keyword + semantic search
list	List bookmarks with optional filters
stats	Show bookmark counts, top authors, and top tags
open <tweet_id>	Open a bookmark URL in your browser
embed	Generate embeddings for unembedded bookmarks
categorize	Auto-tag uncategorized bookmarks via LLM
tag <tweet_id> <tag>	Manually tag a bookmark
untag <tweet_id> <tag>	Remove a tag
tags	List all tags with counts
bulk-tag <tag>	Tag all bookmarks matching filters
delete <tweet_id>	Delete a bookmark
bulk-delete	Delete bookmarks matching filters
digest [tag]	Show reading queue overview, or unread bookmarks for a tag
read <tweet_id>	Mark a bookmark as read and open it in the browser
export	Export bookmarks as JSON

Common Options

Most listing/search commands support these filters:

--author <handle>   Filter by author
--tag <tag>         Filter by tag
--after <date>      After date (ISO 8601)
--before <date>     Before date (ISO 8601)
-n, --limit <N>     Max results (default: 10 for search, 50 for list)
--json              Output as JSON

Import-specific flags:

--dry-run           Preview without writing to the database
--no-embed          Skip embedding generation
--no-categorize     Skip auto-categorization

Data Storage

All data lives under ~/.cache/xbm/:

~/.cache/xbm/
├── xbm.sqlite        # SQLite database (bookmarks, tags, vectors)
└── models/           # Auto-downloaded GGUF models

Running Tests

bun test            # single run
bun run test:watch  # watch mode

License

MIT