birdclaw

library0.7.0jsnpmunverified

birdclaw (v0.7.0) is a local-first Twitter workspace that stores your Twitter data (archives, DMs, likes, bookmarks) in SQLite. It provides a web UI and CLI for browsing timelines, triaging mentions/DMs, managing blocks, and performing moderation. Built with Effect for async operations, it emphasizes privacy by keeping all data locally. Target Node.js >=25.8.1 <27. Actively developed but WIP with potential schema churn.

productivity

npm install birdclaw

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BIRDCLAW

birdclaw

productivityjavascriptv0.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import birdclaw from 'birdclaw'

✗ const birdclaw = require('birdclaw')

ESM-only, no CJS support. Default export may be the entire API object.

start

✓ import { start } from 'birdclaw'

Function to launch the web UI. Requires Node.js >=25.8.1.

sync

✓ import { sync } from 'birdclaw'

Triggers live sync of timeline, DMs, etc. Requires running 'xurl' or OAuth setup.

Shows how to start the birdclaw web UI with optional API keys for sync and AI scoring.

import { start } from 'birdclaw' async function main() { await start({ port: 3000, dataDir: '~/.birdclaw', keys: { xurlApiKey: process.env.XURL_API_KEY ?? '', openaiApiKey: process.env.OPENAI_API_KEY ?? '' } }) console.log('birdclaw UI running at http://localhost:3000') } main()

Debug

Known issues

breakingSchema changes frequently in WIP versions — data migration not automatic

fix

Backup your SQLite database before upgrading. Check CHANGELOG for migration steps.

affects: <1.0.0

gotchaRequires Node.js >=25.8.1, older versions will throw an error

fix

Use nvm or volta to switch to Node.js >=25.8.1.

affects: >=0.0.0 <=0.7.0

gotchaLive writes are disabled in test and CI environments — actions may silently fail

fix

Set BIRDCLAW_ENV=development to enable writes (not for production).

affects: >=0.0.0 <=0.7.0

deprecatedUse of 'bird' CLI for sync is deprecated in favor of 'xurl'

fix

Migrate to xurl for all live sync and actions.

affects: >=0.5.0 <=0.7.0

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND: Cannot find package 'birdclaw'

Missing installation or wrong Node.js version (requires >=25.8.1)

fix

npm install birdclaw && node --version # ensure >=25.8.1

TypeError: birdclaw.start is not a function

Importing wrong symbol; default export is the entire API object, not a named function

fix

Use import birdclaw from 'birdclaw' then birdclaw.start({...})

Error: EACCES: permission denied, open '/home/user/.birdclaw/config.json'

Data directory permissions issue

fix

Ensure ~/.birdclaw directory is writable by the user running the process

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/steipete/birdclaw ↗

packagebirdclaw ↗

homepagehttps://github.com/steipete/birdclaw#readme ↗