Local-first · CLI + Web · SQLite

Your Twitter, your bird.

birdclaw is a local-first Twitter workspace: archive import, cached live reads, focused triage, and reply flows in one local web app + CLI.

Quickstart GitHub
brew install steipete/tap/birdclaw
TweetsDMsLikesBookmarksMentionsInboxBlocksMutesGraph

Other install options →

#Try it

After installing and running birdclaw init, every workflow is a one-liner.

# Find and import your Twitter archive (auto-discovered on macOS).
1 archive find 0
1 import archive 0

# Pull in mentions, likes, bookmarks, and the home timeline.
3 sync timeline 0 100 1 2
3 sync bookmarks 0 auto 1 2

# Search every tweet you've ever liked, locally, with FTS5.
2 search tweets 0 1
4 search tweets 0 1 2 100 3

# Triage with AI ranking and reply from the CLI.
4 inbox 0 1 2 8 3
1 compose reply 1891234567890 0

Stable --json envelopes go to stdout, progress and warnings to stderr — pipes stay parseable.

#What birdclaw does

  • One local SQLite database for tweets, DMs, likes, bookmarks, mentions, follows, blocks, and mutes — multi-account, FTS5-indexed.
  • Archive-first, live-aware. Import a Twitter archive when you have one, or stay live-only. Both paths converge on the same canonical tables.
  • Cached live reads through xurl and bird, so repeated reads do not keep spending the API budget.
  • Local web app for Home, Mentions, Likes, Bookmarks, DMs, Inbox, and Blocks — light/dark/system theme, focused timeline lane, no dashboard chrome.
  • AI-ranked inbox (OpenAI) for low-signal filtering on mentions and DMs.
  • Account-scoped moderation with bulk blocklist import and a cookie-backed fallback when OAuth2 block writes get rejected.
  • Git-friendly text backups with yearly tweet shards and per-conversation DM shards — push the local SQLite truth into a private Git repo.

#Pick your path

  • First time using birdclaw. Install → Quickstart. Five minutes from brew install to your first authenticated query.
  • Have a Twitter archive ZIP. Archive import walks through autodiscovery, full-DM mode, and idempotent re-runs.
  • No archive, just want to read live. Sync covers likes, bookmarks, timeline, mention threads, and rate-limit-aware resumable runs.
  • Triaging mentions or DMs. Search, Mentions, DMs, and Inbox.
  • Maintaining a blocklist. Moderation covers blocks, mutes, ban/unban, and bulk imports.
  • Backing up to Git. Backup for deterministic JSONL shards and backup sync round-trips.
  • Looking up a flag. The CLI reference lists every subcommand and option.

#Project

Active development. Status: real and usable, not finished. Schema churn, transport gaps, and rough edges are expected while the core settles.

The changelog tracks what shipped recently. Goals and non-goals live in the spec. Released under the MIT license. Not affiliated with X Corp.