Add 'watch' command for real-time account tracking

[adityasugandhi]

Summary

Add a x-cli watch command that continuously monitors one or more X/Twitter accounts for new posts and displays them in real-time in the terminal.

Use case: Track accounts like @CheddarFlow for live options flow alerts, breaking news accounts, or any account where timely updates matter.

Proposed CLI Interface

# Watch a single account
x-cli watch CheddarFlow

# Watch multiple accounts
x-cli watch CheddarFlow unusual_whales

# Filter by keyword/ticker
x-cli watch CheddarFlow --filter "$NVDA"

# Custom poll interval (default: 60s)
x-cli watch CheddarFlow --interval 30

# Output formats work too
x-cli -j watch CheddarFlow
x-cli -p watch CheddarFlow  # pipe-friendly for downstream processing

# Desktop notifications (optional)
x-cli watch CheddarFlow --notify

# Stop after N tweets
x-cli watch CheddarFlow --max 50

Implementation Plan

1. Add watch command to cli.py

• New top-level Click command watch
• Params: usernames (multiple), --interval (default 60), --filter, --notify, --max
• Resolves usernames to user IDs, then enters polling loop

2. Add polling logic to api.py

• New method get_new_tweets(user_id, since_id) — wraps get_timeline() with since_id param to only fetch tweets newer than the last seen
• Twitter API v2 supports since_id on the timeline endpoint natively

3. Watch loop (watch.py — new module)

• Core loop: poll → diff → display → sleep
• Track last_seen_id per user to avoid duplicates
• Use since_id API param for efficient server-side filtering
• Handle rate limits gracefully (back off on 429, show countdown)
• Clean Ctrl+C handling with summary on exit

4. Optional: Desktop notifications

• Use osascript on macOS for native notifications
• Fallback to terminal bell (\a) on other platforms
• Gated behind --notify flag

5. Optional: Keyword filtering

• Client-side text matching on tweet content
• Support multiple --filter flags
• Case-insensitive matching

6. Output integration

• Reuse existing format_output() formatters
• JSON mode: one JSON object per line (NDJSON) for streaming parsers
• Plain mode: TSV rows as tweets arrive
• Human mode: Rich panels with timestamp

Rate Limit Considerations

• Twitter API v2 timeline endpoint: 900 requests / 15 min window (bearer token)
• Default 60s interval = ~15 requests/15min per account — well within limits
• With 5 accounts at 30s interval = ~150 requests/15min — still safe
• Display rate limit status in verbose mode

Architecture Notes

• Fits cleanly into existing patterns: Click command → API client → formatter
• since_id is the key — avoids fetching/diffing full timelines
• No new dependencies needed (httpx handles polling fine)
• Consider asyncio for multi-account parallel polling in future

Acceptance Criteria

• x-cli watch <username> polls and displays new tweets in real-time
• Multiple usernames supported
• --interval controls poll frequency
• --filter filters tweets by keyword
• All output modes work (-j, -p, -md, default)
• Graceful Ctrl+C with exit summary
• Rate limit handling (backoff on 429)
• Tests for polling logic and filtering

[adityasugandhi]

Implementation Complete

PR #3 implements this feature with the following:

What was built

• x-cli watch <username> — polls accounts and streams new tweets to terminal
• --interval / -i — custom poll interval (default 60s)
• --filter / -f — keyword filtering (repeatable, e.g. -f "$NVDA" -f "$TSLA")
• --notify / -n — macOS desktop notifications
• --max — stop after N tweets
• Multiple accounts — x-cli watch CheddarFlow unusual_whales
• All output formats work (-j, -p, -md, default Rich)

Technical details

• Uses Twitter API v2 since_id for efficient incremental polling
• RateLimitError with automatic backoff on HTTP 429
• 11 new tests, all 40 tests passing

Files changed

• src/x_cli/api.py — RateLimitError, since_id param on get_timeline()
• src/x_cli/watch.py — new module with polling loop
• src/x_cli/cli.py — watch command
• tests/test_watch.py — unit tests
• pyproject.toml — version bump to 0.2.0