# birdclaw

> A local-first Twitter workspace that stores tweets, DMs, likes, bookmarks, and mentions in a local SQLite database with a CLI and web UI.

birdclaw is a local-first Twitter workspace built by Peter Steinberger ([@steipete](https://github.com/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](https://effect.website/) 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.

## Features
- Local SQLite database for tweets, DMs, likes, bookmarks, mentions, follows, blocks, and mutes
- Twitter archive ZIP import with selective re-import by data type
- FTS5 full-text search over tweets and DMs
- Cached live reads via xurl and bird transports
- Local web app with Home, Mentions, Likes, Bookmarks, DMs, Inbox, and Blocks views
- AI-ranked inbox using OpenAI scoring for low-signal filtering
- Streaming AI digest (today, 24h, yesterday, week) via OpenAI Responses API
- Git-friendly JSONL text backups with yearly tweet shards and per-conversation DM shards
- Bulk blocklist import and moderation tools (ban, unban, mute, unmute)
- Profile analysis with timeline walk and Markdown brief generation
- Follow graph queries (top followers, unfollows, mutuals, non-mutual following)
- Media fetch for local caching of images, videos, and GIFs
- Scheduled macOS LaunchAgent jobs for bookmark and account sync
- Multi-account support with account-scoped edges
- Scriptable JSON CLI output for agent and automation pipelines
- Network map plotting followers/following by profile location
- Profile reply scan for AI/slop triage
- Research command turning bookmarks into Markdown briefs
- Discuss command for live keyword search with AI summary

## Integrations
Twitter/X (via xurl and bird transports), OpenAI (inbox scoring and digest generation), SQLite (local data store), Git (backup sync), macOS Spotlight (archive autodiscovery), macOS LaunchAgent (scheduled jobs), Homebrew (installation), xurl (Twitter API client), bird (cookie-backed Twitter client)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.8.5

## Links
- Website: https://birdclaw.sh
- Documentation: https://birdclaw.sh/quickstart.html
- Repository: https://github.com/steipete/birdclaw
- EveryDev.ai: https://www.everydev.ai/tools/birdclaw