birdclaw 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-04-27
+
+### Added
+
+- Add X web cookie fallback for block and unblock actions when the X API rejects OAuth2 block writes.
+- Add `profiles replies` so moderation triage can inspect a user's recent reply pattern before blocking.
+- Add `blocks import <path>` for one-shot blocklist application from a file.
+- Add paged `mentions export --mode xurl --all --max-pages <n>` so moderation loops can scan the full retrievable mentions window.
+- Add `actions.transport` config plus shared action transport routing for `bird`, `xurl`, and `auto`.
+- Add transport-aware mute/unmute support to the API action route.
+- Add the first packaged `birdclaw` CLI release.
+
+### Fixed
+
+- Capture `xurl` mutation error bodies so transport fallbacks can key off the real API failure.
+- Make `birdclaw` block and unblock flows succeed remotely again on Peter's current auth setup.
+- Verify forced `xurl` mute/block writes through `bird status` before mutating local sqlite.
+- Cache authenticated `xurl whoami` lookups so repeated moderation writes do less redundant auth work.
+- Strip inherited `--localstorage-file` from the Playwright web-server env to avoid noisy cross-repo test warnings.
+- Override Node 25 native web storage in jsdom test setup so Vitest runs stop emitting `--localstorage-file` warnings.
+
+### Docs
+
+- Document block transport behavior and fallback path in the CLI/docs.
+- Document the reply-pattern inspection flow for borderline AI/slop accounts.
+- Document blocklist import file format and usage.
+- Document paged xurl mention export for agent moderation runs.
+- Document that mention reads and moderation writes use separate config knobs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,389 @@
+# birdclaw
+
+`birdclaw` is a local-first X workspace: archive import, cached live reads, focused triage, and reply flows in one local web app + CLI.
+
+Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and rough edges while the core settles.
+
+## What It Does
+
+- keeps your X data in local SQLite
+- stores media and avatar cache under `~/.birdclaw`
+- imports archives when you have them
+- still works when you do not
+- gives you a clean local UI for home, mentions, DMs, inbox, and blocks
+- exposes scriptable JSON for agents and automation
+
+## What Works Today
+
+### Local data + storage
+
+- one shared SQLite DB for multiple accounts
+- FTS5 search over tweets and DMs
+- archive autodiscovery on macOS
+- archive import for tweets, likes, profiles, and full DMs
+- profile hydration from live X metadata
+- local avatar cache
+- local media cache root under `~/.birdclaw`
+
+### Web UI
+
+- `Home` timeline
+- `Mentions` queue
+- `DMs` workspace with two-column layout
+- `Inbox` for mixed mention + DM triage
+- `Blocks` for local blocklist maintenance
+- constrained timeline lane instead of full-width dashboard UI
+- tweet expansion with URLs, inline images, quoted tweets, replies, and profile hover cards
+- sender bio and influence context in the DM detail header
+- system / light / dark theme switcher with animated transition
+
+### Triage + filtering
+
+- replied / unreplied filters for timelines
+- DM filters by participant, followers, and derived influence score
+- AI-ranked inbox for mentions + DMs
+- OpenAI scoring hook for low-signal filtering
+- cached live mentions export in `xurl`-compatible JSON
+- live profile-reply inspection for borderline AI/slop triage
+- one-shot blocklist import from a file for batch moderation passes
+
+### Actions
+
+- post tweets
+- reply to tweets
+- reply to DMs
+- add / remove local blocks
+- import batch blocklists in one call
+- add / remove local mutes
+- sync remote blocks through `xurl` when available
+- fall back to the X web cookie session when OAuth2 block writes are rejected
+
+### Safety
+
+- local-first by default
+- tests disable live writes
+- CI disables live writes
+- app has no auth layer because it is a local-only tool
+
+## Still In Progress
+
+- broader resumable live sync beyond the targeted paths already wired
+- fuller media fetch pipeline
+- richer multi-account UX
+- more complete transport coverage
+- more archive edge-case handling
+
+If you need polished product-grade sync parity today, this is not there yet.
+
+## Screens
+
+- `Home`: read and reply without fighting the main X timeline
+- `Mentions`: work the reply queue with clean filters
+- `DMs`: triage by sender context, follower count, and influence
+- `Inbox`: let heuristics / OpenAI float likely-important items
+- `Blocks`: maintain a local-first account-scoped blocklist
+
+## Storage
+
+Default root:
+
+```text
+~/.birdclaw
+```
+
+Important paths:
+
+- DB: `~/.birdclaw/birdclaw.sqlite`
+- media cache: `~/.birdclaw/media`
+- avatar cache: `~/.birdclaw/media/thumbs/avatars`
+- Playwright test home: `.playwright-home`
+
+Override the root:
+
+```bash
+export BIRDCLAW_HOME=/path/to/custom/root
+```
+
+## Requirements
+
+- Node `25.8.1`
+- `pnpm`
+- macOS recommended for Spotlight archive discovery
+- `xurl` optional for live reads / writes
+- OpenAI API key optional for inbox scoring
+
+## Install
+
+Homebrew:
+
+```bash
+brew install steipete/tap/birdclaw
+```
+
+From source:
+
+```bash
+fnm use
+pnpm install
+```
+
+## Run
+
+```bash
+pnpm dev
+```
+
+Open:
+
+```text
+http://localhost:3000
+```
+
+## Quick Start
+
+Initialize local state:
+
+```bash
+birdclaw init
+birdclaw auth status --json
+birdclaw db stats --json
+```
+
+Find and import an archive:
+
+```bash
+birdclaw archive find --json
+birdclaw import archive --json
+birdclaw import archive ~/Downloads/twitter-archive-2025.zip --json
+birdclaw import hydrate-profiles --json
+```
+
+Start the app:
+
+```bash
+birdclaw serve
+```
+
+First moderation pass:
+
+```bash
+pnpm cli mentions export --mode xurl --refresh --all --max-pages 9 --limit 100
+pnpm cli profiles replies @borderline_handle --limit 12 --json
+pnpm cli blocks import ~/triage/blocklist.txt --account acct_primary --json
+```
+
+## CLI Highlights
+
+### Search local tweets
+
+```bash
+pnpm cli search tweets "local-first" --json
+pnpm cli search tweets "sync engine" --limit 20 --json
+```
+
+### Export mentions for agents
+
+Default `birdclaw` mode returns normalized items with `text`, `plainText`, `markdown`, author metadata, and canonical URLs:
+
+```bash
+pnpm cli mentions export "agent" --unreplied --limit 10
+```
+
+Cached live modes return `xurl`-compatible `data/includes/meta`, but stay in the local SQLite cache so repeat reads do not keep spending live calls:
+
+```bash
+pnpm cli mentions export --mode bird --limit 20
+pnpm cli mentions export --mode bird --refresh --limit 20
+pnpm cli mentions export --mode xurl --limit 5
+pnpm cli mentions export --mode xurl --refresh --limit 5
+pnpm cli mentions export --mode xurl --refresh --all --max-pages 9 --limit 100
+pnpm cli mentions export "courtesy" --mode xurl --limit 5
+```
+
+Home config lives in `~/.birdclaw/config.json`. Example:
+
+```json
+{
+  "actions": {
+    "transport": "auto"
+  },
+  "mentions": {
+    "dataSource": "bird",
+    "birdCommand": "/Users/steipete/Projects/bird/bird"
+  }
+}
+```
+
+Notes:
+
+- `--refresh` forces a live fetch
+- `--cache-ttl <seconds>` tunes freshness
+- `--all` walks every retrievable mentions page; `--max-pages` caps that scan
+- in paged `xurl` mode, `--limit` is the per-page size
+- `mentions.dataSource` controls live mention reads only
+- `actions.transport` controls live block/mute writes only
+- `actions.transport` accepts `auto`, `bird`, or `xurl`
+- `bird` mode uses your local `bird` CLI and caches its mentions output into birdclaw's canonical store
+- filters still work in `xurl` mode; filtered payloads are rebuilt from the local canonical store after sync
+
+### Search and triage DMs
+
+```bash
+pnpm cli search dms "prototype" --json
+pnpm cli search dms "layout" --min-followers 1000 --min-influence-score 120 --sort influence --json
+pnpm cli dms sync --limit 50 --refresh --json
+pnpm cli dms list --refresh --limit 10 --json
+pnpm cli dms list --unreplied --min-followers 500 --min-influence-score 90 --sort influence --json
+```
+
+### AI inbox
+
+```bash
+pnpm cli inbox --json
+pnpm cli inbox --kind dms --limit 10 --json
+pnpm cli inbox --score --hide-low-signal --limit 8 --json
+```
+
+### Blocklist
+
+```bash
+pnpm cli blocks list --account acct_primary --json
+pnpm cli blocks sync --account acct_primary --json
+pnpm cli blocks import ~/triage/blocklist.txt --account acct_primary --json
+pnpm cli blocks add @amelia --account acct_primary --json
+pnpm cli blocks record @amelia --account acct_primary --json
+pnpm cli blocks remove @amelia --account acct_primary --json
+pnpm cli ban @amelia --account acct_primary --transport auto --json
+pnpm cli unban @amelia --account acct_primary --transport bird --json
+```
+
+Notes:
+
+- `ban` / `unban` accept `--transport auto|bird|xurl`
+- `auto` tries `bird` first, then falls back to `xurl` when bird fails
+- forced `xurl` writes still verify through `bird status` before sqlite changes
+- X still rejects pure OAuth2 block writes, so `auto` is the safe default for block/unblock
+- `blocks import` accepts newline-delimited blocklists with comments and markdown bullets
+- `blocks sync` is for slow/manual remote reconciliation; not for a hot cron loop
+- `blocks record` stores a known-good remote block locally without issuing another live write
+
+Example blocklist file:
+
+```text
+# crypto / AI slop
+@jpctan
+@SystemDaddyAi
+- @Pepe202579 memecoin bait
+https://x.com/someone/status/2030857479001960633?s=20
+```
+
+### Profile reply scan
+
+```bash
+pnpm cli profiles replies @jpctan --limit 12 --json
+```
+
+Notes:
+
+- for the "unsure if AI" case
+- scans recent authored tweets, excludes retweets, keeps replies
+- useful for spotting repeated generic praise, abstraction soup, or cross-thread templated cadence
+
+Typical tell:
+
+- same upbeat, generic reply shape across unrelated threads in a short time window
+
+### Mutes
+
+```bash
+pnpm cli mutes list --account acct_primary --json
+pnpm cli mute @amelia --account acct_primary --transport xurl --json
+pnpm cli mutes record @amelia --account acct_primary --json
+pnpm cli unmute @amelia --account acct_primary --transport auto --json
+```
+
+Notes:
+
+- `mute` / `unmute` accept `--transport auto|bird|xurl`
+- target profile resolution prefers `bird user --json` before any `xurl /2/users` lookup
+- `auto` tries `bird` first, then falls back to `xurl` when bird fails
+- forced `xurl` writes still verify through `bird status` before sqlite changes
+- `mutes record` stores a known-good remote mute locally without issuing another live write
+
+### Test env hardening
+
+- Playwright strips inherited `--localstorage-file` from `NODE_OPTIONS` before starting Vite
+- this avoids cross-repo test warnings when another repo injected that flag
+
+### Compose / reply
+
+```bash
+pnpm cli compose post "Ship local software."
+pnpm cli compose reply tweet_004 "On it."
+pnpm cli compose dm dm_003 "Send it over."
+```
+
+## Typical Workflow
+
+1. import your archive if you have one
+2. hydrate imported profiles from live X metadata
+3. use `Home` for reading
+4. use `Mentions` for reply triage
+5. when one account feels borderline, inspect `profiles replies`
+6. collect keepers into a blocklist file and run `blocks import`
+7. use `DMs` for high-context conversation work
+8. use `Inbox` when you want AI help cutting noise
+9. use CLI exports when agents need stable JSON
+
+## Live Transport
+
+Current preference:
+
+- `xurl` first
+
+Without `xurl`, `birdclaw` still works in local/archive mode.
+
+Check transport:
+
+```bash
+pnpm cli auth status --json
+```
+
+## Architecture
+
+- SQLite is the canonical local truth
+- archive import and live transport should converge on the same model
+- CLI and web UI share the same normalized core
+- AI ranking is layered on top of local data, not the source of truth
+
+## Testing
+
+```bash
+fnm exec --using 25.8.1 pnpm check
+fnm exec --using 25.8.1 pnpm test
+fnm exec --using 25.8.1 pnpm coverage
+fnm exec --using 25.8.1 pnpm build
+fnm exec --using 25.8.1 pnpm e2e
+```
+
+Current bar:
+
+- branch coverage above `80%`
+- Playwright coverage for core UI flows
+
+## CI
+
+GitHub Actions runs:
+
+- `pnpm check`
+- `pnpm coverage`
+- `pnpm build`
+- `pnpm e2e`
+
+Workflow: [ci.yml](/Users/steipete/Projects/birdclaw/.github/workflows/ci.yml)
+
+## Docs
+
+- [spec.md](/Users/steipete/Projects/birdclaw/docs/spec.md)
+- [cli.md](/Users/steipete/Projects/birdclaw/docs/cli.md)
+- [data-architecture.md](/Users/steipete/Projects/birdclaw/docs/data-architecture.md)

package/bin/birdclaw.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const tsxCli = join(packageRoot, "node_modules", "tsx", "dist", "cli.mjs");
+const birdclawCli = join(packageRoot, "src", "cli.ts");
+
+const result = spawnSync(
+	process.execPath,
+	[tsxCli, birdclawCli, ...process.argv.slice(2)],
+	{
+		stdio: "inherit",
+		env: process.env,
+	},
+);
+
+if (result.error) {
+	console.error(result.error.message);
+	process.exit(1);
+}
+
+if (result.signal) {
+	process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,100 @@
+{
+	"name": "birdclaw",
+	"version": "0.1.0",
+	"description": "Local-first X workspace for archives, DMs, mentions, and moderation",
+	"homepage": "https://github.com/steipete/birdclaw#readme",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/steipete/birdclaw.git"
+	},
+	"bin": {
+		"birdclaw": "bin/birdclaw.mjs"
+	},
+	"files": [
+		"bin/",
+		"src/",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
+		"!src/test/",
+		"public/",
+		"CHANGELOG.md",
+		"LICENSE",
+		"README.md",
+		"package.json",
+		"playwright.config.ts",
+		"pnpm-lock.yaml",
+		"tsconfig.json",
+		"vite.config.ts"
+	],
+	"type": "module",
+	"imports": {
+		"#/*": "./src/*"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"dev": "vite dev --port 3000",
+		"build": "vite build",
+		"preview": "vite preview",
+		"test": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run",
+		"coverage": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run --coverage",
+		"e2e": "playwright test",
+		"format": "oxfmt --write src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"format:check": "oxfmt --check src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"lint": "oxlint --import-plugin --node-plugin --vitest-plugin --deny-warnings -A require-mock-type-parameters -A no-control-regex src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"check": "pnpm run format:check && pnpm run lint",
+		"cli": "tsx src/cli.ts"
+	},
+	"dependencies": {
+		"@steipete/sweet-cookie": "^0.2.0",
+		"@tailwindcss/vite": "^4.2.4",
+		"@tanstack/devtools-vite": "0.6.0",
+		"@tanstack/react-devtools": "0.10.2",
+		"@tanstack/react-router": "1.168.24",
+		"@tanstack/react-router-devtools": "1.166.13",
+		"@tanstack/react-router-ssr-query": "1.166.12",
+		"@tanstack/react-start": "1.167.49",
+		"@tanstack/router-plugin": "^1.167.27",
+		"@vitejs/plugin-react": "^6.0.1",
+		"better-sqlite3": "^12.9.0",
+		"commander": "^14.0.3",
+		"kysely": "^0.28.16",
+		"lucide-react": "^1.11.0",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5",
+		"tailwindcss": "^4.2.4",
+		"tsx": "^4.21.0",
+		"vite": "^8.0.10",
+		"zod": "^4.3.6"
+	},
+	"devDependencies": {
+		"@playwright/test": "^1.59.1",
+		"@tailwindcss/typography": "^0.5.19",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
+		"@types/better-sqlite3": "^7.6.13",
+		"@types/node": "^25.6.0",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitest/coverage-v8": "^4.1.5",
+		"jsdom": "^29.0.2",
+		"oxfmt": "^0.46.0",
+		"oxlint": "^1.61.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.5"
+	},
+	"engines": {
+		"node": ">=25.8.1 <26"
+	},
+	"packageManager": "pnpm@10.31.0",
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"better-sqlite3",
+			"esbuild",
+			"lightningcss"
+		]
+	}
+}

package/playwright.config.ts

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { defineConfig, devices } from "@playwright/test";
+
+const testHome = path.join(process.cwd(), ".playwright-home");
+
+export default defineConfig({
+	testDir: "./playwright",
+	fullyParallel: false,
+	retries: 0,
+	workers: 1,
+	use: {
+		baseURL: "http://127.0.0.1:3000",
+		trace: "on-first-retry",
+	},
+	projects: [
+		{
+			name: "chromium",
+			use: { ...devices["Desktop Chrome"] },
+		},
+	],
+	webServer: {
+		command: "node ./scripts/start-test-server.mjs",
+		url: "http://127.0.0.1:3000",
+		reuseExistingServer: false,
+		timeout: 120000,
+		env: {
+			BIRDCLAW_HOME: testHome,
+			BIRDCLAW_DISABLE_LIVE_WRITES: "1",
+		},
+	},
+});

package/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "TanStack App",
+  "name": "Create TanStack App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

package/public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow: