Jonathon's AI Wiki

birdclaw (Local Twitter Workspace + Agent Skill)

4 min read

Source: Steipete Birdclaw 2026 04 27

birdclaw (Stefan Petri / @steipete, github.com/steipete/birdclaw) is a local-first Twitter/X workspace that archives tweets, DMs, likes, and bookmarks into a SQLite database at ~/.birdclaw and exposes them through (a) a web UI with home / mentions / DMs / inbox / blocks lanes, (b) a CLI for compose / search / sync / blocklist management, and (c) a .agents/skills/birdclaw Claude/agent skill that lets AI agents read and act on Twitter data programmatically. MIT, 377 GitHub stars, version 0.2.1 (April 2026), built on Node 25 + TypeScript + Vite + Playwright. Status: “work in progress but real and usable.”

Key Takeaways

  • Local-first storage. Tweets, likes, bookmarks, profiles, and full DM threads land in SQLite at ~/.birdclaw; media and avatars cached locally. No vendor lock-in, no rate-limit surprises during analysis runs.
  • FTS5 search. Full-text search over tweets and DMs runs on the local SQLite — fast, scriptable, and survives Twitter API access changes.
  • Three surfaces. A web UI for human triage, a CLI (birdclaw …) for scripting, and the .agents/skills/birdclaw directory for AI agents — same database underneath.
  • Live sync via xurl/bird. Likes and bookmarks sync live through the bundled xurl or bird clients; archive imports cover historical tweets, likes, profiles, and DMs.
  • AI-ranked inbox. Mentions and incoming activity flow into an inbox that can be ranked/sorted by an LLM — the Claude skill is how that ranking gets driven.
  • Git-friendly text backups. JSONL shards integrate with Git repos for diffable, auditable archives that play nicely with version control.
  • Verify-before-write discipline. Forced xurl writes still verify through bird status before committing to SQLite — the skill is built so an agent can’t silently corrupt the local store.

Implementation

Tool/Service: birdclaw v0.2.1 (steipete, MIT)

Setup (Homebrew):

brew install steipete/birdclaw/birdclaw

Setup (from source):

git clone https://github.com/steipete/birdclaw.git
cd birdclaw
pnpm install
pnpm build

Setup (the agent skill): Once installed, the .agents/skills/birdclaw directory becomes the contract for AI agents. Point Claude (or another agent that reads .agents/skills/) at the project, and the agent gains birdclaw auth status, birdclaw search, inbox query, and triage capabilities through stable JSON.

Cost: Free (MIT). No SaaS dependency — costs are: local disk for the SQLite DB and any X/Twitter API/scraping access you bring yourself.

Integration notes:

  • Set BIRDCLAW_BACKUP_AUTO_SYNC=0 to disable Git backup sync if you don’t want every data-changing command pulling/pushing.
  • Read paths (CLI search, inbox, API status/query, web startup) merge from the Git backup only when the last backup check is stale — so day-to-day reads stay fast.
  • Pairs naturally with social-media-skills (X/Twitter posts in your voice) and last30days-skill (X aggregation) — birdclaw is the local X data layer; those are the generative skills. Same person (steipete) is referenced as a worked example in last30days-skill’s README.

Try It

  • Install birdclaw, import your X archive, and run a Claude session pointed at the project — ask the agent to “find every DM thread where I discussed X” and verify the FTS5 search returns useful clusters.
  • Build a triage routine: birdclaw inbox → Claude ranks by signal → output a daily brief of the 5 mentions worth replying to. Pairs well with a scheduled task running each morning.
  • Use birdclaw + git backups as a personal X archive that survives platform changes — the SQLite + JSONL combination is portable and queryable years from now.

Graph View

Backlinks