x-bookmarks

name	x-bookmarks
version	1.1.0
description	Fetch, summarize, and manage X/Twitter bookmarks via bird CLI or X API v2. Use when: (1) user says "check my bookmarks", "what did I bookmark", "bookmark digest", "summarize my bookmarks", "x bookmarks", "twitter bookmarks", (2) user wants a periodic digest of saved tweets, (3) user wants to categorize, search, or analyze their bookmarks, (4) scheduled bookmark digests via cron. Auth: bird CLI with browser cookies, OR X API v2 with OAuth 2.0 tokens.
requires	{"env":[{"AUTH_TOKEN":"X/Twitter auth token (from browser cookies, for bird CLI auth)"},{"CT0":"X/Twitter CSRF token (from browser cookies, for bird CLI auth)"},{"X_API_BEARER_TOKEN":"Optional: X API v2 Bearer token (alternative to bird CLI)"}],"bins":[{"bird":"bird-cli (npm i -g bird-cli) - preferred backend"}],"files":[{".env.bird":"Optional: stores AUTH_TOKEN and CT0 for bird CLI"},{"~/.config/x-bookmarks/tokens.json":"OAuth 2.0 tokens for X API v2 backend"}]}
security	{"credentials":"This skill accesses X/Twitter bookmarks, which requires authentication. Two methods are supported: (1) bird CLI using browser cookies (AUTH_TOKEN/CT0 env vars sourced from .env.bird), or (2) X API v2 with OAuth 2.0 tokens stored locally. All credentials are stored locally on the user's machine and never transmitted to third parties. The user must explicitly provide or authorize credentials.\n","permissions":[{"read":"X/Twitter bookmarks (read-only access)"},{"write":"Local files only (bookmark state, token storage)"}]}

X Bookmarks v2

Turn X/Twitter bookmarks from a graveyard of good intentions into actionable work.

Core philosophy: Don't just summarize — propose actions the agent can execute.

Data Source Selection

This skill supports two backends. Pick the first one that works:

1. bird CLI (preferred if available)

• Fast, no API key needed, uses browser cookies
• Install: npm install -g bird-cli
• Test: bird whoami — if this prints a username, you're good

2. X API v2 (fallback)

• Works without bird CLI
• Requires an X Developer account + OAuth 2.0 app
• Setup: see references/auth-setup.md → "X API Setup"

Auto-detection logic

1. Check if `bird` command exists → try `bird whoami`
2. If bird works → use bird CLI path
3. If not → check for X API tokens (~/.config/x-bookmarks/tokens.json)
4. If tokens exist → use X API path (auto-refresh)
5. If neither → guide user through setup (offer both options)

Fetching Bookmarks

Via bird CLI

# Latest 20 bookmarks (default)
bird bookmarks --json

# Specific count
bird bookmarks -n 50 --json

# All bookmarks (paginated)
bird bookmarks --all --json

# With thread context
bird bookmarks --include-parent --thread-meta --json

# With Chrome cookie auth
bird --chrome-profile "Default" bookmarks --json

# With manual tokens
bird --auth-token "$AUTH_TOKEN" --ct0 "$CT0" bookmarks --json

If user has a .env.bird file or env vars AUTH_TOKEN/CT0, source them first: source .env.bird

Via X API v2

# First-time setup (opens browser for OAuth)
python3 scripts/x_api_auth.py --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_SECRET"

# Fetch bookmarks (auto-refreshes token)
python3 scripts/fetch_bookmarks_api.py -n 20


python3 scripts/fetch_bookmarks_api.py --all


python3 scripts/fetch_bookmarks_api.py --since-id 


python3 scripts/fetch_bookmarks_api.py -n 50 --pretty