birdclaw is a local-first Twitter workspace designed to provide a comprehensive and persistent archive of your interactions on the X platform. Developed as both a command-line interface (CLI) and a local web application, it enables users to reclaim ownership of their data by storing tweets, direct messages (DMs), likes, bookmarks, and network connections within a local SQLite database. By prioritizing a local-first architecture, birdclaw ensures that your history remains accessible even if platform access is restricted or API policies change, offering a reliable way to search, triage, and backup your social history. The tool bridges the gap between official API-driven data and browser-based scraping methods, allowing users to choose the best transport method for their needs.

Functionality centers on building and maintaining a local, searchable repository of all relevant social media activity. It automates the ingestion of data from Twitter/X archives and supplements this with live synchronization of new activity such as mentions, bookmarks, and timeline updates. The system provides a unified interface for triage, including AI-ranked inbox management and focused reply flows, while ensuring that all data is backed up into a Git-friendly, sharded format for long-term preservation.

Some of the key features are:

• Local SQLite Store: A centralized, multi-account, and FTS5-indexed database for all social data including DMs, likes, and follows.
• Archive-First Approach: Seamless import of official Twitter/X data archives to establish a baseline, with selective re-importing capabilities.
• Flexible Live Sync: Sync authored content, timelines, and mentions using either official API-backed tools or browser-cookie-backed alternatives.
• Local Web App: A focused interface for reading, triaging mentions, and exploring saved posts without the typical platform dashboard distractions.
• AI-Enhanced Triage: Optional integration with OpenAI for low-signal filtering and scoring of DMs and mentions.
• Git-Friendly Backups: Export local data into deterministic, sharded JSONL files that can be version-controlled in a private repository.
• Media Caching: Automatic local caching of images, videos, and animated GIFs, including reuse of data already present in existing archives.
• Moderation Tools: Centralized management of blocklists and mute lists, with support for bulk import and cross-account synchronization.

Operating birdclaw involves initializing a local workspace and optionally connecting external transport tools like xurl or bird for live data synchronization. Once the workspace is established, users can perform bulk imports of their historical data and schedule routine synchronization jobs to keep their local copy up to date. The command-line interface provides granular control over each sync step, while the local web server presents this data in a clean, focused user interface for daily use. Because it operates locally, it serves as a robust personal knowledge management system for social media discourse.

Some common use cases include:

• Personal Archival: Preserving your entire history of tweets, likes, and bookmarks for personal research or legacy purposes.
• Triage and Filtering: Managing high-volume mention streams using automated scoring to focus on important interactions.
• Cross-Account Management: Handling multiple Twitter/X accounts within a single workspace to aggregate information or simplify moderation workflows.
• Git-Backed Data Backup: Maintaining a version-controlled history of all interactions that can be audited, searched, or restored as needed.
• Offline Analysis: Performing complex searches and analysis on your historical data without needing an active internet connection.