BirdClaw: The Open-Source Local Twitter Workspace That Turns Your X Feed Into a SQLite Database
BirdClaw (birdclaw.sh) stores your entire Twitter/X history — tweets, DMs, likes, bookmarks, blocks — in a local SQLite database with full-text search, an AI-powered daily digest using GPT-5.5, and a clean ad-free web UI. Complete setup guide, CLI reference, and workflow walkthrough.
BirdClaw is what happens when a developer gets tired of fighting Twitter's algorithm, its ads, and its API restrictions — and decides to just store their own data locally and build the reading experience they actually want.
Built by Peter Steinberger (@steipete, of PSPDFKit fame), BirdClaw is an open-source local-first Twitter workspace: it imports your Twitter archive, syncs sparse live updates to stay within API limits, and stores everything in a single local SQLite database with full-text search. On top of that it gives you a clean web UI for reading, a CLI for automation and agents, and an AI-powered daily digest (GPT-5.5 by default) that summarises what happened in your feed without you opening Twitter at all.
It hit 1.2k GitHub stars within weeks of launch. This is the complete setup and usage guide.
Why BirdClaw exists
Twitter's official app and web interface are optimised for engagement, not for people who want to read their actual feed. The "For You" tab mixes algorithmic content with ads. Bookmarks have no search. DMs are buried. And if you want to find something you tweeted or liked two years ago, good luck.
BirdClaw's premise: your Twitter data belongs to you, and a local SQLite database is a better home for it than Twitter's servers. SQLite gives you instant full-text search, scriptable JSON exports for agents and automation, and offline access to your entire history — all without paying per API call.
The AI digest angle is pragmatic: instead of scrolling your feed every morning, you run birdclaw today and get a structured summary of what actually mattered in your network.
Installation
macOS via Homebrew (recommended)
bash
brew install steipete/tap/birdclaw
To upgrade later: brew upgrade birdclaw
npm / pnpm
bash
pnpm add -g birdclaw
# or
npm install -g birdclaw
From source
bash
git clone https://github.com/steipete/birdclaw
cd birdclaw
fnm use # requires fnm; Node 25.8.1+ required
pnpm install
pnpm build
node ./bin/birdclaw.mjs --version
Requirements
Node 25.8.1 or Node 26.x
pnpm
macOS recommended (Spotlight archive autodiscovery works out of the box)
xurl — optional, for OAuth2-backed live reads/writes
bird — optional, for cookie-backed likes, bookmarks, mentions, and DMs
birdclaw init # creates ~/.birdclaw/, writes default config, probes transports
birdclaw auth status # shows which transports (xurl, bird) are connected
birdclaw db stats # shows what's in the local database
init sets up ~/.birdclaw/birdclaw.sqlite as your canonical store. From there, the quickest path to a useful database is importing your Twitter archive.
Step 1: Import your Twitter archive
Your Twitter archive is a ZIP file containing your complete tweet, DM, likes, bookmarks, followers, and following history. Request it from x.com/settings/download_your_data — X emails a download link when it is ready, which can take a few days for large accounts.
Once you have it:
bash
# Let birdclaw find the archive automatically (macOS Spotlight)
birdclaw archive find --json
# Import it
birdclaw import archive --json
# Or specify the path directly
birdclaw import archive ~/Downloads/twitter-archive-2026.zip --json
The import is idempotent — running it again on the same archive is safe. It parses tweets, likes, followers/following edges, full DMs, and bundled media files. Media from the archive is extracted to ~/.birdclaw/media/originals/archive/ and reused by the media fetcher without spending CDN bandwidth.
Selective re-imports
If you have a newer archive but don't want to wipe local data you've synced live, you can import only a specific slice:
After import, profile data from the archive can be stale. Optionally refresh bios, follower counts, and avatars from live Twitter metadata:
bash
birdclaw import hydrate-profiles --json
This does spend live API reads, so skip it if you are rate-limit-conscious.
Step 2: Start the web UI
bash
birdclaw serve
Opens at http://localhost:3000. The web UI is the primary way most users interact with BirdClaw day-to-day. It has:
Home — timeline view with explicit Sync button, replied/unreplied filters
Mentions — reply queue with clean filters for triage
Likes / Bookmarks — review lanes for archive and live-synced collections
DMs — two-column workspace with sender context, follower count, and influence scores
Inbox — AI-ranked combined view of mentions + DMs, OpenAI scoring to float high-signal items
Links — Hacker News-style top URLs shared in your network over today/week/month/all-time
Blocks — local-first blocklist management
What happened — the AI digest stream
The web UI has system / light / dark theme switching with animated transitions, tweet expansion with inline images and quoted tweets, profile hover cards with bio and follower context, and sender influence context in DM detail headers.
Step 3: The AI digest — birdclaw today
This is the feature that made BirdClaw viral. Instead of scrolling your feed, you get a structured summary:
bash
birdclaw today # digest of today's activity
birdclaw today --language zh-CN # localised to Chinese
birdclaw digest 24h --refresh # last 24 hours, fresh pull
birdclaw digest week --json # week digest as JSON
birdclaw digest today --include-dms # include DMs in digest
birdclaw digest --since 2026-05-16T00:00:00Z --until 2026-05-17T00:00:00Z
BirdClaw uses the OpenAI Responses API with GPT-5.5, medium reasoning, and priority service tier by default. Set your API key:
bash
export OPENAI_API_KEY=sk-...
Override the model or reasoning effort with environment variables:
The digest reads from your local SQLite store — not from live Twitter. Repeated runs on the same context are cached by context hash and return instantly.
The web UI's What happened tab streams the same digest with a structured breakdown: summary cards, signal topics, highlight tweets with hover previews, top links, and people worth following up with.
Live sync commands
For live data beyond your archive, BirdClaw supports two transport backends:
xurl — OAuth2 backed, preferred for most data types
bird — cookie-backed fallback, required for DMs and block writes
The --early-stop flag stops paging once a full page already exists locally — useful for incremental runs that shouldn't re-fetch data you already have.
Full-text search
BirdClaw indexes every tweet and DM in SQLite FTS5. Search runs locally, returns instantly, and works completely offline:
This is the feature people immediately love — searching bookmarks for something you saved three years ago returns instantly because it's a local SQL query, not a network call.
Follow graph queries
BirdClaw builds a local social graph from your followers and following data. Graph commands are purely local SQLite reads — they never call Twitter:
The AI inbox uses OpenAI to score items and float high-signal ones to the top, suppressing low-follower or templated-looking messages.
Research bookmarks and discussions
bash
# Research: turns bookmarked tweets into a markdown brief with thread expansion
birdclaw research "codex" --limit 20 --thread-depth 10 --json
birdclaw research --account acct_primary --out ~/research/codex.md
# Discuss: live keyword search, stored as local tweets, GPT-5.5 summary
birdclaw discuss "local-first" --mode bird
birdclaw discuss "sync engine" --question "what changed over time?"
birdclaw discuss "prototype" --include-dms --limit 500 --json
birdclaw research is particularly useful for power users who heavily bookmark content — it generates a structured markdown brief from your saved tweets on a topic, with thread context and extracted links.
Resolves a profile through xurl, walks their timeline, backfills high-signal conversations via X recent search, and writes a markdown profile brief. Useful for researching people before following up or for due diligence on accounts that DM you.
Blocklist and moderation
One of BirdClaw's killer features for power users: local-first blocklist management with batch import:
The profile reply scan is a practical pattern: for accounts you are unsure about, scanning their recent replies shows whether they have a pattern of generic, upbeat replies across unrelated threads — a common signal for AI-generated engagement.
Media cache
BirdClaw can fetch and cache tweet media locally:
bash
birdclaw media fetch --json
birdclaw media fetch --dry-run --limit 20
birdclaw media fetch --include-video --video-pacing-ms 1500 --json
birdclaw media fetch --no-include-video --parallel 3 --pacing-ms 250 --json
Media is stored at ~/.birdclaw/media/originals/<media_key>.<ext>. For archive imports, BirdClaw extracts bundled media first and only falls back to CDN downloads for what's missing — so you're not re-downloading data you already have locally.
Git backup
BirdClaw exports deterministic JSONL text shards (tweets by year, DMs by year, collections as edges) for a private Git backup:
bash
# Sync to a private GitHub repo
birdclaw backup sync \
--repo ~/Projects/backup-birdclaw \
--remote https://github.com/youruser/backup-birdclaw.git \
--json
# Restore from backup
birdclaw backup import ~/Projects/backup-birdclaw --json
With autoSync: true, data-changing commands automatically commit and push changes after running. Read commands pull from Git only when the last sync is stale.
Scheduled sync with LaunchAgent (macOS)
For hands-free daily operation, install LaunchAgents that run sync automatically:
bash
# Full account sync every 30 minutes
birdclaw --json jobs install-account-launchd \
--account acct_primary \
--program /opt/homebrew/bin/birdclaw
# Bookmark sync every 3 hours
birdclaw --json jobs install-bookmarks-launchd \
--program /opt/homebrew/bin/birdclaw
# Check status
launchctl print gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
tail -n 1 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
Logs go to ~/.birdclaw/logs/, audit records to ~/.birdclaw/audit/. A lock file prevents overlapping runs.
Storage layout
snippet
~/.birdclaw/
├── birdclaw.sqlite # the main database
├── config.json # transport and backup config
├── media/
│ ├── originals/ # cached tweet/DM media
│ └── thumbs/avatars/ # cached profile avatars
├── audit/ # sync audit JSONL logs
└── logs/ # LaunchAgent stdout/stderr
Override the root: export BIRDCLAW_HOME=/path/to/custom/root
Config file
~/.birdclaw/config.json controls transport defaults:
actions.transport — auto, bird, or xurl for block/mute writes
mentions.dataSource — controls which transport backs live mention reads
Who is BirdClaw for
Power users with large archives — if you've been on Twitter since 2009, BirdClaw turns that history into an instantly searchable local database. Every tweet you ever liked or bookmarked is searchable in milliseconds.
Developers and AI builders — the CLI exports stable JSON for agents and automation. Every command accepts --json. Birdclaw's SQLite store is designed to be "claw-able" for agents — the database schema is normalized, FTS5-indexed, and scriptable.
High-volume accounts — the DM triage, AI inbox scoring, and blocklist management are genuinely useful for accounts with hundreds of inbound DMs and mentions.
People who want a clean reading experience — the web UI is intentionally minimal: no ads, no algorithmic reordering, no "For You" tab. Just your actual timeline, mentions, and DMs.
Current status and limitations
BirdClaw is on version 0.8.5 (June 2026) and explicitly self-described as "real and usable, not done." What works well today:
Archive import and full-text search — solid
AI digest (birdclaw today) — the flagship feature, works well
Blocklist management and import — works well
DM triage and inbox scoring — works well
Web UI for reading — stable
Known rough edges:
Broader resumable live sync (beyond targeted paths) is still in progress
Thumbnail generation is not yet automatic — run birdclaw media fetch manually or from cron
Multi-account UX is basic
Schema churn is expected as the project evolves — backups are important
The MIT license and active development (18 contributors, 17 releases in 3 months) signal a project that is genuinely maintained, not abandoned.
Getting started: the five-minute path
bash
# 1. Install
brew install steipete/tap/birdclaw
# 2. Initialize
birdclaw init
# 3. Import your archive (download from x.com/settings first)
birdclaw import archive ~/Downloads/twitter-archive.zip --json
# 4. Start the web UI
birdclaw serve
# 5. Generate your first AI digest (needs OPENAI_API_KEY)export OPENAI_API_KEY=sk-...
birdclaw today
After step 3, you have a fully searchable local copy of your Twitter history. The web UI at http://localhost:3000 works immediately — no live Twitter connection required.
