Bird

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 | | Read Thread | bird thread | | 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/
• 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zaydiscold
• Source: zaydiscold/bird-skill
• License: MIT
• Homepage: https://zayd.wtf

Install and usage instructions live in the source repository linked above.