X Fetcher
A command-line tool for fetching X (Twitter) post content, supporting regular tweets and X Article long-form articles, and automatically saving as Markdown format.
Engineering Source: This Skill is based on the
Jane-xiaoer/x-fetcher project.
Features
- Fetch regular tweets (text, images, video links)
- Fetch X Article long-form articles (full content in Markdown format)
- Get interaction data (likes, retweets, views, bookmark counts)
- Automatically save as formatted Markdown files
- Configurable default download directory
Script Directory
Scripts are located in the
subdirectory.
Path Resolution:
- = Directory where this SKILL.md file is located
- Script path =
${SKILL_DIR}/scripts/main.py
Preferences (EXTEND.md)
Use Bash to check if EXTEND.md exists (priority order):
bash
# Check project-level first
test -f .x-fetcher/EXTEND.md && echo "project"
# Then check user-level (cross-platform: $HOME works for macOS/Linux/WSL)
test -f "$HOME/.x-fetcher/EXTEND.md" && echo "user"
┌────────────────────────────────────┬───────────────────┐
│ Path │ Location │
├────────────────────────────────────┼───────────────────┤
│ .x-fetcher/EXTEND.md │ Project directory │
├────────────────────────────────────┼───────────────────┤
│ $HOME/.x-fetcher/EXTEND.md │ User home directory │
└────────────────────────────────────┴───────────────────┘
┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│ Result │ Action │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found │ Read, parse, and apply settings │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ Must run initial setup (see below) — Do not silently create defaults │
└───────────┴───────────────────────────────────────────────────────────────────────────┘
EXTEND.md Support: Default download directory | Media handling method
Initial Setup (Blocking)
Key: When EXTEND.md is not found, you
must use to ask the user for preferences before creating EXTEND.md.
Never create EXTEND.md with default values without asking. This is a
blocking operation —
do not proceed with any conversion until setup is complete.
Use
in
one call to ask all questions:
Question 1 — header: "Download Directory", question: "Default directory path for saving tweets?"
- "x-fetcher (Recommended)" — Save to ./x-fetcher/{username}/{tweet-id}.md
- (User can select "Other" to enter a custom path)
Question 2 — header: "Save Location", question: "Where to save preferences?"
- "User (Recommended)" — ~/.x-fetcher/ (all projects)
- "Project" — .x-fetcher/ (this project only)
After the user answers, create EXTEND.md at the selected location, confirm "Preferences saved to [path]", then proceed.
Supported Configuration Keys
| Key | Default Value | Optional Values | Description |
|---|
| Empty | Path or empty | Default output directory (empty = ) |
| | / | Automatically save Markdown files |
| | / / | Whether to download media files locally ( = ask every time, = always download, = never download) |
Value Priority:
- CLI parameters
- EXTEND.md
- Skill default values
Media Download Notes:
- When is set to , images are saved to the directory, videos to the directory
- Media links in Markdown files are automatically updated to local relative paths
- Supported media formats: Images (jpg, png, gif, webp), Videos (mp4, mov, webm)
Usage
bash
python3 ${SKILL_DIR}/scripts/main.py <url>
python3 ${SKILL_DIR}/scripts/main.py <url> --output /path/to/save
python3 ${SKILL_DIR}/scripts/main.py <url> --download-media
python3 ${SKILL_DIR}/scripts/main.py <url> --json
Options
| Option | Description |
|---|
| Tweet or article URL |
| Output path (directory or file) |
| Download image/video resources to local and directories, and rewrite Markdown links to local relative paths |
| Output in JSON format (do not save Markdown) |
| Do not automatically save Markdown files |
Supported URLs
https://x.com/<user>/status/<id>
https://twitter.com/<user>/status/<id>
Output
Regular Tweet
markdown
# Tweet from @username
> Author: **Author Name** (@username)
> Published: 2024-01-01 12:00:00
> Original Link: https://x.com/user/status/123
---
Tweet content...
## Media
---
## Interaction Data
- ❤️ Likes: 1,234
- 🔁 Retweets: 567
- 👀 Views: 89,000
- 💬 Replies: 123
X Article Long-form Article
markdown
# Article Title
> Author: **Author Name** (@username)
> Published: 2024-01-01 12:00:00
> Updated: 2024-01-02 10:30:00
> Original Link: https://x.com/user/status/123
---
Full article content (Markdown format)...
---
## Interaction Data
- ❤️ Likes: 206,351
- 🔁 Retweets: 28,631
- 👀 Views: 115,555,283
- 🔖 Bookmarks: 571,495
File Structure:
{output_dir}/{username}/{tweet-id}.md
How It Works
- Extract tweet ID from URL
- Try fxtwitter API (supports Articles)
- Fallback to syndication API
- Parse and format output
- Automatically save as Markdown file
Limitations
- Depends on third-party APIs (fxtwitter), which may fail due to service changes
- Cannot fetch content from private accounts
- Some media content may not have complete URLs available
Dependencies
- Python 3.6+
- requests >= 2.25.0
Dependencies are automatically checked on first use, and installation commands will be prompted if not installed.
Extension Support
Custom configurations are supported via EXTEND.md. See the Preferences section for paths and supported options.