X (Twitter) Personal Analytics

Monitor your X account — posts, engagement, mentions, followers. Read any tweet. Built for daily briefings and accountability.

Triggers

Use this skill when the user asks about:

• Their X / Twitter posts, timeline, or engagement
• Mentions, replies, or who's talking about them on X
• Follower count, profile stats, follower growth
• "What's happening on my X?" / "How are my posts doing?"
• "Check my Twitter mentions" / "Any new replies?"
• Morning briefing / daily social media summary
• "Am I on X too much?" / accountability check
• Reading a specific tweet or thread (user sends a tweet URL)
• "What did @someone say?" / reading other people's tweets
• Bookmarking or saving tweets for later
• X/Twitter analytics or performance

Prerequisites

Run setup first (imports credentials from ~/.openclaw/.env or prompts interactively):

uv run scripts/x_setup.py

Commands

Briefing — combined morning summary

# Full briefing: your posts + mentions + profile (last 24h, ~$0.02)
uv run scripts/x_briefing.py

# Custom lookback period
uv run scripts/x_briefing.py --hours 48

# Preview cost
uv run scripts/x_briefing.py --dry-run

Timeline — your posts + engagement

# Recent posts with engagement metrics
uv run scripts/x_timeline.py recent

# Last 5 posts
uv run scripts/x_timeline.py recent --max 5

# Posts from last 24 hours
uv run scripts/x_timeline.py recent --hours 24

# Top posts by engagement (from local store, no API call)
uv run scripts/x_timeline.py top --days 7

# Refresh metrics for a specific tweet
uv run scripts/x_timeline.py refresh TWEET_ID

# Accountability check — are they on X right now?
uv run scripts/x_timeline.py activity

Mentions — who's talking to/about you

# Recent mentions
uv run scripts/x_mentions.py recent

# Mentions from last 24 hours
uv run scripts/x_mentions.py recent --hours 24

# Mentions with context (shows what they replied to — costs extra)
uv run scripts/x_mentions.py recent --context

Read — fetch any tweet or thread

# Read a tweet by URL
uv run scripts/x_read.py https://x.com/user/status/123456

# Read by bare ID
uv run scripts/x_read.py 123456

# Fetch full thread
uv run scripts/x_read.py 123456 --thread

# Preview cost
uv run scripts/x_read.py --dry-run https://x.com/user/status/123456

Bookmarks — save and manage

# List your bookmarks
uv run scripts/x_bookmarks.py list

# Bookmark a post
uv run scripts/x_bookmarks.py add TWEET_ID

# Remove a bookmark
uv run scripts/x_bookmarks.py remove TWEET_ID

User Profile — stats + follower tracking

# Your profile stats
uv run scripts/x_user.py me

# Track follower changes over time
uv run scripts/x_user.py me --track

# Look up another user
uv run scripts/x_user.py lookup someuser

Setup & Spend

# Validate credentials
uv run scripts/x_setup.py --check

# Show config (secrets redacted)
uv run scripts/x_setup.py --show

# Weekly spend summary
uv run scripts/x_setup.py --spend-report

# 30-day spend report
uv run scripts/x_setup.py --spend-report --days 30

# Set budget mode
uv run scripts/x_setup.py --budget-mode relaxed

# Print version
uv run scripts/x_setup.py --version

Cost Control Flags (all scripts)

# Preview cost without making the API call
uv run scripts/x_timeline.py --dry-run recent

# Override budget guard
uv run scripts/x_timeline.py --force recent

# Skip all budget checks and warnings
uv run scripts/x_timeline.py --no-budget recent

Workflows

Morning Brief

uv run scripts/x_briefing.py

Accountability Check

uv run scripts/x_timeline.py activity

Weekly Review

uv run scripts/x_timeline.py top --days 7
uv run scripts/x_user.py me --track

Agent Guidelines — READ THIS BEFORE CALLING ANY COMMAND

Every command costs real money. The X API charges per request. Follow these rules to minimize spend:

Rules

• Never call the same command twice in one conversation unless the user explicitly asks for fresh data. The scripts cache locally — if you already ran recent this session, just reference those results.
• Prefer top over recent for repeat questions. top reads from the local store for free ($0). recent hits the API ($0.005).
• Don't use --context on mentions by default. It costs an extra $0.005 per reply thread it fetches. Only add it if the user specifically asks "what were they replying to?"
• Use --max 5 for quick checks. Default is 10-20. If the user just wants a summary, pull fewer.
• Use --hours 24 for briefings. Don't pull the full timeline when they just want "what happened today."
• Never run all scripts unprompted. If the user asks "what's happening on my X?", use x_briefing.py instead of running 3 separate commands.
• For accountability checks, use activity only. It's a single API call. Don't also pull mentions and profile — that triples the cost.
• top and refresh are your friends. top is free (local data). refresh TWEET_ID updates just one tweet ($0.005) — use it when they ask "how's my last post doing?" instead of re-pulling the whole timeline.
• Watch the daily spend total. Every command output shows "Today's spend: $X.XXX". If it's approaching the budget limit, tell the user before making more calls.
• Never loop or retry on your own. If a command fails (402, rate limit, etc.), report the error. Don't retry automatically.
• x_read.py caches tweets — if the user asks about the same tweet again, it's already in the local store. No need to re-fetch.
• Use x_briefing.py for morning briefings instead of running timeline + mentions + user separately. It's cheaper ($0.02 vs $0.02 for 3 separate commands) and cleaner output.

Cost Reference

Budget Modes

The user can set a budget enforcement mode via x_setup.py --budget-mode:

• guarded (default): Warn at 50/80/100%, block at limit
• relaxed: Warn at 50/80/100%, never block
• unlimited: No warnings, no blocks

Budget Tiers

The user set a daily budget during setup. The scripts will warn and block when the limit is hit:

• lite: $0.03/day (~1 briefing)
• standard: $0.10/day (~3-5 checks)
• intense: $0.25/day (~10+ checks)

What NOT to do

• Don't run commands "just to have fresh data" — only fetch when the user needs it
• Don't use --no-cache unless debugging
• Don't call user lookup on multiple accounts in a loop
• Don't refresh every tweet's metrics — only refresh specific ones the user asks about
• Don't combine recent + mentions + user in one response — use x_briefing.py instead