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).
birdclaw archive find --json
birdclaw import archive --json
birdclaw import archive ~/Downloads/twitter-archive.zip --select likes,bookmarks --json

# Pull in mentions, likes, bookmarks, and the home timeline.
birdclaw sync timeline --limit 100 --refresh --json
birdclaw sync bookmarks --mode auto --all --json

# Search every tweet you've ever liked, locally, with FTS5.
birdclaw search tweets "local-first" --json
birdclaw search tweets --bookmarked --hide-low-quality --limit 100 --json

# Triage with AI ranking and reply from the CLI.
birdclaw inbox --score --hide-low-signal --limit 8 --json
birdclaw compose reply 1891234567890 "On it."

# Stream a local "what happened" digest.
birdclaw today
birdclaw digest week --json

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, selectively re-import stale slices with --select, or stay live-only. All 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 What happened, 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.
  • Streaming AI digest (OpenAI Responses API) for today, 24h, yesterday, or week, with DMs excluded unless explicitly enabled.
  • 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, selected re-imports, 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.
  • Caching tweet media locally. Media covers media fetch for images, video, and GIFs, plus archive-byte reuse.
  • 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.