TL;DR

birdclaw là workspace Twitter chạy hoàn toàn trên máy bạn - không cloud, không tracking. Toàn bộ tweets, DMs, likes, bookmarks được lưu vào một file SQLite duy nhất với FTS5 full-text search. Kèm theo là web UI cục bộ sạch sẽ và CLI xuất JSON ổn định cho AI agent. Hiện ở trạng thái WIP nhưng "real and usable".

Twitter của bạn đang ở đâu?

Bạn đã từng tìm lại một tweet cũ từ 3 năm trước mà không thể tìm thấy? Bookmark một bài quan trọng rồi quên luôn vì Twitter không có search tốt? Hay chỉ muốn đọc timeline không bị thuật toán can thiệp?

Đó chính là vấn đề mà birdclaw - tool mã nguồn mở của Peter Steinberger (@steipete) - muốn giải quyết. Triết lý cốt lõi: Your Twitter, your bird. Dữ liệu nằm trên máy bạn, dưới quyền kiểm soát của bạn.

birdclaw local-first workflow - từ Twitter về SQLite đến CLI, Web UI, Git
Kiến trúc local-first của birdclaw: dữ liệu Twitter được lưu vào SQLite và truy cập qua CLI, Web UI, hoặc Git backup.

Cách birdclaw hoạt động

Toàn bộ pipeline xoay quanh một file SQLite duy nhất tại ~/.birdclaw/birdclaw.sqlite:

  • Import archive: Tải archive ZIP từ Twitter, chạy birdclaw import archive, toàn bộ tweets, DMs, likes, bookmarks được parse và lưu vào SQLite với FTS5 indexing.
  • Cached live reads: Sync thêm dữ liệu mới qua xurl (official X API) hoặc bird (cookie-backed). Repeated reads không tiêu API budget vì đã cache cục bộ.
  • Web UI cục bộ: Chạy birdclaw serve để mở web app local với các lane: Home, Mentions, Likes, Bookmarks, DMs, Inbox, Blocks. Light/dark/system theme, không có dashboard chrome gây phân tâm.
  • CLI scriptable: Mọi command xuất --json ổn định ra stdout, progress và warnings ra stderr - pipe-friendly cho automation và AI agent.

Bắt đầu trong 2 phút

Cài đặt trên macOS qua Homebrew:

brew install steipete/tap/birdclaw
birdclaw init
birdclaw import archive
birdclaw serve

Hoặc cài qua npm/pnpm:

pnpm i -g birdclaw

Yêu cầu Node.js 25.8.1 hoặc 26.x. macOS được khuyến nghị cho archive autodiscovery qua Spotlight; Linux hỗ trợ đầy đủ các tính năng còn lại.

Những tính năng đáng chú ý

AI-ranked inbox với gpt-5.5

Kết nối OPENAI_API_KEY, birdclaw sẽ dùng gpt-5.5 để score từng mention và DM theo độ quan trọng. Inbox hiển thị những item đáng đọc lên đầu, lọc bỏ spam và low-signal noise. Lệnh birdclaw today stream một AI digest tóm tắt "hôm nay có gì" từ timeline - chọn today, 24h, yesterday, hoặc week.

Git-friendly backup

Chạy birdclaw backup export để xuất toàn bộ database thành JSONL text shards - tweets theo năm, DMs theo conversation. Push vào private Git repo là bạn có version history cho toàn bộ lịch sử Twitter của mình.

Bulk moderation

Có file blocklist? Một lệnh là xong:

birdclaw blocks import blocklist.txt

Lệnh profiles replies <handle> scan reply gần đây của một account - hữu ích để phát hiện AI bot theo dạng "cùng một template upbeat generic comment trên nhiều thread không liên quan".

Agent-ready JSON export

Mọi command hỗ trợ --json flag xuất dữ liệu có cấu trúc - raw text, plainText, markdown, author metadata, canonical URLs. Lý tưởng để feed vào custom automation hoặc AI pipeline.

birdclaw - Bộ nhớ Twitter trên máy bạn

Giới hạn cần biết

  • WIP: Tác giả mô tả là "real and usable, not done" - expect schema churn và rough edges. Auto-sync account chạy mỗi 30 phút, bookmark sync mỗi 3 tiếng.
  • Cần thêm tool: Để live sync đầy đủ, cần cài thêm xurl (official X API) và/hoặc bird (cookie-backed). birdclaw là local layer ở trên.
  • Không có mobile app: Hiện tại chỉ macOS/Linux.
  • OpenAI optional: Không có API key vẫn dùng được đầy đủ - chỉ mất AI inbox scoring.

Ai nên thử ngay?

  • Developer/power user muốn thoát khỏi thuật toán Twitter và có workspace tập trung hơn
  • AI/automation builder cần nguồn dữ liệu Twitter sạch, có cấu trúc cho agent pipeline
  • Người dùng nặng về privacy không muốn dữ liệu cá nhân nằm trên cloud bên thứ ba
  • Researcher/operator cần phân tích follow graph, triage DMs theo influence score, hoặc bulk moderation

Kết

birdclaw là tool thú vị nhìn từ góc độ "local-first" - trong khi mọi thứ đang đẩy lên cloud, có người đặt câu hỏi "tại sao dữ liệu của tôi phải nằm trên server của người khác?".

Project đang active với 659 stars và commit mới nhất chỉ vài giờ trước tính tới thời điểm viết bài. Nếu bạn là dev và dùng Twitter/X nhiều, đây là thứ đáng thử một buổi tối cuối tuần.

Cài đặt và source code: via birdclaw.sh | via GitHub