birdclaw — Local Twitter memory in SQLite

birdclaw Local Twitter memory

Search

#Try it

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

# Find and import your Twitter archive (auto-discovered on macOS).<br>birdclaw archive find --json<br>birdclaw import archive --json<br>birdclaw import archive ~/Downloads/twitter-archive.zip --select likes,bookmarks --json

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

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

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

# Stream a local "what happened" digest.<br>birdclaw today<br>birdclaw digest week --json<br>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.