x-bookmarks

X Bookmarks v2

X/Twitter のブックマークを、せっかくのアイデアが埋もれる場所から、実行可能な作業に変えます。

基本理念： 要約するだけでなく、エージェントが実行できるアクションを提案します。

データソースの選択

このスキルは2つのバックエンドに対応しています。動作する方を選んでください。

1. bird CLI（利用可能な場合は優先）

• 高速で、API キーは不要です。ブラウザーの Cookie を使用します
• インストール：npm install -g bird-cli
• テスト：bird whoami — ユーザー名が表示されれば使用できます

2. X API v2（フォールバック）

• bird CLI がなくても動作します
• X Developer アカウントと OAuth 2.0 アプリが必要です
• セットアップ：references/auth-setup.md →「X API Setup」を参照してください

自動検出のロジック

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)

ブックマークの取得

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

ユーザーが .env.bird ファイル、または AUTH_TOKEN／CT0 の環境変数を設定している場合は、最初に読み込んでください：source .env.bird

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

# All bookmarks
python3 scripts/fetch_bookmarks_api.py --all

# Since a specific tweet
python3 scripts/fetch_bookmarks_api.py --since-id "1234567890"

# Pretty print
python3 scripts/fetch_bookmarks_api.py -n 50 --pretty

API スクリプトは bird CLI と同じ JSON 形式で出力するため、後続のワークフローはすべて同じように動作します。

トークン管理は自動です： トークンは ~/.config/x-bookmarks/tokens.json に保存され、保存済みの refresh_token を使って更新されます。更新に失敗した場合は、エージェントが x_api_auth.py を再実行するようユーザーを案内してください。

環境変数による上書き

ユーザーがすでに Bearer トークンを持っている場合（別のツールから取得したものなど）、OAuth の手順を省略できます：

X_API_BEARER_TOKEN="your_token" python3 scripts/fetch_bookmarks_api.py -n 20

JSON 出力形式（両方のバックエンド共通）

各ブックマークは次の形式で返されます：

{
  "id": "tweet_id",
  "text": "tweet content",
  "createdAt": "2026-02-11T01:00:06.000Z",
  "replyCount": 46,
  "retweetCount": 60,
  "likeCount": 801,
  "bookmarkCount": 12,
  "viewCount": 50000,
  "author": { "username": "handle", "name": "Display Name" },
  "media": [{ "type": "photo|video", "url": "..." }],
  "quotedTweet": { "id": "..." }
}

主なワークフロー

1. アクション優先のダイジェスト（主なユースケース）

重要な差別化要素は、要約するだけでなく、エージェントが実行できるアクションを提案することです。

1. ブックマークを取得します（bird または API、自動検出）
2. トピックごとに解析して分類します（暗号資産、AI、マーケティング、ツール、個人関連などを自動検出）
3. 各カテゴリについて、具体的なアクションを提案します：
   • ツール／リポジトリのブックマーク →「これをテストしたり、セットアップしたり、コードを分析したりできます」
   • 戦略／アドバイスのブックマーク →「実行可能な手順を抽出しました。どれか実行しましょうか？」
   • ニュース／トレンド →「これはユーザーの仕事と関連しています。コンテンツに活用できる切り口はこちらです」
   • コンテンツのアイデア →「ユーザーらしい文体で、ツイートや動画にするとよさそうです。下書きはこちらです」
   • 質問／ディスカッション →「さらに調査して、要約をお伝えできます」
4. 古いブックマーク（2週間超）にフラグを付けます —「活用するか、忘れるか」
5. アクションを添えたカテゴリ別ダイジェストを作成します

出力形式：

📂 CATEGORY (count)
• Bookmark summary (@author)
→ 🤖 I CAN: [specific action the agent can take]

2. スケジュール済みダイジェスト（Cron）

定期的にブックマークを確認するよう設定します。次の cron 設定をユーザーに提案してください：

Schedule: daily or weekly
Payload: "Check my X bookmarks for new saves since last check.
  Fetch bookmarks, compare against last digest, summarize only NEW ones.
  Categorize and propose actions. Deliver to me."

処理した最新のブックマーク ID を保存して状態を管理します。ワークスペースに保存してください： memory/bookmark-state.json → { "lastSeenId": "...", "lastDigestAt": "..." }

3. コンテンツの再活用

ユーザーがブックマークからコンテンツのアイデアを求めた場合：

1. 最近のブックマークを取得します
2. フレームワーク、ヒント、インサイトを含む、エンゲージメントの高いツイート（500 いいね超）を特定します
3. 重要なアイデアをユーザーらしい文体に書き換えます（文体データがある場合）
4. ブックマークの元のエンゲージメントに基づいて投稿時間を提案します

4. パターンの検出

ユーザーに十分なブックマーク履歴がある場合：

1. すべてのブックマークを取得します（--all）
2. トピック／キーワードごとにクラスタリングします
3. 「[トピック]について、N件のツイートをブックマークしています。さらに詳しく調べましょうか？」と報告します
4. パターンに基づいて、調査レポート、コンテンツシリーズ、またはツールを提案します

5. ブックマークの整理

古いブックマークについて：

1. しきい値（デフォルト：30日）より前のブックマークを特定します
2. それぞれについて、TL;DR と実行可能な要点を1つ抽出します
3. 「今日活用するか、削除してください」と提示します
4. ユーザーは次のコマンドでブックマークを解除できます：bird unbookmark <tweet-id>（bird のみ）

エラー処理

エラー	原因	対処方法
bird: command not found	bird CLI がインストールされていません	代わりに X API を使用するか、npm i -g bird-cli を実行します
"No Twitter cookies found"	ブラウザーで X にログインしていません	Chrome／Firefox で x.com にログインするか、X API を使用します
Safari の Cookie で EPERM が発生する	macOS の権限	代わりに Chrome／Firefox または X API を使用します
結果が空	Cookie／トークンの有効期限が切れています	再ログインするか、x_api_auth.py を再実行します
レート制限（429）	API リクエストが多すぎます	待ってから再試行し、--count で件数を制限します
"No X API token found"	認証のセットアップを実行していません	x_api_auth.py --client-id YOUR_ID を実行します
トークンの更新に失敗	リフレッシュトークンの有効期限が切れています	x_api_auth.py を再実行して、再認証します

ヒント

• 手早く要約するには -n 20 から始め、詳細に分析するには --all を使用します
• bird：返信のスレッドコンテキストを取得するには --include-parent を使用します
• API：bookmarkCount と viewCount を含みます（bird では含まれない場合があります）
• bird の --folder-id <id> でブックマークフォルダーを利用できます
• どちらのバックエンドも同一の JSON を出力するため、ワークフローはバックエンドに依存しません