BirdClaw: The Open-Source Local Twitter Workspace That Turns Your X Feed Into a SQLite Database

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)

brew install steipete/tap/birdclaw

To upgrade later: brew upgrade birdclaw

npm / pnpm

pnpm add -g birdclaw
# or
npm install -g birdclaw

From source

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
• OpenAI API key — optional, only needed for birdclaw today / birdclaw digest AI features

Getting started: the first three commands

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:

# 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:

birdclaw import archive ~/Downloads/twitter-archive-2026.zip --select tweets --json
birdclaw import archive ~/Downloads/twitter-archive-2026.zip --select likes,bookmarks --json
birdclaw import archive ~/Downloads/twitter-archive-2026.zip --select directMessages --json

Valid slices: tweets, likes, bookmarks, profiles, directMessages, followers, following.

Hydrate profiles

After import, profile data from the archive can be stale. Optionally refresh bios, follower counts, and avatars from live Twitter metadata:

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

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:

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:

export OPENAI_API_KEY=sk-...

Override the model or reasoning effort with environment variables:

export BIRDCLAW_AI_MODEL=gpt-5.5
export BIRDCLAW_OPENAI_REASONING_EFFORT=medium
export BIRDCLAW_OPENAI_SERVICE_TIER=auto

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

# Sync your timeline
birdclaw sync timeline --limit 100 --refresh --json

# Sync likes (auto tries xurl, falls back to bird)
birdclaw sync likes --mode auto --limit 100 --refresh --json

# Sync bookmarks
birdclaw sync bookmarks --mode auto --limit 100 --max-pages 5 --early-stop --json

# Sync mentions
birdclaw sync mentions --mode xurl --limit 100 --max-pages 3 --refresh --json

# Sync mention threads (fills parent/root conversation context)
birdclaw sync mention-threads --limit 30 --delay-ms 1500 --json

# Sync authored tweets
birdclaw sync authored --mode xurl --limit 100 --json

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:

# Search tweets
birdclaw search tweets "local-first" --json
birdclaw search tweets "sync engine" --limit 20 --json
birdclaw search tweets --since 2020-01-01 --until 2021-01-01 --json
birdclaw search tweets --liked --limit 20 --json          # only liked tweets
birdclaw search tweets --bookmarked --limit 20 --json      # only bookmarks

# Search DMs
birdclaw search dms "prototype" --json
birdclaw search dms "layout" --min-followers 1000 --sort followers --json

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:

birdclaw sync followers --json           # sync first (cache-first, dry-run by default)
birdclaw sync following --yes --json     # --yes to actually write to SQLite

birdclaw graph summary --json
birdclaw graph top-followers --limit 20 --json
birdclaw graph unfollowed --date 2026-05-01 --json
birdclaw graph non-mutual-following --sort followers --limit 100 --json
birdclaw graph mutuals --json
birdclaw graph events --since 2026-05-01 --json

The follow graph catches changes (unfollows, new followers) that the Twitter app buries.

DM triage and AI inbox

The DM workspace is one of BirdClaw's most practically useful features for people with high-volume inboxes:

# Sync DMs
birdclaw dms sync --limit 50 --refresh --json

# List DMs with filters
birdclaw dms list --unreplied --min-followers 500 --sort followers --json

# AI inbox — ranks mentions + DMs by likely importance
birdclaw inbox --json
birdclaw inbox --kind dms --limit 10 --json
birdclaw inbox --score --hide-low-signal --limit 8 --json

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

# 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.

Profile analysis

birdclaw profile-analyze steipete
birdclaw profile-analyze openai --max-pages 20 --max-conversations 40 --json

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:

# Import a blocklist file (newline-delimited handles, supports markdown bullets)
birdclaw blocks import ~/triage/blocklist.txt --account acct_primary --json

# Block / unblock
birdclaw ban @handle --account acct_primary --transport auto --json
birdclaw unban @handle --transport bird --json

# View local blocks
birdclaw blocks list --account acct_primary --json

# Scan profile replies to detect likely spam/AI accounts
birdclaw profiles replies @suspicious_handle --limit 12 --json

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:

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:

# 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

Configure auto-sync in ~/.birdclaw/config.json:

{
  "backup": {
    "repoPath": "/Users/you/Projects/backup-birdclaw",
    "remote": "https://github.com/youruser/backup-birdclaw.git",
    "autoSync": true,
    "staleAfterSeconds": 900
  }
}

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:

# 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

~/.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"
  },
  "mentions": {
    "dataSource": "bird",
    "birdCommand": "/Users/you/Projects/bird/bird"
  }
}

• 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

# 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.

GitHub: github.com/steipete/birdclaw | Site: birdclaw.sh | Version: 0.8.5 | License: MIT

Related guides:

• What Is OpenClaw? The local-first AI assistant BirdClaw was built alongside
• Top 25 OpenClaw Claws — including the BirdClaw claw for agent-driven Twitter triage