birdclaw: A Local-First Archive and Search Tool for Twitter/X History
Stores all your tweets nicely claw-able for agents. It makes no network requests; run birdclaw serve afterward to browse the demo.
At a glance
- What is it?
- birdclaw imports Twitter/X archives into SQLite, adds optional live sync, and exposes local search through a CLI, web app, and read-only MCP server. It is a pragmatic tool for users who want their own searchable history without a cloud backend.
- Who is it for?
- Adopt birdclaw if you want a self-contained, searchable copy of your Twitter/X history and are comfortable with SQLite and command-line workflows. Skip it if you need a hosted service, automatic live sync, or a GUI-heavy experience.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What birdclaw Solves
birdclaw addresses a specific gap: Twitter/X users who want a durable, searchable record of their tweets, DMs, saved posts, and follow graph without depending on the platform's cloud or a third-party service. The README frames it as a tool for people who want their own history with a longer memory. It imports a Twitter/X archive into local SQLite, then lets you search and browse that data through a web app, a CLI, and an optional MCP server. The project targets individuals, researchers, or developers who value data ownership and local access. It is not a social media client; it does not replace the X app. Instead, it turns a one-time archive export into a living local dataset.
How the Data Flow Works
The architecture is straightforward: SQLite is the canonical store, and all data converges into the same tables regardless of whether it comes from an archive import or a live sync. Archive imports establish the account identity and load tweets, DMs, likes, bookmarks, profiles, media, and follow edges. Live sync, when enabled, delegates to `xurl` or an existing private `bird` installation and only runs when you explicitly invoke it. This separation is deliberate. The README states that local reads do not trigger network traffic by default, and the web server listens on loopback. That design choice means your normal browsing and searching never hit the network, which is a privacy win. The trade-off is that live data is not automatically fetched; you must run sync commands to refresh. For users who want a complete picture, that manual step is a small cost.
Getting Started: Commands and Configuration
Installation is simple on macOS and Linux via Homebrew: `brew install steipete/tap/birdclaw`. A global npm install is also available: `npm install -g birdclaw`. The quick start creates a self-contained demo: `birdclaw init --demo`, then `birdclaw search tweets "local-first" --limit 3 --json`, then `birdclaw serve`. This seeds sample tweets, DMs, profiles, and links without any credentials or network requests. For real data, you import an archive: `birdclaw import archive ~/Downloads/twitter-archive.zip --json`. Imports are idempotent and merge destination-only rows by default. Configuration lives in `~/.birdclaw/config.json`, and you can override it with environment variables or command flags. The precedence is flags, then environment, then config file. Set `BIRDCLAW_HOME` to use a different root. Live sync examples include `birdclaw sync timeline --limit 100 --refresh --json` and `birdclaw sync bookmarks --mode auto --limit 100 --refresh --json`. The README stresses that you should import an archive before the first live sync on a new database.
Search and Interfaces
Local search is powered by SQLite's FTS5, which gives you fast full-text search over tweets and DMs. The CLI supports JSON output, which makes it scriptable for automation or research. The web app provides views for home, mentions, saved posts, DMs, inbox, moderation, and network. The backup feature writes deterministic JSONL shards that round-trip through Git, which is a practical way to version your history. The optional MCP server is read-only and exposes cached tweet search and thread tools. It stays off until you configure a token and public URL, which is a sensible security default. The MCP angle is interesting because it lets AI agents query your local history without making network requests, but the README does not detail the exact tool schemas. That is a gap you would need to fill by reading the MCP guide on the project site.
Limitations and Failure Modes
birdclaw is not a full X client. It does not fetch live data on its own; you must run sync commands, and those depend on `xurl` or a private `bird` installation. If you do not have those set up, live sync simply will not work. The README also notes that live writes can be disabled with `BIRDCLAW_DISABLE_LIVE_WRITES=1`, which implies that writes are possible by default, a consideration if you want a strictly read-only setup. The Node.js version requirement is narrow: `>=26.5.1 <27`. That could be a problem if your environment uses an older LTS or a newer major version. The project pins a specific Bun canary for development, which is fine for contributors but adds friction for anyone who wants to build from source. Another limitation is that the demo only shows sample data; to see real value, you need an actual Twitter/X archive, and the import process assumes a standard archive format. If your archive is incomplete or malformed, the README does not describe error handling.
Alternatives and Different Approaches
A common alternative is to use Twitter's own export feature and then store the JSON files in a Git repository or a generic document database. That approach gives you raw data but no built-in search or web interface. Another alternative is a hosted service that syncs your tweets to a cloud database, but that defeats the local-first purpose. A closer comparison is to use a generic SQLite FTS5 setup with your own scripts to import the archive, which gives you full control but requires you to build the schema and search logic yourself. birdclaw differs by providing a ready-made schema, a CLI, a web app, and an MCP server out of the box. The trade-off is that you are tied to birdclaw's data model and update cadence. If you need a more flexible schema or want to integrate with other tools, a custom solution might be better.
Maintenance and License
The project is MIT-licensed, which is permissive and allows commercial use with attribution. The repository is actively maintained, with recent releases in August 2026, including v0.12.1. The development workflow uses a checksum-pinned Bun canary, which is a strong reproducibility measure but also a maintenance burden. The README mentions dual-runtime testing with Bun and Node, plus Playwright against the production server, which suggests a serious CI pipeline. Upgrade cost is low if you use the package manager, but the narrow Node version range means you may need to manage multiple Node installs. The backup feature helps with versioning, but you would need to test restore procedures yourself. Overall, the license and maintenance posture are favorable for adoption, but the live sync dependency on `xurl` is an external factor that could change.
Editorial conclusion
Adopt birdclaw if you want a self-contained, searchable copy of your Twitter/X history and are comfortable with SQLite and command-line workflows. Skip it if you need a hosted service, automatic live sync, or a GUI-heavy experience. Before committing, verify that your archive exports match the expected format, check the Node.js version requirement (>=26.5.1 <27), and test the demo with `birdclaw init --demo` to see if the search and web app meet your needs. The project is MIT-licensed and actively maintained, but its live sync depends on xurl, so confirm that transport works for your account before relying on it.
Community notes