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 26.5.1 (managed via fnm, nvm, or volta)
  • pnpm 11.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 — recommended official-API live reads/writes (likes, bookmarks, blocks, mutes, posting)
  • an existing private bird installation — optional browser-cookie-backed compatibility fallback
  • 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. Existing private bird users can verify 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.

#Existing bird installations

Birdclaw preserves compatibility with existing private bird installations, but bird is not a public setup path for new users. If bird is already installed, verify it with bird whoami.

This compatibility path 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.