birdclaw README

项目的 README,来自 github.com/steipete/birdclaw。合并为一个 markdown 文件:README.md。

birdclaw 🪶 — Your Twitter history, with a longer memory

CI npm Node Bun source toolchain License Homebrew Docs

Birdclaw imports Twitter/X archives into local SQLite, adds explicit cached live reads, and exposes the result through a web app, CLI, and optional read-only MCP server. It is for people who want their own searchable history, DMs, saved posts, and follow graph without a cloud backend.

Birdclaw's local Home timeline populated with demo data

Install

Homebrew is the shortest path on macOS and Linux:

brew install steipete/tap/birdclaw

The package is also published on npm:

npm install -g birdclaw

The npm and Homebrew installs retain the public Node.js >=26.5.1 <27 contract. Source development uses one checksum-pinned Bun 1.4.0-canary.1 build and keeps Node as a tested compatibility lane. See the installation guide for setup and the Bun canary reference for exact checksums, constraints, and rollback boundaries.

Quick start

Create a self-contained demo, search it locally, then open the web app:

birdclaw init --demo
birdclaw search tweets "local-first" --limit 3 --json
birdclaw serve

Open http://localhost:3000. The demo seeds sample tweets, DMs, profiles, and links without credentials or network requests.

Use your archive

A Twitter/X archive establishes the account identity for a new real database and imports tweets, DMs, likes, bookmarks, profiles, media, and follow edges:

birdclaw import archive ~/Downloads/twitter-archive.zip --json
birdclaw import x-json ~/Downloads/saved-tweets.jsonl --json

Imports are idempotent and merge destination-only rows by default. Selected re-imports and exact replacement are documented in Archive import.

Birdclaw stores its database, configuration, and media under ~/.birdclaw. Set BIRDCLAW_HOME to use another root.

Add live data

Archive and local search work without an X login. Live sync delegates to xurl or an existing private bird installation and only runs when requested:

birdclaw sync timeline --limit 100 --refresh --json
birdclaw sync bookmarks --mode auto --limit 100 --refresh --json

Import an archive before the first live sync on a new database. The sign-in guide explains xurl setup and transport selection; the sync guide covers caching, pagination, and rate limits.

Work locally

SQLite is the canonical store. Archive imports and live transports converge on the same tables, and FTS5 powers local tweet and DM search.

Surface What it provides Guide
Web app Home, mentions, saved posts, DMs, inbox, moderation, and network views Quickstart
CLI Search, sync, moderation, research, JSON output, and scheduled jobs CLI reference
Backup Deterministic JSONL shards that round-trip through Git Backup
MCP Read-only cached tweet search and thread tools behind a dedicated token MCP server

Local reads do not trigger network traffic by default. The web server listens on loopback, live writes can be disabled with BIRDCLAW_DISABLE_LIVE_WRITES=1, and the MCP endpoint remains off until its token and public URL are configured.

Bird is optional: xurl supports ordinary live workflows and moderation, while native web access handles DM requests using AUTH_TOKEN and CT0 session cookies. Neither native request access nor xurl moderation needs a browser process. See running without bird.

For an archive-only server, set BIRDCLAW_DEPLOYMENT_READ_ONLY=1 before birdclaw serve. This opt-in mode serves an initialized archive through strict readers, disables web mutations and automatic sync, and hides unavailable controls. See read-only archive deployments for its authentication and storage requirements.

Configuration

~/.birdclaw/config.json selects default accounts, transport preferences, mention sources, and backup behavior. Command flags override environment variables, which override the config file.

See Configuration for the complete file and environment reference. Product boundaries live in VISION.md, and storage and transport details live in Data and architecture.

Development

./scripts/bun-canary.sh install --frozen-lockfile
./scripts/bun-canary.sh run --bun check
./scripts/bun-canary.sh run --bun test
./scripts/bun-canary.sh run --bun build

Vite generates the compact app/favicon logo from the original artwork during configuration. The derivative lives in .generated/birdclaw-brand/ and is emitted with a content hash; the full-resolution documentation image remains unchanged. Sharp is a build-only dependency.

The CLI build bundles the Effect modules it uses to reduce process startup work. Other direct dependencies remain external, and the installed package keeps the same Node and Bun runtime contracts.

The wrapper installs and verifies the exact Rust-port canary recorded in toolchains/bun-canary.conf; it refuses a newer rolling canary with a different checksum or revision. CI also runs Bun/Istanbul and Node/V8 coverage, dual-runtime installed-package smoke, and Playwright against the Bun production server.

License

MIT. Created by Peter Steinberger. Birdclaw is not affiliated with X Corp.

birdclaw (steipete/birdclaw)

正在搜索数据库…

这是什么?Birdclaw 会把你的 Twitter/X 存档导入到本地 SQLite 数据库中,并让你通过网页应用、CLI,或可选的只读 MCP 服务器来搜索和浏览。
怎么把它跑起来?在 macOS 或 Linux 上用 Homebrew 安装,也可以用 npm 安装。然后运行内置的 demo,它会在无需凭据的情况下填充示例数据,你可以先试着搜索一下,再导入自己的存档。
我需要先安装 Node.js 或 Bun 吗?通过 npm 或 Homebrew 安装时,需要 Node.js >=26.5.1 <27。从源码开发时使用固定版本的 Bun canary,并保留经过测试的 Node 作为备选。
有什么需要注意的坑吗?在新数据库上首次实时同步之前,先导入一份存档。实时读取是显式触发的并会缓存结果,MCP 端点在配置好令牌和公开 URL 之前一直保持关闭。
这东西到底适合谁?适合那些想要一份属于自己的、可搜索的推文、私信、收藏帖子和关注关系副本,而又不想依赖云服务的人。
我能在服务器上只运行存档查看功能吗?可以,需要主动开启只读模式。它会提供已初始化的存档,禁用网页端的修改操作和自动同步,并隐藏不可用的控件。
存档导入后,没有网络也能用吗?可以,导入、本地搜索和网页应用都能离线使用。只有实时同步需要网络连接和 X 登录会话。
我的 AI 代理能读取这份存档吗?可以,通过可选的只读 MCP 服务器,它提供缓存推文搜索和线程工具,并需要专用令牌才能访问。在配置好令牌和公开 URL 之前,该端点保持关闭。
实时同步是怎么工作的?只有在你主动请求时才会运行,它会调用 xurl 或已有的私有 bird 安装来完成。结果会被缓存,分页和速率限制的细节见同步指南。
我可以把存档放进 Git 里吗?可以,备份功能会写出确定性的 JSONL 分片,并且可以通过 Git 往返保存和还原。
有哪些类似的项目?leviathan, xerj, epiq, graphicle, hyperfide-oss, canonry, kanzo, mcp-memory
作者
steipete
大小
5.5 MB
星标
1.7K
时长
8个月
提交 · 90 天