Start

Quickstart

GitHub Edit page

Quickstart

Five minutes from a clean machine to a local SQLite store full of your tweets, DMs, likes, and bookmarks — plus a working web UI.

#1. Install

0 install steipete/tap/1
1 0

Other install options (npm, source) are on Install.

#2. Initialize local state

0 init
1 auth status 0
1 db stats 0

init creates ~/.birdclaw/, opens the shared SQLite database, writes a default config when none exists, and probes for xurl and bird on PATH.

auth status prints which transports are available and which account is active. Right after init, no account is configured yet — that comes in step 4.

#3. Find and import an archive

If you downloaded your Twitter/X archive from https://x.com/settings/your_archive, point birdclaw at it. On macOS, autodiscovery looks in ~/Downloads and Spotlight first.

1 archive find 0
1 import archive 0
# or with an explicit path:
1 import archive ~/Downloads/twitter-archive-2025.zip 0
1 import hydrate-profiles 0

hydrate-profiles fills bios, follower counts, and avatars from live Twitter metadata using whichever transport is available.

No archive yet? Skip to step 4 — birdclaw is fully usable in live-only mode.

#4. Sync live state

auto tries xurl first, then falls back to bird. Use bird directly for surfaces where the API path is rate-limited.

4 sync likes 0 auto 1 100 2 3
4 sync bookmarks 0 auto 1 100 2 3
3 sync timeline 0 100 1 2
3 sync mention-threads 0 30 1 1500 2

Without xurl or bird, sync stays in archive-only mode and just verifies the local cache.

#5. Start the web app

0 serve

Open http://localhost:3000. The default lanes:

  • Home — read and reply without fighting the main Twitter timeline
  • Mentions — work the reply queue with replied/unreplied filters
  • Likes / Bookmarks — revisit saved posts
  • DMs — triage by sender follower count, bio, and influence
  • Inbox — let heuristics or OpenAI float likely-important items
  • Blocks — maintain a local-first account-scoped blocklist

serve background-syncs by default. Pass --no-sync to keep the server purely local.

#6. Run real CLI workflows

Search every tweet you ever liked or bookmarked:

2 search tweets 0 1
4 search tweets 0 1 2 20 3
5 search tweets 0 2020-01-01 1 2021-01-01 2 3 500 4

Triage mentions for an agent:

3 mentions 4 0 1 2 10
4 inbox 0 1 2 8 3

Bulk-block a list of obvious AI/spam accounts:

2 blocks import ~/triage/blocklist.txt 0 acct_primary 1

Reply from the CLI:

1 compose post 0
1 compose reply 1891234567890 0
1 compose dm dm_003 0

#7. Back up locally

backup export writes deterministic JSONL shards that round-trip back into SQLite. Push them to a private Git repo:

0 backup sync \
  0 ~/Projects/backup-1 \
  0 https://github.com/steipete/backup-1.2 \
  0

Set backup.autoSync in ~/.birdclaw/config.json and read paths pull + merge from Git when the last check is stale; data-changing commands push back automatically. Full details in Backup.

#Where to go next

  • Configuration — ~/.birdclaw/config.json, env vars, and per-account profiles
  • Sync — full reference for likes, bookmarks, timeline, and resumable mention-thread fetches
  • Moderation — blocks, mutes, bans, and bulk imports
  • Inbox — heuristic and OpenAI-ranked triage
  • Backup — Git-friendly text shards
  • CLI reference — every subcommand, every flag