Quick Start Guide
Get TweetPilot up and running in under 5 minutes. Follow these steps in order.
1
Download & Install
Visit the homepage and download the installer for your platform. macOS: open
TweetPilot.dmg, drag TweetPilot to your Applications folder, then launch it (macOS 12 Monterey or later). Windows: run TweetPilot.msi and follow the setup wizard (Windows 10 or later, x64).2
Install TweetClaw Extension
a
Open the Chrome Web Store listing and click Add to Chrome. Confirm the permissions popup — TweetClaw only needs access to x.com.
b
Pin TweetClaw to your toolbar so you can always check its status at a glance.
Can't see the puzzle piece icon? Some browsers hide it when no extensions are installed. Click the three-dot menu (⋮) in the top-right corner of Chrome → Extensions → Manage Extensions. Find TweetClaw in the list and toggle it on, then return to the toolbar — the puzzle piece icon should now appear.
c
Navigate to x.com in the same Chrome window and make sure you're logged in. TweetClaw will activate automatically and start a local WebSocket bridge in the background.
d
Click the TweetClaw icon in your toolbar. The popup shows your connected Twitter username and the active port number (default:
20086). Confirm both are displayed correctly.e
In TweetPilot, open Settings → LocalBridge and verify the port matches what TweetClaw shows. Both must use the same port — if you change one, update the other. A mismatch will prevent the connection from establishing.
3
Configure an AI Model
a
In TweetPilot, click Settings in the top menu bar, then select AI Providers.
b
Choose a provider from the list. If you're unsure which to pick: DeepSeek is the most affordable for getting started; Claude Sonnet or GPT-4o give the best results for complex automation tasks.
c
d
Select a model from the dropdown, then click Test Connection. A green checkmark confirms the key is valid and the model is reachable. You're ready to go.
4
Add Your Twitter Account
a
Click Accounts in the left sidebar, then click Add Account.
b
Choose a connection method. TweetClaw (Browser) is recommended for most users — it reads your existing logged-in session from Chrome, so no passwords or tokens are required. X API (Direct) uses your own developer credentials and works without the browser extension, but requires setting up an app on the Twitter Developer Portal first.
c
If you chose TweetClaw: make sure Chrome is open with x.com and TweetClaw is active. TweetPilot will detect your session automatically and display your Twitter username. Click Confirm to complete.
d
Once added, your account appears in the Accounts list with a green status indicator. You can add multiple accounts and switch between them at any time from the account dropdown at the top of the sidebar.
5
Run Your First Script
a
Click New Workspace in the sidebar to create your first workspace. A workspace is where you manage scripts, data blocks, and AI conversations for a specific goal.
b
Open the AI Chat panel. This is your main interface for giving instructions — you talk to the agent in plain language, and it handles the code and Twitter API calls for you.
c
Try this example to verify everything is working:
"Search for the 5 most recent tweets mentioning 'AI automation' and show me the usernames and like counts."
The agent will write and run the script automatically, then display the results in the chat.
"Search for the 5 most recent tweets mentioning 'AI automation' and show me the usernames and like counts."
The agent will write and run the script automatically, then display the results in the chat.
d
If you see results returned — you're all set. From here you can ask follow-up questions, save the script for reuse, or bind it to a scheduled task to run automatically.
All your data — credentials, scripts, workspaces — stays 100% local on your Mac. Nothing is uploaded to our servers except license validation.
AI Agent
TweetPilot ships three purpose-built AI agents, each optimized for a different role. All agents run locally on your Mac using your own AI provider — nothing is routed through TweetPilot servers.
Built on Claurst
Claurst
An open-source agentic coding engine, originally a clean-room reimplementation of Claude Code's core behavior. TweetPilot embeds Claurst as its agent runtime and injects Twitter-specific tooling on top.
Multi-provider LLM routing
Structured tool system
Granular permission model
MCP server integration
Cross-session memory
Full conversation logging
All four agents below share this runtime. TweetPilot extends each agent's environment with a different set of tools and constraints — Twitter access via ClawBot or xdk, data block build rules, Feishu messaging, etc.
Four Specialized Agents
①
TweetPilot Agent
Interactive Chat · Main Workspace
ClawBot
xdk
Multi-account
Workspace docs
The interactive chat agent in the main workspace. Extends Claurst with two Twitter access layers: ClawBot (via LocalBridge → TweetClaw, free, no API keys) and xdk (X OAuth, official API). Automatically selects the right path based on account type. Reads
product.md for product context and content_rules.md for tone and content constraints — every response stays on-brand.
Use case
Explore data, draft tweets, write and debug Python scripts, manage accounts — all through natural-language conversation.
②
Task AI Agent
Autonomous Operation · 7×24 Scheduled
No user interaction
Prompt-driven
content_rules.md
Session log
The autonomous account operation agent. Runs entirely from a prompt you define — no interaction during execution. Pair it with
content_rules.md to enforce brand tone, religious constraints, or keyword blocklists across every run. Supports two permission modes: Workspace Full Access (recommended) limits file ops to the workspace; Full Access removes all restrictions. Full session logs are saved for every run.
Use case
Auto-reply to mentions in a warm or technical tone, engage trending topics, post daily summaries — running 24/7 via scheduled tasks.
③
Data Block Agent
Data Visualization · Custom Blocks
custom_blocks.db
window.tweetpilot.query()
Inlined charts
A specialized variant of the TweetPilot Agent, activated inside the Data Block builder. Inherits all Twitter access capabilities and adds data block rules: create tables in
custom_blocks.db (mandatory purpose comment in every CREATE TABLE), generate data write scripts, produce self-contained display HTML in the cards/ folder. All chart libraries are inlined — no external CDN.
Use case
Describe what you want to visualize — the agent creates the DB table, writes the data script, and generates the display HTML end-to-end.
④
Feishu AI Assistant
Remote Control · Feishu Private Message
ClawBot
xdk
Mobile access
Workspace boundary
The Feishu AI Assistant lets you interact with TweetPilot remotely through Feishu private messages — from your phone or any device. It carries the same Twitter access capabilities as the TweetPilot Agent (ClawBot + xdk) but operates under strict workspace boundaries: file access is limited to the workspace directory, it will not initiate network calls on its own, and it only executes operations you explicitly authorize. When you send a file or image, it waits for your next instruction before acting.
Use case
Step away from your Mac — send commands via Feishu on your phone: "check follower growth today", "draft a reply to the top mention", "run the weekly report script".
Supported Provider Types
All four agents use the same active AI provider. Configure multiple providers and switch the active one at any time — the switch takes effect immediately across all agents.
| Type | Built-in Examples | API Key | Base URL |
|---|---|---|---|
| Anthropic | claude-sonnet-4-5, claude-opus-4-5… | Required | https://api.anthropic.com |
| OpenAI | gpt-4o, gpt-4-turbo… | Required | https://api.openai.com |
| OpenAI Compatible | DeepSeek, Groq, and others | Required | Provider's endpoint |
| Ollama | llama3, qwen2.5, mistral… | Not needed | http://localhost:11434 |
| Custom | Any OpenAI-compatible endpoint | Optional | Your custom URL |
Setup Steps
1
Open AI Provider Settings
In TweetPilot, click the Settings icon in the top bar, then select AI Providers.
2
Add a Provider
Click Add Provider. In the form, select the Type (Anthropic / OpenAI / OpenAI Compatible / Ollama / Custom), fill in the Model name (free text — type it exactly, e.g.
claude-sonnet-4-5), and optionally set a Base URL. Built-in provider types are locked and cannot be changed after creation.3
Enter Your API Key
Paste your API key. Ollama does not require one. For all other types, the key is required. Keys are stored encrypted on your Mac — they are never sent to TweetPilot servers.
4
Set as Active
You can add multiple providers. Click the ★ Set Active button on the provider you want to use. All AI tasks and chat sessions will use the active provider until you switch it.
Using Ollama (Local Models)
Ollama runs models entirely on your Mac — no internet required, no API cost, completely private. Install from ollama.ai, pull a model with
ollama pull llama3 (or any other model), then add Ollama as a provider in TweetPilot. The default base URL is http://localhost:11434 and no API key is needed.OpenAI-Compatible Providers (DeepSeek, Groq, etc.)
DeepSeek and Groq are built-in as OpenAI Compatible type. For any other provider that exposes an OpenAI-compatible API, use the Custom type — set the Base URL to their endpoint and enter your API key. The model field is always free text, so enter the exact model identifier the provider requires.
Note: DeepSeek offers two API interface modes — OpenAI-compatible and Anthropic-compatible. The base URL and model identifiers differ between the two modes. Visit the DeepSeek API Docs to find the correct endpoint URL and model names for each mode.
LocalBridge & TweetClaw
TweetPilot provides two independent ways to reach Twitter/X — LocalBridge (browser session via TweetClaw) and X API (official OAuth). LocalBridge is a local HTTP + WebSocket server compiled into TweetPilot, exposing a REST API at 127.0.0.1:20088. TweetClaw is the Chrome extension that connects your live browser session to LocalBridge, giving scripts and AI agents free, rate-limit-free access to Twitter's full web API.
Two Routes to Twitter/X
① LocalBridge Route — this page
Your script → LocalBridge REST API (
Pros: zero cost, no rate limits, no OAuth setup, full GraphQL responses including likes, retweets, screen_name.
Requires: Chrome open and logged in to x.com.
:20088) → WebSocket (:20086) → TweetClaw extension → Twitter's internal web API via live browser session.Pros: zero cost, no rate limits, no OAuth setup, full GraphQL responses including likes, retweets, screen_name.
Requires: Chrome open and logged in to x.com.
② X API Route — see X API page
Your script → LocalBridge OAuth token proxy (
Pros: no browser required, supports Direct Messages (DMs), official API compliance.
Requires: Twitter developer plan ($100/month+), strict rate limits apply.
POST /api/v1/x/oauth/access-token) → Twitter's official API v2 using stored OAuth 2.0 access token.Pros: no browser required, supports Direct Messages (DMs), official API compliance.
Requires: Twitter developer plan ($100/month+), strict rate limits apply.
How It Works
TweetClaw's architecture has three layers working together. LocalBridge (compiled into TweetPilot as a static library) runs a local WebSocket server and REST API. TweetClaw connects to that WebSocket from inside Chrome and injects a content script into the x.com page. When TweetPilot issues a task — search, post, like, follow — it goes through the REST API → WebSocket → TweetClaw content script → Twitter's own web API, using the full authenticated page session.
TweetPilot
Issues tasks via AI agent or script
macOS App
→
REST API
:20088
:20088
LocalBridge
WebSocket server + REST gateway, compiled into TweetPilot
Go static lib
→
WebSocket
:20086
:20086
TweetClaw
Receives tasks, executes via injected content script
Chrome Extension
→
Web session
x.com
x.com
Twitter/X
Real web API calls using live browser session
Web API
Why TweetClaw — Two Core Advantages
Zero API Cost
The X API charges for both read and write operations — even basic search and timeline access require a paid developer plan ($100/month+). TweetClaw operates through your browser session, so every operation is completely free, with no usage caps or billing surprises.
Dramatically Lower Token Usage
Tools like OpenAI's browser operator work by taking screenshots and asking the AI to interpret the page visually — consuming enormous tokens per action and often misreading content. TweetClaw returns structured JSON data directly from Twitter's internal API, so the AI receives clean, precise data with near-zero token overhead.
| Feature | TweetClaw | X API (Direct) | AI Browser Operator |
|---|---|---|---|
| Cost | Free | $100+/month | Free |
| AI Token Usage | Low (structured JSON) | Low (structured JSON) | Very High (screenshot parsing) |
| Data Accuracy | Exact | Exact | Unreliable (OCR errors) |
| Rate Limits | None | Strict | None |
| Setup Required | Extension install only | Developer Portal + OAuth | Complex configuration |
Setup (if you haven't already)
Full installation walkthrough is covered in Quick Start → Step 2. In brief:
1
Install from Chrome Web Store
Install TweetClaw, open x.com while logged in, then pin it to your toolbar.
2
Align the Port
Click the TweetClaw icon — confirm the port shown (default
20086). In TweetPilot, open Settings → LocalBridge and ensure the Browser Extension port matches. Both must be identical.3
Add Account
In TweetPilot go to Accounts → Add Account → TweetClaw (Browser Mode). Your logged-in Twitter username will be detected automatically.
Troubleshooting
Port conflict: If port 20086 is in use by another process, change it in TweetPilot Settings → LocalBridge → Browser Extension port. Then open the TweetClaw popup and update the port there too. Both must match, then refresh the x.com tab.
Status shows disconnected: Refresh the x.com tab in Chrome — TweetClaw re-establishes the WebSocket connection on page load. If it still fails, check that TweetClaw is enabled in Chrome's extension manager and that you're logged into Twitter.
Multiple Twitter accounts: TweetClaw connects the account currently active in Chrome. To switch, log into the desired account in your browser, then refresh x.com — TweetPilot will detect the new session automatically.
LocalBridge REST API Reference
All endpoints are served at http://127.0.0.1:20088 — accessible only from the local machine. Scripts use requests (Python) or any HTTP client. No authentication header is needed.
| Endpoint | Description |
|---|---|
GET /api/v1/x/search?query=&count= |
Search tweets by keyword or hashtag. Returns full GraphQL response including favorite_count, retweet_count, full_text, screen_name. Parse path: data.data.search_by_raw_query.search_timeline.timeline.instructions[].entries[] |
POST /api/v1/x/retweetsbody: {"tweetId": "…"} |
Retweet a tweet by its ID. Uses the browser session's active account. No OAuth token required. |
POST /api/v1/x/likesbody: {"tweetId": "…"} |
Like a tweet by its ID. |
POST /api/v1/x/tweetsbody: {"text": "…"} |
Post a new tweet. Optionally include "reply": {"in_reply_to_tweet_id": "…"} to reply. |
GET /api/v1/x/tweets?tweetId= |
Fetch a single tweet's full data. Returns likes, retweets, reply count, full text, author info. |
POST /api/v1/x/followsbody: {"userId": "…"} |
Follow a user by their numeric user ID. |
POST /api/v1/x/bookmarksbody: {"tweetId": "…"} |
Bookmark a tweet. |
POST /api/v1/x/oauth/access-tokenbody: {"twitter_id": "…"} |
Retrieve the stored OAuth 2.0 access token for an authorized account (X API route). Required by xdk SDK scripts. |
POST /api/v1/feishu/sendbody: {"text": "…"} |
Send a text message to your configured Feishu private conversation. Returns {"ok": true} on success. |
Calling LocalBridge from a Python Script
There are two ways to call LocalBridge from Python: using the ClawBot SDK (higher-level wrapper) or raw HTTP REST (requests library, no extra install). Both are shown below.
ClawBot SDK — search & retweet (S08 pattern)
from clawbot import ClawBotClient
import time
client = ClawBotClient()
instances = client.x.status.get_instances()
instance_id = instances[0].get("instanceId") if instances else None
# Search #AI, sort by likes, retweet top result
raw = client.x.tweets.transport.search_raw(query="#AI", count=20, instance_id=instance_id)
instructions = (raw.get("data",{}).get("data",{})
.get("search_by_raw_query",{}).get("search_timeline",{})
.get("timeline",{}).get("instructions",[]))
tweets = []
for instr in instructions:
for entry in instr.get("entries", []):
r = entry.get("content",{}).get("itemContent",{}).get("tweet_results",{}).get("result",{})
if not r: continue
t = r.get("tweet") or r
rid = t.get("rest_id") or r.get("rest_id")
likes = t.get("legacy",{}).get("favorite_count", 0)
if rid: tweets.append({"id": rid, "likes": likes})
top = sorted(tweets, key=lambda x: x["likes"], reverse=True)[:1]
for t in top:
client.x.actions.retweet(tweet_id=t["id"], instance_id=instance_id)
print(f"Retweeted {t['id']} ({t['likes']} likes)")
time.sleep(3)
HTTP REST — search & retweet (pure requests, no SDK needed)
import requests, time
BASE = "http://127.0.0.1:20088"
# Search
resp = requests.get(f"{BASE}/api/v1/x/search", params={"query": "#AI", "count": 20})
instructions = (resp.json().get("data",{}).get("data",{})
.get("search_by_raw_query",{}).get("search_timeline",{})
.get("timeline",{}).get("instructions",[]))
tweets = []
for instr in instructions:
for entry in instr.get("entries", []):
r = entry.get("content",{}).get("itemContent",{}).get("tweet_results",{}).get("result",{})
if not r: continue
t = r.get("tweet") or r
rid = t.get("rest_id") or r.get("rest_id")
likes = t.get("legacy",{}).get("favorite_count", 0)
if rid: tweets.append({"id": rid, "likes": likes})
# Retweet top result
top = sorted(tweets, key=lambda x: x["likes"], reverse=True)[:1]
for t in top:
requests.post(f"{BASE}/api/v1/x/retweets", json={"tweetId": t["id"]})
print(f"Retweeted {t['id']} ({t['likes']} likes)")
time.sleep(3)
GraphQL response tip: Search results wrap some tweets in a
TweetWithVisibilityResults object. Always use result.get("tweet") or result before accessing legacy or rest_id — this handles both formats transparently.Managing Accounts
TweetPilot supports two fundamentally different account types. Each has its own connection method, API capabilities, and data access model. Understanding the difference helps you choose the right type for each workflow.
Two Account Types
TweetClaw Account
Connected via the TweetClaw browser extension. Operates through your live browser session — requires Chrome to be open and logged in to x.com. Gives the AI access to Twitter's internal web APIs (timeline, search, post, like, follow, bookmark, and more) through LocalBridge.
X OAuth Account
Connected via Twitter's official OAuth 2.0 flow. TweetPilot securely stores the access token — no browser required once authorized. The AI can call Twitter's official API v2 using this token, with access to posts, users, DMs, media, lists, and more.
Capability Comparison
| Capability | TweetClaw | X OAuth |
|---|---|---|
| Browser required | Yes (Chrome + x.com) | No |
| Home timeline | ✓ | ✓ |
| Tweet search | ✓ | ✓ |
| Post / Delete tweet | ✓ | ✓ |
| Like / Retweet / Follow / Bookmark | ✓ | ✓ |
| Direct Messages | No | ✓ |
| Media upload | ✓ | ✓ |
| Rate limits | None | Twitter API tier limits apply |
| Cost | Free | Paid developer plan required |
| Ask AI about capabilities | Ask AI — it knows all available APIs | Ask AI — it knows all available APIs |
Not sure what's possible with your account type? Just ask the AI in plain language — for example: "What can I do with a TweetClaw account?" or "Can I send DMs using my OAuth account?". The AI has full knowledge of both account types' API capabilities.
Managed vs. Unmanaged
After connecting an account, you can choose whether to manage it. This controls whether TweetPilot actively collects data for that account.
Managed
Data Blocks will periodically collect this account's profile data — followers, following count, tweet count, and more. Snapshots accumulate locally over time, letting you track trends and changes. You can also set a personality prompt for the AI to adopt when writing on behalf of this account.
Unmanaged
Only the account's online/offline status is synced. No profile data is collected, no snapshots are stored. Use this for accounts you want connected but don't need to monitor — it keeps things lightweight.
You can toggle an account between managed and unmanaged at any time from the account detail page. All collected data stays on your Mac — nothing is uploaded to TweetPilot servers. Historical snapshots are retained even if you temporarily unmanage an account.
Account Status Indicators
| Status | Account Type | Meaning |
|---|---|---|
| online | TweetClaw | Browser is open, TweetClaw is connected, and x.com is active. Ready to execute tasks. |
| instance | TweetClaw | Connected as a background instance. May have limited capabilities depending on page state. |
| online | X OAuth | Token is valid and the account is accessible. Ready for API calls without needing a browser. |
| offline | X OAuth | Token may have expired or been revoked. API calls will fail until re-authorized. |
| reauth required | X OAuth | Token has expired. Go to the account detail page and click Re-authorize to log in again. |
You can add multiple accounts of either type and run different workspaces under different accounts simultaneously. Managed accounts will accumulate historical trend data locally over time — the longer you run TweetPilot, the richer your local dataset becomes.
Task Scheduler
TweetPilot's task scheduler combines two dimensions — task type (Python or AI) × execution mode (instant or scheduled) — giving you four ways to automate Twitter workflows, from one-click scripts to fully unattended AI-driven operations running around the clock.
Two Dimensions, Four Combinations
Python Task
Executes a fixed Python script. The logic is fully in your hands — read data, call APIs, post tweets, send notifications. Predictable, repeatable, zero ambiguity.
AI Task
You write a prompt describing what to do; the AI figures out how. It can browse timelines, draft replies, fetch data, and take action — all driven by natural language. Full session logs are saved for every run.
Instant Execution
Run on demand with one click. Perfect for non-programmers who want to execute a Python script or fire an AI task without touching the command line. Available on all plans.
Scheduled Execution
Runs automatically at a fixed interval or cron time — no one needs to be at the keyboard. The cornerstone of unattended automation. Requires Pro or higher.
What You Can Build — Real Examples
| Combination | Example Use Case |
|---|---|
| Instant + Python | Run a one-off data export, bulk-like a list of tweets, or trigger a notification — without opening a terminal. |
| Instant + AI | Paste a tweet URL and ask the AI to "write three professional reply options in English." Get results in seconds, no code needed. |
| Scheduled + Python | Every hour, fetch your latest mentions, filter for support questions, and post a structured summary to Feishu — fully unattended. |
| Scheduled + AI | Every 30 minutes, let the AI scan new replies under your product tweet and respond as a warm, friendly customer support agent. Or have the AI answer technical questions in a precise, engineering-team tone on a fixed schedule. |
Creating a Task
1
Open the Task Workbench
In TweetPilot, click Tasks in the left sidebar, then click New Task. The Task Workbench opens — a single form for configuring all task dimensions.
2
Choose Task Type
Select Python Script to run a
.py file, or AI Task to describe the job in natural language. For Python, pick the script file. For AI, type your prompt — be specific about tone, target, and action.3
Choose Execution Mode
Select Manual for on-demand execution, or Scheduled to run automatically. If scheduled, pick Simple Interval (every N minutes / hours / days) or Fixed Time (Cron) for precise scheduling like "every weekday at 9 AM".
4
Set Permission Mode (AI Tasks Only)
Relaxed (recommended) — allows most operations while blocking a small set of highly destructive commands (e.g.
rm -rf /, sudo). Full Access — no restrictions at all; use only if you fully trust the prompt.5
Save and Run
Click Save. For manual tasks, click Execute Now. For scheduled tasks, the scheduler activates immediately and shows the next execution time. You can also click Test Run on a scheduled task to trigger it immediately without waiting.
Schedule Types
Simple Interval
Runs every N minutes, hours, or days starting from the moment you save the task. Easiest to set up — no syntax required.
Fixed Time (Cron)
Runs at a precise time of day, week, or month. Uses a 6-field cron expression:
second minute hour day month weekday. The UI has a visual helper that translates your settings into a human-readable summary (e.g. "9:00 每周一").Cron Expression Reference
Format: second minute hour day month weekday
0 0 9 * * * # Every day at 09:00
0 0 */2 * * * # Every 2 hours
0 30 8 * * 1-5 # Weekdays at 08:30
0 0 9,21 * * * # 09:00 and 21:00 daily
0 */30 * * * * # Every 30 minutes
0 0 9 1 * * # 1st of every month at 09:00
Weekday: 0 = Sunday, 1 = Monday … 6 = Saturday. The UI handles UTC↔local time conversion automatically — always enter times in your local timezone.
Managing Tasks
| Action | Description |
|---|---|
| Test Run | Triggers a scheduled task immediately without changing its schedule. Useful for verifying a new prompt or script before the next automatic run. |
| Pause Schedule | Suspends automatic execution without deleting the task. The task stays in the list with a "paused" badge and can be resumed at any time. |
| Resume Schedule | Re-activates a paused scheduled task. The next run will be calculated from the current time according to the original schedule. |
| Execution History | Each task keeps a log of past runs with status (success / failure), duration, exit code, stdout/stderr output. For AI tasks, the full session conversation is also stored and viewable. |
| Edit Task | Change the task name, prompt, script, or schedule at any time. Not available while a task is currently running. |
Drafts are auto-saved as you type in the task workbench — if you accidentally close the window, your work will be restored when you reopen the New Task form.
Data Blocks
Data Blocks are visual panels that display account metrics and custom data right inside TweetPilot. There are two kinds: built-in blocks that automatically read your managed account data, and custom blocks that you build yourself — powered by any data source you choose.
Built-in Data Blocks
Built-in blocks are tied to your managed accounts. Use the account switcher at the top of each block to view data for different accounts. Only accounts marked as Managed appear here — the longer TweetPilot runs, the richer the historical data becomes.
| Block | What It Shows | Time Range |
|---|---|---|
| Account Snapshot | The latest values for followers, following count, tweet count, liked count, listed count, and media count — a real-time snapshot of the account's current state. | Latest |
| Follower Growth Trend | A time-series curve of follower count changes over the past N hours, letting you see whether the account is growing, plateauing, or declining. | 24h / 7d / 30d |
| Activity Metrics | Trends in tweet count, liked count, and media count over time — useful for understanding posting frequency and content activity changes. | 24h / 7d / 30d |
| Account Overview | A consolidated multi-metric dashboard showing current values alongside change deltas — all key dimensions at a glance. | 24h / 7d / 30d |
Built-in blocks require at least one Managed account with collected snapshots. If you just added an account, data will appear after the first collection cycle. Go to Account Management → set account as Managed to start collecting.
Custom Data Blocks
Custom blocks let you visualize any data you care about — not just Twitter metrics. You define both the data and how it's displayed. Each custom block has a dedicated AI agent that guides you through the full build process.
How Custom Blocks Work
① Local Database
All custom block data lives in a single SQLite file at
.tweetpilot/custom_blocks.db in your workspace. TweetPilot only reads from this file — nothing is synced to the cloud.② Data Write-in
Any program can write data into
custom_blocks.db — a Python script run as a TweetPilot scheduled task, an external tool, or any process that can write SQLite. The AI can generate the write script for you.③ Display HTML
Each custom block is a self-contained HTML file. It uses
window.tweetpilot.query(sql) to run SELECT queries against the database and renders results as charts or tables. The AI generates this HTML for you — just describe what you want to see.Creating a Custom Block
1
Click + and Start AI Collaboration
In the Data Blocks sidebar, click the + button. Enter a name and a brief description of what you want to track. Click Next — Start AI Collaboration to open the dedicated Data Block AI agent.
2
AI Creates the Table and Write Script
The AI agent will create the table in
custom_blocks.db and generate a Python script (or other program) that writes data into it. You can schedule this script as a TweetPilot task to keep data flowing automatically.3
AI Generates the Display HTML
The AI generates a self-contained HTML file (saved to the
cards/ folder in your workspace) that queries the database and renders your data as charts or tables. All chart libraries are inlined — no external CDN dependencies.4
Install and View
Click + again, choose Install existing HTML, and select the generated file. The block appears in your sidebar immediately. Use AI Edit at any time to update the layout, queries, or styling.
Example: Write Data with a Scheduled Python Script
write_stats.py · runs as a scheduled task
import sqlite3, os
from clawbot import ClawBotClient
DB_PATH = os.path.join(os.environ["TWEETPILOT_WORKSPACE"], ".tweetpilot", "custom_blocks.db")
bot = ClawBotClient()
info = bot.x.users.get_basic_info()
conn = sqlite3.connect(DB_PATH)
conn.execute("""
CREATE TABLE IF NOT EXISTS daily_stats (
-- 用途：每日账号粉丝/推文数快照，由定时任务写入
date TEXT PRIMARY KEY,
followers INTEGER,
tweets INTEGER
)
""")
conn.execute(
"INSERT OR REPLACE INTO daily_stats VALUES (date('now'), ?, ?)",
(info["followers_count"], info["statuses_count"])
)
conn.commit()
conn.close()
print("✅ Stats written to custom_blocks.db")
The display HTML for this table would call
window.tweetpilot.query("SELECT date, followers FROM daily_stats ORDER BY date DESC LIMIT 30") and render a trend chart. The AI generates both the script and the HTML for you.Data doesn't have to come from Twitter. Any external program can write to
custom_blocks.db — sales data, server metrics, WeChat analytics, anything. TweetPilot's custom blocks are a general-purpose local data visualization layer.X API Configuration
The X API route connects to Twitter's official API v2 using OAuth 2.0 — no browser required. Once authorized, TweetPilot stores your access token and scripts retrieve it on demand via POST /api/v1/x/oauth/access-token. This is the second of TweetPilot's two Twitter access routes — complementing LocalBridge with DM support and official API compliance.
LocalBridge vs X API — When to Use Which
| Scenario | Recommended Route | Reason |
|---|---|---|
| Search tweets, like, retweet, post, follow, bookmark | LocalBridge | Free, no rate limits, full GraphQL data (likes, screen_name, etc.) — requires Chrome open |
| Send / read Direct Messages (DMs) | X API | LocalBridge does not support DMs; X API v2 has full DM read/write access |
| Headless server / no browser environment | X API | Token is stored, no Chrome or active browser session needed |
| Official API compliance required | X API | Uses Twitter's published v2 endpoints with proper OAuth 2.0 |
| High-volume automation (100+ actions/day) | LocalBridge | X API free tier has strict caps; LocalBridge has none |
How the Token Flow Works
After you authorize an account (Step 5 below), TweetPilot stores the OAuth 2.0 access token securely. Scripts never handle the token directly — they ask LocalBridge to retrieve it at runtime:
Your Script
POST /api/v1/x/oauth/access-token→
token
LocalBridge
Returns stored OAuth 2.0 access token for the requested twitter_id
:20088
→
Bearer
Twitter API v2
Official endpoints: posts, users, DMs, media, lists
api.twitter.com
Important: Always pass the token as
access_token= (User OAuth 2.0) — not bearer_token= (App-only, read-only). Write operations like retweet, post, and DM require a user access token.Setup: Connect an X API Account
1
Apply for Developer Access
a
Go to console.x.com and sign in with your Twitter/X account.
b
If this is your first time, complete the developer application. Briefly describe your intended use case — typical automation and analytics use cases are approved quickly.
2
Create a Project and App
a
In the Developer Portal, create a new Project, then create an App inside it.
b
In the App's Settings tab, find User authentication settings and enable OAuth 2.0. Set the App permissions to Read and Write.
3
Fill in the Callback URL — This Step is Critical
a
In TweetPilot, go to Settings → X API. You will see a read-only Callback URL field with a Copy button. Click it to copy the URL — it looks like
http://127.0.0.1:20088/oauth/callback.b
Back in the X Developer Portal, go to your App's Settings → App info. Find the Callback URI / Redirect URL field and paste the URL you just copied. Save the changes.
Why this matters: The Callback URL is generated from your LocalBridge REST port. If you ever change the port in Settings → LocalBridge, the Callback URL will change — and you'll need to update it in the X Developer Portal as well, otherwise OAuth login will fail.
4
Copy Client ID and Client Secret
a
In the X Developer Portal, go to your App's Keys and Tokens tab. Under OAuth 2.0 Client ID and Client Secret, copy both values.
b
Back in TweetPilot Settings → X API, paste the Client ID and Client Secret into the corresponding fields, then click Save.
5
Add Account via X API
Go to Accounts in the sidebar, click Add Account, and choose X API (Direct). TweetPilot will open an OAuth authorization page in your browser — log in and authorize the app. Once approved, the account will appear in your list.
The free X API tier has strict rate limits. For automation-heavy workflows, consider upgrading to the Basic plan ($100/month) or using TweetClaw mode instead.
Calling X API from Python — xdk SDK
The xdk SDK wraps Twitter API v2 calls. Install it once (pip install xdk), then retrieve the access token from LocalBridge and pass it to the client. The pattern is the same across all scripts.
Step 1 — Get access token from LocalBridge
import requests
def get_access_token(twitter_id: str) -> str:
"""Retrieve the stored OAuth 2.0 token for the given account."""
resp = requests.post(
"http://127.0.0.1:20088/api/v1/x/oauth/access-token",
json={"twitter_id": twitter_id},
timeout=10,
)
resp.raise_for_status()
return resp.json()["access_token"]
# Your numeric Twitter account ID (find it in TweetPilot → Accounts)
TWITTER_ID = "1735224873365225472"
token = get_access_token(TWITTER_ID)
Step 2 — Search tweets and retweet top results (S08 pattern)
from xdk import Client
import time
# Must use access_token= (User OAuth 2.0), NOT bearer_token= (read-only App token)
client = Client(access_token=token)
# Search recent tweets
tweets = []
for page in client.posts.search_recent(
query="#AI",
max_results=20,
tweet_fields=["public_metrics", "text"],
):
tweets.extend(page.data or [])
break # one page per run
# Sort by like_count, retweet top 3 with >= 100 likes
def likes(t):
m = t.get("public_metrics") if isinstance(t, dict) else getattr(t, "public_metrics", {})
return (m or {}).get("like_count", 0)
for t in sorted(tweets, key=likes, reverse=True)[:3]:
if likes(t) < 100: continue
tweet_id = t.get("id") if isinstance(t, dict) else t.id
client.users.repost_post(id=TWITTER_ID, body={"tweet_id": tweet_id})
print(f"Retweeted {tweet_id} ({likes(t)} likes)")
time.sleep(3)
Other common xdk operations
# Post a tweet
client.posts.create_tweet(text="Hello from TweetPilot!")
# Fetch your mention timeline (since_id filters to new mentions only)
for page in client.users.get_mentions(id=TWITTER_ID, max_results=20, since_id=last_id):
for mention in (page.data or []):
print(mention.get("text") if isinstance(mention, dict) else mention.text)
break
# Get user info by username
user = client.users.find_user_by_username(username="elonmusk",
user_fields=["public_metrics", "description"])
# Send a Direct Message
client.dm.create_message(
participant_id="TARGET_USER_ID",
text="Hey, just spotted your tweet!"
)
xdk returns dicts or objects depending on the endpoint. Always guard with
t.get("id") if isinstance(t, dict) else t.id — this pattern is used throughout all S0x example scripts and handles both response formats safely.Feishu / Lark Integration
TweetPilot connects to Feishu via your own bot credentials (App ID + App Secret). Once configured, you get two capabilities: push messages from Python scripts, and a Feishu AI Assistant that lets you control TweetPilot remotely by private message — from your phone, anywhere.
Your bot, your data — zero relay. Messages travel directly between Feishu's servers and TweetPilot running on your own Mac. TweetPilot's servers are never in the loop. Every user creates their own Feishu app with their own credentials — no one else can see your conversations or commands.
Message Flow
You (Feishu app)
Send a message on phone or desktop
Any device
→
Feishu API
TweetPilot (your Mac)
Receives event via long-poll to Feishu API using your credentials
Local — your machine
→
Local agent
Feishu AI Agent
Runs locally, processes your command, replies via Feishu API
ClawBot · xdk
TweetPilot's servers are not part of this chain. The bot only polls Feishu using the credentials you entered — if TweetPilot is not running on your Mac, the bot is offline.
Two Capabilities After Setup
Push from Scripts
In any Python task or report script, call
POST http://localhost:20088/api/v1/feishu/send to push a text message to your Feishu private conversation. Works from scheduled tasks for automated reporting.Feishu AI Assistant
Message the bot in a Feishu private chat like you'd message a person. It can read workspace files, help draft tweet content, answer questions about TweetPilot, and confirm execution of scripts — all in natural language, from your phone or desktop.
Setup: Create a Feishu App
1
Create an App in the Feishu Developer Console
Go to open.feishu.cn/app and sign in. Click Create App → Custom App. Give it a name (e.g. "TweetPilot Bot") and save.
2
Copy App ID and App Secret
In the app's Credentials & Basic Info page, copy the App ID and App Secret. These are the only two credentials you need.
3
Enable the Bot Feature & Set Permissions
Go to App Capabilities → Bot and enable it. Then go to Permissions & Scopes and grant at least:
im:message:send_as_bot and im:message.4
Enter Credentials in TweetPilot
In TweetPilot, go to Settings → Feishu. Paste your App ID and App Secret, then click Save. The status indicator will show Connected once the channel is established.
5
Restrict Availability — Important
Before publishing, go to App Release → App Availability and set the visible range to specific people only (yourself, or a small trusted list). Do not make the bot available to your entire organization. Anyone who can find and message your bot can issue commands to your TweetPilot — keep the list tight.
6
Send Yourself a Message to Activate
In Feishu, find the bot app and send it any message (e.g. "hello"). This binds your Feishu user ID so TweetPilot knows where to deliver future push messages. After this step, both push notifications and the AI assistant are fully active.
Access control is your responsibility. Feishu does not authenticate users at the bot level — anyone who messages your bot can talk to your TweetPilot AI agent, which has access to your workspace files and can execute scripts. Always restrict bot availability to yourself or a small, trusted list. If you suspect unauthorized access, regenerate your App Secret in the Feishu Developer Console immediately.
Push Messages from a Python Script
send_feishu.py
import requests
resp = requests.post(
"http://localhost:20088/api/v1/feishu/send",
json={"text": "📊 Daily report ready — check your workspace!"},
timeout=10,
)
print(resp.json()) # {"ok": true}
Common errors:
尚未绑定任何飞书 ID — you haven't sent the bot a message yet (Step 6). empty_text — the text field is empty.Feishu AI Assistant
Once connected, the bot is your private AI assistant running entirely on your own Mac. Message it like any Feishu contact — from your phone or desktop. It can draft tweet content, answer TweetPilot questions, read data files in your workspace, and confirm execution of pre-authorized scripts. Replies are always concise. See the AI Agent section for its full capabilities.
Contact Us on Feishu
Scan the QR code below to reach our support team directly on Feishu for real-time help.
Upgrade & Plans
TweetPilot is free to start. Unlock scheduled automation and AI agents with Pro, or reach out for an Enterprise plan with hands-on service. View pricing & purchase →
Which plan is right for you?
Pro · Self-serve online
Pro
Solo operators & tech-savvy teams
Purchase online via FastSpring — the license key is emailed instantly after payment. Sign in with the same email inside TweetPilot and the license activates automatically. Everything is self-serve. Set up AI agents and scheduled tasks by following our video tutorials and documentation. Best for individuals and teams who are comfortable running their own tools.
Enterprise · Hands-on service
Enterprise
Companies without an IT department
No online store — reach out to discuss your needs and we handle the rest. We provide hands-on onboarding: demo the product with your team, configure the first AI agent together, and document your workflow. We can also develop custom scripts or features tailored to your business. A signed service agreement covers scope, pricing, and support terms. Permanent license (P-xxx), no annual renewal required.
Feature Comparison
| Feature | Free | Pro | Enterprise |
|---|---|---|---|
| Core | |||
| Multiple accounts | ✓ | ✓ | ✓ |
| TweetClaw integration | ✓ | ✓ | ✓ |
| X API integration | ✓ | ✓ | ✓ |
| Data Blocks | ✓ | ✓ | ✓ |
| Manual Python scripts | ✓ | ✓ | ✓ |
| Automation & AI | |||
| Scheduled tasks (cron) | ✗ | ✓ | ✓ |
| AI agents (Task / Feishu) | ✗ | ✓ | ✓ |
| Feishu integration | ✗ | ✓ | ✓ |
| License & Service | |||
| Price | $0 | $300 / yr | Contact us |
| License type | — | Annual (S-xxx) | Permanent (P-xxx) |
| Devices per license | 1 | 2 | Custom |
| 30-day free trial | ✓ | — | — |
| Onboarding & training | ✗ | Self-serve (docs / video) | ✓ |
| Custom development | ✗ | ✗ | ✓ |
| Service contract | ✗ | ✗ | ✓ |
Not ready to buy? Start a 30-day free trial — click Start Free Trial after sign-in to unlock all Pro features for 30 days, no payment required. Trial is limited to 1 device and does not auto-renew.
