twitter

name	twitter
description	Interact with Twitter/X -- fetch bookmarks, categorize content, draft tweets, post, and search.
version	1.0.0
variables	["action","topic"]
allowed-tools	["Bash","Read","Write","Glob"]
user-invocable	true
argument-hint	<action> [options] (e.g., bookmarks, draft "topic", categorize)

Twitter/X Operations

You interact with the Twitter/X API v2 through clawft's OAuth2 plugin. All authenticated requests use weft tool rest_request --provider twitter which auto-injects the Bearer token from ~/.clawft/tokens/twitter.json.

Prerequisites

The user must have authorized Twitter via /social-auth twitter authorize before using any action. If a request returns 401, call weft tool oauth2_refresh --provider twitter and retry once.

Available Actions

bookmarks -- Fetch Bookmarks

Fetch the authenticated user's bookmarks with pagination.

# First page
weft tool rest_request --provider twitter --method GET \
  --url "https://api.x.com/2/users/me/bookmarks?tweet.fields=created_at,author_id,text,public_metrics&max_results=100"

For pagination, use the next_token from the response:

weft tool rest_request --provider twitter --method GET \
  --url "https://api.x.com/2/users/me/bookmarks?tweet.fields=created_at,author_id,text,public_metrics&max_results=100&pagination_token=<next_token>"

Store results to the workspace:

~/.clawft/workspace/social/twitter/bookmarks/YYYY-MM-DD.json

Create parent directories as needed. Each file contains the full API response for that fetch. Append paginated results into the same date file by merging the data arrays.

Rate limits: Twitter allows 180 requests per 15 minutes for bookmark reads. If you receive HTTP 429, extract the x-rate-limit-reset header and inform the user when they can retry.

categorize -- Categorize Bookmarks

Read stored bookmarks and classify each into categories.

Categories: tech, news, personal, reference, career, entertainment, other

1. Read the bookmarks file:

   ~/.clawft/workspace/social/twitter/bookmarks/YYYY-MM-DD.json
   

   If no date is specified, use the most recent file (find via Glob).

2. For each bookmark, classify it by analyzing the tweet text. Assign:

   • category: One of the categories above.
   • confidence: High, medium, or low.
   • tags: 1-3 descriptive tags.
   • text_preview: First 100 characters of the tweet.

3. Process in batches of 20 tweets. After each batch, append results to:

   ~/.clawft/workspace/social/twitter/bookmarks/categorized/YYYY-MM-DD.json
   

4. Output format per entry:

   {
     "id": "tweet_id",
     "text_preview": "First 100 chars...",
     "category": "tech",
     "confidence": "high",
     "tags": ["rust", "programming", "performance"],
     "author_id": "author_id",
     "created_at": "ISO timestamp"
   }
   

5. After processing, print a summary: count per category, total processed.

draft -- Compose a Tweet

Draft a tweet or thread on a given topic.

• Single tweet: Max 280 characters. Be concise and engaging.
• Thread: If the content exceeds 280 chars, structure as a numbered thread (1/N format). Each tweet in the thread must be under 280 chars.
• Suggest 2-3 relevant hashtags based on the topic.
• Save the draft to:

  ~/.clawft/workspace/social/twitter/drafts/<slug>.json
  

  where <slug> is a URL-safe version of the topic (lowercase, hyphens).

Draft format:

{
  "topic": "original topic",
  "tweets": [
    { "text": "Tweet content here #hashtag", "index": 1 }
  ],
  "hashtags": ["#hashtag1", "#hashtag2"],
  "created_at": "ISO timestamp",
  "status": "draft"
}

Present the draft to the user for review before saving. Ask if they want edits.

post -- Publish a Tweet

Post a draft or compose and send immediately.

1. If a draft slug is provided, read from drafts directory.
2. Show the user exactly what will be posted.
3. Always ask for explicit confirmation before posting.
4. Post via the API:

weft tool rest_request --provider twitter --method POST \
  --url "https://api.x.com/2/tweets" \
  --body '{"text": "Tweet content here"}'

For threads, post sequentially, using reply.in_reply_to_tweet_id for each subsequent tweet:

weft tool rest_request --provider twitter --method POST \
  --url "https://api.x.com/2/tweets" \
  --body '{"text": "Next tweet", "reply": {"in_reply_to_tweet_id": "<previous_id>"}}'

5. After posting, update the draft status to "posted" with the tweet ID(s).

search -- Search Tweets

Search recent tweets matching a query.

weft tool rest_request --provider twitter --method GET \
  --url "https://api.x.com/2/tweets/search/recent?query=<encoded_query>&tweet.fields=created_at,author_id,text,public_metrics&max_results=10"

Present results in a readable format: author, text preview, metrics (likes, retweets, replies).

Token Expiry Handling

If any API call returns HTTP 401:

1. Call weft tool oauth2_refresh --provider twitter.
2. Retry the original request once.
3. If it fails again, inform the user their token may be revoked and suggest re-authorizing with /social-auth twitter authorize.

Error Handling

• 401 Unauthorized: Refresh token and retry (see above).
• 403 Forbidden: The app lacks the required scope. Report which scope is needed (e.g., bookmark.read for bookmarks).
• 429 Rate Limited: Report the reset time from x-rate-limit-reset header. Do not retry automatically.
• 5xx Server Error: Twitter is experiencing issues. Suggest retrying later.

Safety Rules

• NEVER post without explicit user confirmation.
• NEVER store raw API tokens in workspace files -- only store content data.
• Sanitize all user input before including in API request bodies.
• Do not include sensitive personal information in tweets unless the user explicitly provides it.