Start

Install

GitHub Edit page

Install

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

#Requirements

  • Node.js 25.8.1 or Node 26.x (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 uses Node's native node:sqlite runtime — no system install needed

Optional but encouraged:

  • xurl — official-API live reads/writes (likes, bookmarks, blocks, mutes, posting)
  • bird — browser-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)

brew install steipete/tap/birdclaw
birdclaw --version

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

#npm / pnpm

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

birdclaw --version

The package is published as birdclaw on npm.

#From source

git clone https://github.com/steipete/birdclaw.git
cd birdclaw
fnm use
pnpm install
pnpm build
node ./bin/birdclaw.mjs --version

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

#Verify the install

birdclaw --version
birdclaw auth status --json
birdclaw db stats --json

auth status runs Birdclaw's coarse xurl status probe. Verify xurl with xurl whoami and bird with bird whoami. See Sign in for the complete setup and transport-selection model.

#Optional: xurl

# macOS
brew install --cask xdevplatform/tap/xurl

# macOS or Linux
npm install -g @xdevplatform/xurl

xurl auth oauth2 --app my-app
xurl whoami

Alternatively, use xurl's no-sudo install script. Register my-app through the xurl authentication guide, keeping the client secret out of shared shell history and process listings. The redirect URI configured in the X developer portal must match xurl's configured URI. Birdclaw shells out to xurl and does not own ~/.xurl.

#Optional: bird

npm install -g @steipete/bird
bird whoami

bird reads cookies from a logged-in Safari, Chrome, or Firefox profile. This matters most for DMs, mentions, timeline reads, and moderation flows where X 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

export OPENAI_API_KEY="sk-..."

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
brew uninstall birdclaw

# npm
pnpm rm -g birdclaw

# Optional: also remove local data
rm -rf ~/.birdclaw

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.