Install

birdclaw ships as a Node CLI plus a local web app. Pick whichever path fits the machine.

#Requirements

Node.js 25.8.1 (managed via fnm, nvm, or volta)
pnpm 10.x for source installs
macOS is recommended for archive autodiscovery (Spotlight mdfind); Linux works for everything else
SQLite is bundled via better-sqlite3 — no system install needed

Optional but encouraged:

xurl — official-API live reads/writes (likes, bookmarks, blocks, mutes, posting)
bird — cookie-backed reads/writes for surfaces where xurl is rate-limited or unavailable
OPENAI_API_KEY — inbox scoring and low-signal filtering

birdclaw still works in pure local/archive mode without any of the above.

#Homebrew (macOS, Linux)

0 install steipete/tap/1
1 0

The Homebrew formula lives in steipete/homebrew-tap and installs the birdclaw binary plus a launchd plist target.

#npm / pnpm

1 add 0 2
# or
1 install 0 2

1 0

The package is published as birdclaw on npm.

#From source

0 clone https://github.com/steipete/1.2
0 1
fnm use
0 install
0 build
1 ./bin/2.mjs 0

fnm use reads the version from .node-version. Source builds run the same tsx-based entrypoint as the published binary.

#Verify the install

1 0
1 auth status 0
1 db stats 0

auth status prints which transports are wired up (archive, xurl, bird, xweb) and which account is currently active.

#Optional: xurl

0 install xdevplatform/tap/1
0 auth login

After xurl auth login succeeds, birdclaw will pick xurl first for live reads and writes. No extra wiring needed — birdclaw shells out to xurl rather than owning ~/.xurl itself.

#Optional: bird

0 install steipete/tap/1
0 auth import-cookies

Once bird is in PATH, birdclaw uses it as the cookie-backed fallback. This matters most for DMs, mentions, blocks, and any block/unblock flow where Twitter rejects OAuth2 writes.

If you only run birdclaw via launchd (jobs install-bookmarks-launchd), bird may need its AUTH_TOKEN/CT0 exported via an env file because launchd does not see your interactive browser session. See Jobs.

#Optional: OpenAI

1 OPENAI_API_KEY=0

Add it to ~/.profile or your shell rc to persist. The inbox uses OpenAI for low-signal scoring; without the key, inbox --score is a no-op and the heuristic ranker still works.

#Updating

Homebrew: brew upgrade birdclaw.
npm: pnpm up -g birdclaw (or npm i -g birdclaw@latest).
Source: git pull && pnpm install && pnpm build.

The local SQLite store is forward-compatible across point releases. Long-running schema migrations run on startup; birdclaw db stats --json reports the current schema version.

#Uninstall

# Homebrew
0 uninstall 1

# 0
1 2 0 3

# Optional: also remove local data
1 0 ~/.2

The local data root defaults to ~/.birdclaw (override via BIRDCLAW_HOME). Removing it deletes your imported archive, media cache, and live cache. Backup shards are stored separately if you set up backup sync.