[[
wikihub
]]
Search
⌘K
Explore
Activity
People
For Agents
Sign in
Explore
Activity
People
For Agents
Sign in
×
@jacobcole / Vibe Coding Tutorial / memory-workshop/birdclaw.md
Suggest edit
Cancel
Submit suggestion
Title
Name
Note
--- title: Birdclaw — your X/Twitter archive, local visibility: public --- # Birdclaw *Stores all your tweets nicely claw-able for agents.* [Birdclaw](https://birdclaw.sh) imports your X/Twitter archive into a fast local **SQLite** database and gives you a web app plus a CLI over it: years of tweets, bookmarks, likes, followers, following, and DMs, all searchable offline. It's from [@steipete](https://x.com/steipete), the same person behind OpenClaw — which is why the CLI is so agent-friendly: nearly every command takes `--json`. That `--json` flag is the whole point for this workshop. Your OpenClaw agent can shell out to `birdclaw` and answer questions about your own history. > **⏳ Start the archive request FIRST** > X takes anywhere from a few hours to a few days to prepare your download. Request it now, then do the rest of the workshop while you wait. > ➤ [x.com/settings/download_your_data](https://x.com/settings/download_your_data) --- ## 01 — Install ```bash brew install steipete/tap/birdclaw birdclaw --version ``` ## 02 — Initialize ```bash birdclaw init birdclaw auth status --json birdclaw db stats --json ``` `db stats` will show an empty database — that's expected until the import. ## 03 — Import your archive When the zip from X arrives in your Downloads folder: ```bash birdclaw archive find --json # locates the zip for you birdclaw import archive --json ``` Or point at it explicitly: ```bash birdclaw import archive ~/Downloads/twitter-archive-2026.zip --json ``` Optionally fill in profile details for the accounts in your archive: ```bash birdclaw import hydrate-profiles --json ``` ## 04 — Sync live state The archive is a snapshot. These pull in what's happened since — and bookmarks in particular, which aren't fully accessible through the API, are the reason the sync jobs exist: ```bash birdclaw sync likes --mode auto --limit 100 --refresh --json birdclaw sync bookmarks --mode auto --limit 100 --refresh --json birdclaw sync timeline --limit 100 --refresh --json birdclaw sync mention-threads --limit 30 --delay-ms 1500 --json ``` Run these on a schedule (cron, or an OpenClaw cron job) and your local copy stays current. ## 05 — Open the app ```bash birdclaw serve ``` Then open **http://localhost:3000**. Archive browsing, search, triage, and reply flows in one place. ## 06 — Back it up to GitHub ```bash birdclaw backup sync \ --repo ~/Projects/backup-birdclaw \ --remote https://github.com/username/backup-birdclaw.git \ --json ``` Set `backup.autoSync` in `~/.birdclaw/config.json` to make it automatic. **Use a private repo** — this contains your DMs. --- ## Pointing your agent at it This is where it stops being an archive tool and starts being memory. Because every command speaks JSON, your OpenClaw agent can just run them. Things worth asking once it's wired up: - *"What have I said about agent memory over the years? Quote me."* - *"Which of my bookmarks from the last month have I never acted on?"* - *"Find the thread where someone explained X to me — I can't remember who."* - *"Draft a post in my voice, using my actual past posts as the style reference."* The last one only works well *because* the corpus is yours. A model guessing at your voice is imitation; a model reading three years of your own posts is retrieval. ## Gramclaw — the Instagram sibling **Gramclaw** does the same thing for Instagram: imports an Instagram export into local SQLite with media analysis, natural-language visual search, Smart Saved collections, and exportable moodboards. Same shape as Birdclaw — local-first, JSON-first CLI, agent-readable. There are **two versions**. The official site and build live at **[gramclaw.globalbr.ai](https://gramclaw.globalbr.ai)**; the fork is mirrored on jacobcole.ai. Either installs without npm registry access or a GitHub clone. ### Official — by [Art Jing](https://github.com/artjing) The upstream project. Start here unless you specifically want Instagram sign-in. ```bash npm install -g https://gramclaw.globalbr.ai/downloads/gramclaw-1.1.0.tgz ``` ➤ [gramclaw.globalbr.ai](https://gramclaw.globalbr.ai) — site, demo, and download · [github.com/artjing/gramclaw](https://github.com/artjing/gramclaw) ### Fork — adds direct Instagram sign-in My fork of the above. Everything the official build does, plus signing in to Instagram directly instead of going through the export flow. ```bash npm install -g https://jacobcole.ai/downloads/gramclaw-fork-1.1.0.tgz ``` ➤ [github.com/tmad4000/gramclaw](https://github.com/tmad4000/gramclaw) Both are version 1.1.0 and install the same `gramclaw` command, so **pick one** — installing the second over the first replaces it. ### Either way ```bash gramclaw init --demo # fictional sample content, no Instagram login needed gramclaw serve --open ``` For a real archive: `gramclaw import archive ~/Downloads/instagram-export.zip --json` > **📲 One-click versions of both installs** are on the [Memory Workshop page](https://jacobcole.ai/memory-workshop/). ## Troubleshooting | Symptom | Fix | | --- | --- | | `archive find` returns nothing | Give the explicit path to the zip; don't unzip it first | | Import looks like it hung | Large archives take a while — `birdclaw db stats --json` in another terminal shows progress | | Port 3000 already in use | Something else is on it. Stop that, or check `birdclaw serve --help` for a port flag | | Sync commands rate-limited | Raise `--delay-ms`, lower `--limit`, and run less often | ➤ [birdclaw.sh](https://birdclaw.sh) · [Quickstart](https://birdclaw.sh/quickstart.html) · [github.com/steipete/birdclaw](https://github.com/steipete/birdclaw) --- **Next:** [Group chats (beta) →](groupchats-beta.md) · **Back:** [Workshop index](index.md) **Memory Workshop:** [jacobcole.ai/memory-workshop](https://jacobcole.ai/memory-workshop/) — every command here as a copy button.