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.3.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 5-step sequence with validation at each gate.

Step 1: Resolve Executable

Action: Ensure bird CLI exists Validation: command -v bird returns path OR $HOME/.local/bin/bird exists 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 health check command Validation: $BIRD_CMD check --plain output contains "Ready" Rollback:

• If fails: Re-run install sequence
• If still fails: Report "Bird CLI installation failed. Check network or GitHub availability."

Step 3: Verify Authentication

Action: Confirm Twitter session is valid Validation: $BIRD_CMD whoami --plain returns @username format Rollback:

• Try Chrome profile fallback (Profile 1-3)
• If all fail: Instruct user to re-authenticate in browser first

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 with validated CLI Validation: Exit code 0 AND valid JSON/text output received Rollback: On error, classify per Troubleshooting table and retry once if appropriate

Step 5: Present Results

Action: Format and summarize output for user Validation: User confirms understanding OR requests raw output Rollback: Offer raw JSON/terminal output if formatted 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 for specific situations. Do NOT load by default.

Reference	When to Load
references/search-operators.md	User asks for complex search with filters/operators
references/write-actions.md	BEFORE any tweet/reply/follow/unbookmark operation
references/troubleshooting.md	Auth failures persist after basic retry, or errors unclear

Critical: References contain extended documentation only. All essential workflow information is in this SKILL.md.