Skip to content
Back to search

x-bookmarks

SkillWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sharbelxyz--x-bookmarks/badge.svg)](/listings/sharbelxyz--x-bookmarks)

HTML

<a href="/listings/sharbelxyz--x-bookmarks"><img src="/api/listings/sharbelxyz--x-bookmarks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: bird CLI (easiest)

npm install -g bird-cli
# Log into x.com in Chrome, then:
bird --chrome-profile "Default" bookmarks --json

Option 2: X API v2 (no bird needed)

# One-time: create app at https://developer.x.com, then:
python3 scripts/x_api_auth.py --client-id "YOUR_CLIENT_ID"

# Fetch bookmarks
python3 scripts/fetch_bookmarks_api.py -n 20

Both backends output the same JSON format — all workflows work with either.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 218 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: x-bookmarks
  3. version: 1.1.0
  4. description: >
  5. Fetch, summarize, and manage X/Twitter bookmarks via bird CLI or X API v2.
  6. Use when: (1) user says "check my bookmarks", "what did I bookmark", "bookmark digest",
  7. "summarize my bookmarks", "x bookmarks", "twitter bookmarks", (2) user wants a periodic
  8. digest of saved tweets, (3) user wants to categorize, search, or analyze their bookmarks,
  9. (4) scheduled bookmark digests via cron.
  10. Auth: bird CLI with browser cookies, OR X API v2 with OAuth 2.0 tokens.
  11. requires:
  12. env:
  13. - AUTH_TOKEN: "X/Twitter auth token (from browser cookies, for bird CLI auth)"
  14. - CT0: "X/Twitter CSRF token (from browser cookies, for bird CLI auth)"
  15. - X_API_BEARER_TOKEN: "Optional: X API v2 Bearer token (alternative to bird CLI)"
  16. bins:
  17. - bird: "bird-cli (npm i -g bird-cli) - preferred backend"
  18. files:
  19. - .env.bird: "Optional: stores AUTH_TOKEN and CT0 for bird CLI"
  20. - ~/.config/x-bookmarks/tokens.json: "OAuth 2.0 tokens for X API v2 backend"
  21. security:
  22. credentials: >
  23. This skill accesses X/Twitter bookmarks, which requires authentication.
  24. Two methods are supported: (1) bird CLI using browser cookies (AUTH_TOKEN/CT0 env vars
  25. sourced from .env.bird), or (2) X API v2 with OAuth 2.0 tokens stored locally.
  26. All credentials are stored locally on the user's machine and never transmitted
  27. to third parties. The user must explicitly provide or authorize credentials.
  28. permissions:
  29. - read: "X/Twitter bookmarks (read-only access)"
  30. - write: "Local files only (bookmark state, token storage)"
  31. ---
  32. # X Bookmarks v2
  33. Turn X/Twitter bookmarks from a graveyard of good intentions into actionable work.
  34. **Core philosophy:** Don't just summarize — propose actions the agent can execute.
  35. ## Data Source Selection
  36. This skill supports **two backends**. Pick the first one that works:
  37. ### 1. bird CLI (preferred if available)
  38. - Fast, no API key needed, uses browser cookies
  39. - Install: `npm install -g bird-cli`
  40. - Test: `bird whoami` — if this prints a username, you're good
  41. ### 2. X API v2 (fallback)
  42. - Works without bird CLI
  43. - Requires an X Developer account + OAuth 2.0 app
  44. - Setup: see [references/auth-setup.md](references/auth-setup.md) → "X API Setup"
  45. ### Auto-detection logic
  46. ```
  47. 1. Check if `bird` command exists → try `bird whoami`
  48. 2. If bird works → use bird CLI path
  49. 3. If not → check for X API tokens (~/.config/x-bookmarks/tokens.json)
  50. 4. If tokens exist → use X API path (auto-refresh)
  51. 5. If neither → guide user through setup (offer both options)
  52. ```
  53. ## Fetching Bookmarks
  54. ### Via bird CLI
  55. ```bash
  56. # Latest 20 bookmarks (default)
  57. bird bookmarks --json
  58. # Specific count
  59. bird bookmarks -n 50 --json
  60. # All bookmarks (paginated)
  61. bird bookmarks --all --json
  62. # With thread context
  63. bird bookmarks --include-parent --thread-meta --json
  64. # With Chrome cookie auth
  65. bird --chrome-profile "Default" bookmarks --json
  66. # With manual tokens
  67. bird --auth-token "$AUTH_TOKEN" --ct0 "$CT0" bookmarks --json
  68. ```
  69. If user has a `.env.bird` file or env vars `AUTH_TOKEN`/`CT0`, source them first: `source .env.bird`
  70. ### Via X API v2
  71. ```bash
  72. # First-time setup (opens browser for OAuth)
  73. python3 scripts/x_api_auth.py --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_SECRET"
  74. # Fetch bookmarks (auto-refreshes token)
  75. python3 scripts/fetch_bookmarks_api.py -n 20
  76. # All bookmarks
  77. python3 scripts/fetch_bookmarks_api.py --all
  78. # Since a specific tweet
  79. python3 scripts/fetch_bookmarks_api.py --since-id "1234567890"
  80. # Pretty print
  81. python3 scripts/fetch_bookmarks_api.py -n 50 --pretty
  82. ```
  83. The API script outputs the **same JSON format** as bird CLI, so all downstream workflows work identically.
  84. **Token management is automatic:** tokens are stored in `~/.config/x-bookmarks/tokens.json` and refreshed via the saved refresh_token. If refresh fails, the agent should guide the user to re-run `x_api_auth.py`.
  85. ### Environment variable override
  86. If the user already has a Bearer token (e.g., from another tool), they can skip the OAuth dance:
  87. ```bash
  88. X_API_BEARER_TOKEN="your_token" python3 scripts/fetch_bookmarks_api.py -n 20
  89. ```
  90. ## JSON Output Format (both backends)
  91. Each bookmark returns:
  92. ```json
  93. {
  94. "id": "tweet_id",
  95. "text": "tweet content",
  96. "createdAt": "2026-02-11T01:00:06.000Z",
  97. "replyCount": 46,
  98. "retweetCount": 60,
  99. "likeCount": 801,
  100. "bookmarkCount": 12,
  101. "viewCount": 50000,
  102. "author": { "username": "handle", "name": "Display Name" },
  103. "media": [{ "type": "photo|video", "url": "..." }],
  104. "quotedTweet": { "id": "..." }
  105. }
  106. ```
  107. ## Core Workflows
  108. ### 1. Action-First Digest (Primary Use Case)
  109. The key differentiator: don't just summarize, **propose actions the agent can execute**.
  110. 1. Fetch bookmarks (bird or API, auto-detected)
  111. 2. Parse and categorize by topic (auto-detect: crypto, AI, marketing, tools, personal, etc.)
  112. 3. For EACH category, propose specific actions:
  113. - **Tool/repo bookmarks** → "I can test this, set it up, or analyze the code"
  114. - **Strategy/advice bookmarks** → "Here are the actionable steps extracted — want me to implement any?"
  115. - **News/trends** → "This connects to [user's work]. Here's the angle for content"
  116. - **Content ideas** → "This would make a great tweet/video in your voice. Here's a draft"
  117. - **Questions/discussions** → "I can research this deeper and give you a summary"
  118. 4. Flag stale bookmarks (>2 weeks old) — "Use it or lose it"
  119. 5. Deliver categorized digest with actions
  120. Format output as:
  121. ```
  122. 📂 CATEGORY (count)
  123. • Bookmark summary (@author)
  124. → 🤖 I CAN: [specific action the agent can take]
  125. ```
  126. ### 2. Scheduled Digest (Cron)
  127. Set up a recurring bookmark check. Suggest this cron config to the user:
  128. ```
  129. Schedule: daily or weekly
  130. Payload: "Check my X bookmarks for new saves since last check.
  131. Fetch bookmarks, compare against last digest, summarize only NEW ones.
  132. Categorize and propose actions. Deliver to me."
  133. ```
  134. Track state by saving the most recent bookmark ID processed. Store in workspace:
  135. `memory/bookmark-state.json` → `{ "lastSeenId": "...", "lastDigestAt": "..." }`
  136. ### 3. Content Recycling
  137. When user asks for content ideas from bookmarks:
  138. 1. Fetch recent bookmarks
  139. 2. Identify high-engagement tweets (>500 likes) with frameworks, tips, or insights
  140. 3. Rewrite key ideas in the user's voice (if voice data available)
  141. 4. Suggest posting times based on the bookmark's original engagement
  142. ### 4. Pattern Detection
  143. When user has enough bookmark history:
  144. 1. Fetch all bookmarks (`--all`)
  145. 2. Cluster by topic/keywords
  146. 3. Report: "You've bookmarked N tweets about [topic]. Want me to go deeper?"
  147. 4. Suggest: research reports, content series, or tools based on patterns
  148. ### 5. Bookmark Cleanup
  149. For stale bookmarks:
  150. 1. Identify bookmarks older than a threshold (default: 30 days)
  151. 2. For each: extract the TL;DR and one actionable takeaway
  152. 3. Present: "Apply it today or clear it"
  153. 4. User can unbookmark via: `bird unbookmark <tweet-id>` (bird only)
  154. ## Error Handling
  155. | Error | Cause | Fix |
  156. |-------|-------|-----|
  157. | `bird: command not found` | bird CLI not installed | Use X API path instead, or `npm i -g bird-cli` |
  158. | "No Twitter cookies found" | Not logged into X in browser | Log into x.com in Chrome/Firefox, or use X API |
  159. | EPERM on Safari cookies | macOS permissions | Use Chrome/Firefox or X API instead |
  160. | Empty results | Cookies/token expired | Re-login or re-run `x_api_auth.py` |
  161. | Rate limit (429) | Too many API requests | Wait and retry, use `--count` to limit |
  162. | "No X API token found" | Haven't run auth setup | Run `x_api_auth.py --client-id YOUR_ID` |
  163. | Token refresh failed | Refresh token expired | Re-run `x_api_auth.py` to re-authorize |
  164. ## Tips
  165. - Start with `-n 20` for quick digests, `--all` for deep analysis
  166. - bird: Use `--include-parent` for thread context on replies
  167. - API: includes `bookmarkCount` and `viewCount` (bird may not)
  168. - Bookmark folders supported via bird `--folder-id <id>`
  169. - Both backends output identical JSON — workflows are backend-agnostic
README.md · README · 103 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # x-bookmarks
  2. Turn X/Twitter bookmarks from a graveyard of good intentions into actionable work.
  3. ## How This Works
  4. Once installed, just tell your AI agent:
  5. > "check my bookmarks"
  6. That's it. Your agent will:
  7. 1. **Fetch** your latest X bookmarks (auto-detects bird CLI or X API v2)
  8. 2. **Categorize** them by topic (crypto, AI, marketing, tools, etc.)
  9. 3. **Propose actions** for each one — not just summaries, but things your agent can actually do:
  10. ```
  11. 📂 AI TOOLS (3)
  12. • @someone shared a repo for automating video edits
  13. → 🤖 I CAN: Clone it, test it, and set it up for you
  14. 📂 TRADING (2)
  15. • @trader posted a new momentum strategy with backtest data
  16. → 🤖 I CAN: Compare this against your current strategy and report differences
  17. ```
  18. You can also say:
  19. - **"bookmark digest"** — get a categorized summary of recent saves
  20. - **"what did I bookmark this week?"** — filtered by time
  21. - **"find patterns in my bookmarks"** — clusters topics you keep saving
  22. - **"clean up old bookmarks"** — flags stale saves with TL;DRs
  23. ### Scheduled Digests
  24. Set up a daily or weekly cron job and your agent will automatically check for new bookmarks, categorize them, and deliver a digest to you.
  25. ## What it does
  26. - Fetches your X bookmarks via **bird CLI** or **X API v2** (auto-detects)
  27. - Categorizes them by topic
  28. - Proposes specific actions your AI agent can execute
  29. - Supports scheduled digests via cron
  30. - Pattern detection across bookmark history
  31. ## Quick Start
  32. ### Option 1: bird CLI (easiest)
  33. ```bash
  34. npm install -g bird-cli
  35. # Log into x.com in Chrome, then:
  36. bird --chrome-profile "Default" bookmarks --json
  37. ```
  38. ### Option 2: X API v2 (no bird needed)
  39. ```bash
  40. # One-time: create app at https://developer.x.com, then:
  41. python3 scripts/x_api_auth.py --client-id "YOUR_CLIENT_ID"
  42. # Fetch bookmarks
  43. python3 scripts/fetch_bookmarks_api.py -n 20
  44. ```
  45. Both backends output the same JSON format — all workflows work with either.
  46. ## Auto-Detection
  47. You don't need to pick a backend. The skill automatically:
  48. 1. Tries `bird whoami` — if it works, uses bird CLI
  49. 2. If not, checks for X API tokens in `~/.config/x-bookmarks/`
  50. 3. If neither, walks you through setup (offers both options)
  51. ## Files
  52. ```
  53. SKILL.md — Agent instructions (the skill itself)
  54. scripts/
  55. fetch_bookmarks.sh — bird CLI wrapper
  56. fetch_bookmarks_api.py — X API v2 fetcher
  57. x_api_auth.py — OAuth 2.0 PKCE auth helper
  58. references/
  59. auth-setup.md — Detailed setup guide for both backends
  60. ```
  61. ## Requirements
  62. **bird CLI path:** Node.js, npm, bird-cli, browser with X login
  63. **X API path:** Python 3.10+, X Developer account, OAuth 2.0 app
  64. ## Install as OpenClaw Skill
  65. Copy this folder to your OpenClaw skills directory, or:
  66. ```bash
  67. # If published to ClawhHub
  68. openclaw skill install x-bookmarks
  69. ```
  70. ## License
  71. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.