birdclaw

birdclaw is a local-first Twitter workspace built by Peter Steinberger (@steipete) that keeps your entire Twitter data — tweets, DMs, likes, bookmarks, mentions, follows, blocks, and mutes — in a single local SQLite database. It combines a CLI and a local web app, and is released under the MIT license on GitHub. The project self-describes its status as "real and usable, not finished," with active development and expected schema churn while the core settles.

What It Is

birdclaw is a local-first Twitter data management tool that replaces the need to rely on Twitter's own interface for reading, triaging, and acting on your account data. It imports Twitter archive ZIPs, syncs live data through optional xurl and bird transports, and stores everything in a single SQLite file at ~/.birdclaw/birdclaw.sqlite. A local web app serves views for Home, Mentions, Likes, Bookmarks, DMs, Inbox, and Blocks, while the CLI exposes every workflow as a scriptable JSON-outputting command suitable for agents and automation pipelines.

Architecture and Data Model

The canonical truth is a local SQLite database with FTS5 full-text search over tweets and DMs. Key design decisions include:

• Multi-account support with canonical tweet/profile rows and account-scoped timeline and collection edges, so shared tweets don't clobber account ownership.
• Archive-first, live-aware: a Twitter archive ZIP establishes account identity; live transports (xurl, bird) then fill gaps and refresh stale slices.
• Cached live reads so repeated reads don't keep spending API budget.
• Effect-based internals: the project uses the Effect library for I/O-heavy internals including sync orchestration, backup, moderation, and media fetch pipelines.
• Git-friendly text backups: deterministic JSONL shards (yearly tweet shards, per-conversation DM shards) can be pushed to a private Git repo and merged back.

CLI and Workflow

Every workflow is a one-liner with stable --json envelopes to stdout and progress/warnings to stderr, keeping pipes parseable. Key CLI capabilities include:

• Archive import with --select for partial re-imports (tweets, likes, bookmarks, directMessages, followers, following).
• Live sync for timeline, mentions, mention threads, likes, bookmarks, and DMs with rate-limit-aware resumable runs.
• FTS5 search over local tweets and DMs with filters for liked, bookmarked, replied/unreplied, date ranges, and quality signals.
• AI-ranked inbox using OpenAI scoring to surface high-signal mentions and DMs.
• Streaming AI digest (birdclaw today, birdclaw digest week) using the OpenAI Responses API for a "what happened" summary.
• Profile analysis (birdclaw profile-analyze) that walks a user's timeline, backfills conversations, and writes a Markdown brief.
• Moderation tools: bulk blocklist import, ban/unban, mute/unmute, with auto transport trying bird first and falling back to xurl.
• Scheduled jobs via macOS LaunchAgent for bookmark sync (every 3 hours) and full account sync (every 30 minutes).

Local Web App

The web UI runs at localhost:3000 via birdclaw serve and is local-only by default (no auth layer, loopback only). It provides:

• Home timeline with constrained lane instead of full-width dashboard chrome.
• What happened streaming AI digest.
• Mentions queue with replied/unreplied filters.
• Likes / Bookmarks review lanes.
• DMs workspace with two-column layout and sender influence context.
• Inbox for AI-assisted triage of mixed mentions and DMs.
• Blocks for local blocklist maintenance.
• System/light/dark theme switcher.

Remote access requires setting BIRDCLAW_ALLOW_REMOTE_WEB=1 and optionally BIRDCLAW_WEB_TOKEN for an app-level token.

Update: v0.8.5

The latest release is v0.8.5, published on June 21, 2026. The repository was created in March 2026 and has seen rapid iteration, with the last push on June 22, 2026. The GitHub repository has accumulated over 1,000 stars and 95 forks. The changelog tracks recent shipments, and the project roadmap (spec) lists broader resumable live sync, thumbnail generation, richer multi-account UX, and more complete transport coverage as still in progress.