birdclaw 🪶 — Your Twitter history, with a longer memory

Birdclaw imports Twitter/X archives into local SQLite, adds explicit cached live reads, and exposes the result through a web app, CLI, and optional read-only MCP server. It is for people who want their own searchable history, DMs, saved posts, and follow graph without a cloud backend.

Install

Homebrew is the shortest path on macOS and Linux:

brew install steipete/tap/birdclaw

The package is also published on npm:

npm install -g birdclaw

The npm and source installs require Node.js >=26.5.1 <27. See the installation guide for pnpm, source builds, updates, and optional live transports.

Quick start

Create a self-contained demo, search it locally, then open the web app:

birdclaw init --demo
birdclaw search tweets "local-first" --limit 3 --json
birdclaw serve

Open http://localhost:3000. The demo seeds sample tweets, DMs, profiles, and links without credentials or network requests.

Use your archive

A Twitter/X archive establishes the account identity for a new real database and imports tweets, DMs, likes, bookmarks, profiles, media, and follow edges:

birdclaw import archive ~/Downloads/twitter-archive.zip --json

Imports are idempotent and merge destination-only rows by default. Selected re-imports and exact replacement are documented in Archive import.

Birdclaw stores its database, configuration, and media under ~/.birdclaw. Set BIRDCLAW_HOME to use another root.

Add live data

Archive and local search work without an X login. Live sync delegates to xurl or an existing private bird installation and only runs when requested:

birdclaw sync timeline --limit 100 --refresh --json
birdclaw sync bookmarks --mode auto --limit 100 --refresh --json

Import an archive before the first live sync on a new database. The sign-in guide explains xurl setup and transport selection; the sync guide covers caching, pagination, and rate limits.

Work locally

SQLite is the canonical store. Archive imports and live transports converge on the same tables, and FTS5 powers local tweet and DM search.

Local reads do not trigger network traffic by default. The web server listens on loopback, live writes can be disabled with BIRDCLAW_DISABLE_LIVE_WRITES=1, and the MCP endpoint remains off until its token and public URL are configured.

Configuration

~/.birdclaw/config.json selects default accounts, transport preferences, mention sources, and backup behavior. Command flags override environment variables, which override the config file.

See Configuration for the complete file and environment reference. Product boundaries live in VISION.md, and storage and transport details live in Data and architecture.

Development

fnm use
pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm build

The CI workflow also runs coverage, the installed-package smoke test, and Playwright end-to-end tests.

License

MIT. Created by Peter Steinberger. Birdclaw is not affiliated with X Corp.