bird

name	bird
description	Use when user shares x.com/twitter.com URLs, asks to "read tweet", "search twitter", "check mentions", "timeline", "bird", or any tweet-related actions. Read tweets, search, and browse Twitter/X timelines via bird CLI. Do NOT use for general web browsing or non-Twitter sites.
metadata	{"author":"zaydk","version":"1.2.0","upstream":"https://github.com/zaydiscold/bird","compatibility":"Requires bird CLI 0.8.0+. macOS/Linux with Safari or Chrome cookies."}

Bird — Twitter/X CLI

Read tweets, search, and browse timelines directly via bird CLI using Bash. All commands use deterministic execution with explicit confirmation for write operations.

Quick Reference

Action	Command
Read Tweet	bird read <url>
Read Thread	bird thread <url>
Search	bird search "query" -n 12
Mentions	bird mentions
Feed	bird home
User Timeline	bird user @handle

Examples

Read a tweet

User: "Check this tweet https://x.com/elonmusk/status/123456"

bird read "https://x.com/elonmusk/status/123456"

Search with operators

User: "Search twitter for AI announcements from OpenAI this week"

bird search "from:OpenAI AI announcement since:2025-04-01" -n 15

Read full thread

User: "Show me the whole thread"

bird thread "https://x.com/handle/status/123456"

Check mentions

User: "Do I have any twitter notifications?"

bird mentions -n 10

Post a tweet (requires confirmation)

User: "Tweet 'Hello world'"

I will run: `bird tweet "Hello world"`
Proceed? (yes/no)

Sequential Workflow: Execute Bird Command

CRITICAL: Follow this exact sequence with validation at each gate.

Step 1: Resolve Executable

Action: Ensure bird CLI exists Validation: command -v bird or check $HOME/.local/bin/bird Rollback: Auto-install from GitHub release

if command -v bird >/dev/null 2>&1; then
  BIRD_CMD="bird"
elif [ -x "$HOME/.local/bin/bird" ]; then
  export PATH="$HOME/.local/bin:$PATH"
  BIRD_CMD="$HOME/.local/bin/bird"
else
  curl -fsSL https://github.com/zaydiscold/bird/releases/download/v0.8.0/bird -o /tmp/bird && \
    chmod +x /tmp/bird && \
    mkdir -p "$HOME/.local/bin" && \
    mv /tmp/bird "$HOME/.local/bin/bird" && \
    export PATH="$HOME/.local/bin:$PATH"
  BIRD_CMD="$HOME/.local/bin/bird"
fi

Step 2: Verify CLI Health

Action: Run $BIRD_CMD check --plain Validation: Output contains "Ready" or valid auth check Rollback: If fails, re-run install; if still fails, report "CLI installation failed"

Step 3: Verify Authentication

Action: Confirm Twitter session is valid Validation: $BIRD_CMD whoami --plain returns @username Rollback: Try Chrome profile fallback; if all fail, instruct user to re-auth in browser

if ! $BIRD_CMD whoami --plain 2>/dev/null | grep -q "@"; then
  for profile in "Default" "Profile 1" "Profile 2" "Profile 3"; do
    if $BIRD_CMD --chrome-profile "$profile" check --plain 2>/dev/null | grep -q "Ready"; then
      mkdir -p "$HOME/.config/bird"
      echo "{ chromeProfile: \"$profile\", cookieSource: [\"chrome\"] }" > "$HOME/.config/bird/config.json5"
      break
    fi
  done
fi

Step 4: Execute User Command

Action: Run requested bird operation Validation: Exit code 0, valid JSON/text output Rollback: On error, classify per Troubleshooting and retry if appropriate

Step 5: Present Results

Action: Format output for user Validation: User understands the content Rollback: Offer raw output if summary is unclear

URL Normalization

CRITICAL - Validate URLs before processing:

• Accept ONLY: x.com, twitter.com, mobile.twitter.com
• Normalize to: https://x.com/<path>
• Strip tracking: utm_*, s, ref, t query params
• Reject early: Non-Twitter URLs with clear error message

Troubleshooting

Error	Cause	Solution
unauthorized / 401	Expired/missing cookies	Run bird check, re-auth in browser
rate limit	Too many requests	Wait 60s, retry once, then stop
not found	Deleted tweet or bad URL	Verify URL, inform user if deleted
private/protected	Account requires permission	Explain limitation, suggest following
Safari vs Chrome mismatch	Cookie source changed	Use --chrome-profile flag
exec: bird not found	CLI not installed	Run auto-install from Preflight
error 226	x-client-transaction-id invalid	Update to bird v0.8.0+

Write-Action Confirmation Protocol

For tweet, reply, follow, unbookmark:

1. Restate intent: "I will run: bird tweet \"Your text here\""
2. Ask confirmation: "Proceed? (yes/no)"
3. Execute only on yes
4. Report result: Show tweet URL/ID on success
5. On no: Stop, ask for revised intent

See references/write-actions.md for complete protocol.

Reference Navigation

Load only when needed — these are detailed references, not required for basic operation:

• references/search-operators.md — Search syntax and filters (load if user asks for complex search)
• references/write-actions.md — Tweeting, replying, following (load before any write operation)
• references/troubleshooting.md — Detailed error remediation (load if auth or errors persist)