sawz/Agent-Reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: migrate Twitter backend from bird CLI to xreach CLI

Browse Source 
bird CLI (@steipete/bird) is deprecated and no longer maintained.
xreach CLI (xreach-cli on npm) is our maintained fork with:
- Fixed SearchTimeline (POST + updated query ID)
- Built-in proxy rotation support
- Additional features (DMs, notifications, lists)

Changes across 11 files:
- channels/twitter.py: detect xreach instead of bird/birdx
- cli.py: install/doctor/uninstall all reference xreach-cli
- SKILL.md: updated command examples (bird read → xreach tweet)
- guides/setup-twitter.md: rewritten for xreach
- docs/troubleshooting.md: updated proxy guidance
- README.md + README_en.md: all references updated
- config.py: twitter_bird → twitter_xreach
- core.py, mcp_server.py: comment updates

npm package: https://www.npmjs.com/package/xreach-cli
Source: https://github.com/Panniantong/xfetch
This commit is contained in:
Panniantong
2026-02-27 08:17:51 +01:00
parent dbcc668f47
commit 62aacf38b5
11 changed files with 155 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README_en.md
+10 -10
View File
@@ -45,7 +45,7 @@ Copy that to your Agent. A few minutes later, it can read tweets, search Reddit,
|---|---|
| 💰 **Completely free** | All tools are open source, all APIs are free. The only possible cost is a server proxy ($1/month) — local computers don't need one |
| 🔒 **Privacy safe** | Cookies stay local. Never uploaded. Fully open source — audit anytime |
| 🔄 **Kept up to date** | Upstream tools (yt-dlp, bird, Jina Reader, etc.) are tracked and updated regularly |
| 🔄 **Kept up to date** | Upstream tools (yt-dlp, xreach, Jina Reader, etc.) are tracked and updated regularly |
| 🤖 **Works with any Agent** | Claude Code, OpenClaw, Cursor, Windsurf… any Agent that can run commands |
| 🩺 **Built-in diagnostics** | `agent-reach doctor` — one command shows what works, what doesn't, and how to fix it |
@@ -56,7 +56,7 @@ Copy that to your Agent. A few minutes later, it can read tweets, search Reddit,
| Platform | Capabilities | Setup | Notes |
|----------|-------------|:-----:|-------|
| 🌐 **Web** | Read | Zero config | Any URL → clean Markdown ([Jina Reader](https://github.com/jina-ai/reader) ⭐9.8K) |
| 🐦 **Twitter/X** | Read · Search | Zero config / Cookie | Single tweets readable out of the box. Cookie unlocks search, timeline, posting ([bird](https://github.com/steipete/bird)) |
| 🐦 **Twitter/X** | Read · Search | Zero config / Cookie | Single tweets readable out of the box. Cookie unlocks search, timeline, posting ([xreach](https://www.npmjs.com/package/xreach-cli)) |
| 📕 **XiaoHongShu** | Read · Search · **Post · Comment · Like** | mcporter | Via [xiaohongshu-mcp](https://github.com/user/xiaohongshu-mcp) internal API, install and go |
| 🎵 **Douyin** | Video parsing · Watermark-free download | mcporter | Via [douyin-mcp-server](https://github.com/yzfly/douyin-mcp-server), no login needed |
| 💼 **LinkedIn** | Jina Reader (public pages) | Full profiles, companies, job search | Tell your Agent "help me set up LinkedIn" |
@@ -112,7 +112,7 @@ No configuration needed — just tell your Agent:
- "Read this link" → `curl https://r.jina.ai/URL` for any web page
- "What's this GitHub repo about?" → `gh repo view owner/repo`
- "What does this video cover?" → `yt-dlp --dump-json URL` for subtitles
- "Read this tweet" → `bird read URL --json`
- "Read this tweet" → `xreach tweet URL --json`
- "Subscribe to this RSS" → `feedparser` to parse feeds
- "Search GitHub for LLM frameworks" → `gh search repos "LLM framework"`
@@ -172,7 +172,7 @@ Every time you spin up a new Agent, you spend time finding tools, installing dep
Agent Reach does one simple thing: **it makes those tool selection and configuration decisions for you.**
After installation, your Agent calls the upstream tools directly (bird CLI, yt-dlp, mcporter, gh CLI, etc.) — no wrapper layer in between.
After installation, your Agent calls the upstream tools directly (xreach CLI, yt-dlp, mcporter, gh CLI, etc.) — no wrapper layer in between.
### 🔌 Every Channel is Pluggable
@@ -181,7 +181,7 @@ Each platform maps to an upstream tool. **Don't like one? Swap it out.**
```
channels/
├── web.py → Jina Reader ← swap to Firecrawl, Crawl4AI…
├── twitter.py → bird ← swap to Nitter, official API…
├── twitter.py → xreach ← swap to Nitter, official API…
├── youtube.py → yt-dlp ← swap to YouTube API, Whisper…
├── github.py → gh CLI ← swap to REST API, PyGithub…
├── bilibili.py → yt-dlp ← swap to bilibili-api…
@@ -202,7 +202,7 @@ Each channel file only checks whether its upstream tool is installed and working
| Scenario | Tool | Why |
|----------|------|-----|
| Read web pages | [Jina Reader](https://github.com/jina-ai/reader) | 9.8K stars, free, no API key needed |
| Read tweets | [bird](https://github.com/steipete/bird) | Cookie auth, free. Official API is pay-per-use ($0.005/post read) |
| Read tweets | [xreach](https://www.npmjs.com/package/xreach-cli) | Cookie auth, free. Official API is pay-per-use ($0.005/post read) |
| Video subtitles + search | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | 148K stars, YouTube + Bilibili + 1800 sites |
| Search the web | [Exa](https://exa.ai) via [mcporter](https://github.com/nicepkg/mcporter) | AI semantic search, MCP integration, no API key |
| GitHub | [gh CLI](https://cli.github.com) | Official tool, full API after auth |
@@ -233,7 +233,7 @@ This project was entirely vibe-coded 🎸 There might be rough edges here and th
<details>
<summary><strong>How to search Twitter/X with AI agent without paying for API?</strong></summary>
Agent Reach uses the [bird CLI](https://www.npmjs.com/package/@steipete/bird) with cookie-based authentication — completely free, no Twitter API subscription needed. After installing Agent Reach, export your Twitter cookies using the Cookie-Editor Chrome extension, run `agent-reach configure twitter-cookies "your_cookies"`, and your agent can search with `bird search "query" --json`.
Agent Reach uses the [xreach CLI](https://www.npmjs.com/package/xreach-cli) with cookie-based authentication — completely free, no Twitter API subscription needed. After installing Agent Reach, export your Twitter cookies using the Cookie-Editor Chrome extension, run `agent-reach configure twitter-cookies "your_cookies"`, and your agent can search with `xreach search "query" --json`.
</details>
<details>
@@ -257,13 +257,13 @@ Yes! Agent Reach is an installer + configuration tool. Any AI coding agent that
<details>
<summary><strong>Is Agent Reach free? Any API costs?</strong></summary>
100% free and open source. All backends (bird CLI, yt-dlp, Jina Reader, Exa) are free tools that don't require paid API keys. The only optional cost is a residential proxy (~$1/month) if you need Reddit/Bilibili access from a server.
100% free and open source. All backends (xreach CLI, yt-dlp, Jina Reader, Exa) are free tools that don't require paid API keys. The only optional cost is a residential proxy (~$1/month) if you need Reddit/Bilibili access from a server.
</details>
<details>
<summary><strong>Free alternative to Twitter API for web scraping?</strong></summary>
Agent Reach uses bird CLI which accesses Twitter via cookie auth — same as your browser session. No API fees, no rate limit tiers, no developer account needed. Supports search, read tweets, read profiles, and timelines.
Agent Reach uses xreach CLI which accesses Twitter via cookie auth — same as your browser session. No API fees, no rate limit tiers, no developer account needed. Supports search, read tweets, read profiles, and timelines.
</details>
<details>
@@ -282,7 +282,7 @@ Install douyin-mcp-server, then your agent can use `mcporter call 'douyin.parse_
## Credits
[Jina Reader](https://github.com/jina-ai/reader) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [bird](https://github.com/steipete/bird) · [Exa](https://exa.ai) · [feedparser](https://github.com/kurtmckee/feedparser) · [douyin-mcp-server](https://github.com/yzfly/douyin-mcp-server) · [linkedin-scraper-mcp](https://github.com/stickerdaniel/linkedin-mcp-server) · [mcp-bosszp](https://github.com/mucsbr/mcp-bosszp)
[Jina Reader](https://github.com/jina-ai/reader) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [xreach](https://www.npmjs.com/package/xreach-cli) · [Exa](https://exa.ai) · [feedparser](https://github.com/kurtmckee/feedparser) · [douyin-mcp-server](https://github.com/yzfly/douyin-mcp-server) · [linkedin-scraper-mcp](https://github.com/stickerdaniel/linkedin-mcp-server) · [mcp-bosszp](https://github.com/mucsbr/mcp-bosszp)
## License
docs/install.md
+5 -5
View File
@@ -20,7 +20,7 @@ Copy this to your AI Agent:
### Goal
Install Agent Reach and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (bird CLI, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is just the installer and health checker.
Install Agent Reach and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (xreach CLI, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is just the installer and health checker.
### ⚠️ Boundaries
@@ -41,7 +41,7 @@ pip install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto
```
This auto-installs system dependencies (gh CLI, Node.js, mcporter, bird), configures Exa search, detects environment, and tests all channels.
This auto-installs system dependencies (gh CLI, Node.js, mcporter, xreach), configures Exa search, detects environment, and tests all channels.
**Safe mode (no automatic system changes):**
@@ -103,9 +103,9 @@ agent-reach configure twitter-cookies "PASTED_STRING"
> **代理说明（中国大陆等需要翻墙的网络环境）：**
>
> bird CLI 使用 Node.js 原生 `fetch()`，默认不走系统代理（`HTTP_PROXY`/`HTTPS_PROXY`）。
> xreach CLI 使用 Node.js 原生 `fetch()`，默认不走系统代理（`HTTP_PROXY`/`HTTPS_PROXY`）。
> Agent Reach 已内置解决方案：安装时会自动安装 `undici`（`npm install -g undici`），
> 运行 bird 时自动注入 `EnvHttpProxyAgent`，让 fetch 走用户配置的代理。
> 运行 xreach 时自动注入 `EnvHttpProxyAgent`，让 fetch 走用户配置的代理。
>
> **你（Agent）需要做的：**
> 1. 确认 `undici` 已全局安装：`npm list -g undici`，没有就装：`npm install -g undici`
@@ -277,7 +277,7 @@ After installation, use upstream tools directly. See SKILL.md for the full comma
| Platform | Upstream Tool | Example |
|----------|--------------|---------|
| Twitter/X | `bird` | `bird search "query" --json` |
| Twitter/X | `xreach` | `xreach search "query" --json` |
| YouTube | `yt-dlp` | `yt-dlp --dump-json URL` |
| Bilibili | `yt-dlp` | `yt-dlp --dump-json URL` |
| Reddit | `curl` | `curl -s "https://reddit.com/r/xxx.json"` |
docs/troubleshooting.md
+39 -64
View File
@@ -1,69 +1,44 @@
# Troubleshooting / 常见问题
# 常见问题排查
## Twitter/X: bird CLI "fetch failed"
## Twitter/X: xreach CLI "fetch failed"
**症状：** `bird whoami` 或 `bird search` 返回 "fetch failed"
**症状：** `xreach search` 或其他命令返回 "fetch failed"
**原因：** bird CLI 使用 Node.js 原生 `fetch()` 发请求，而 Node.js 的 fetch **不走系统代理**（不读取 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）。如果你的网络环境需要代理才能访问 x.com，bird 就连不上。
**解决方案（按推荐顺序）：**
### 方案 1：使用透明代理 / TUN 模式（推荐）
让代理工具接管所有网络流量，这样 bird 的 fetch 也会走代理：
- **Clash Verge / Clash for Windows：** 开启 TUN 模式或系统代理
- **Proxifier（Windows）：** 添加规则让 Node.js 进程走代理
- **macOS：** 在 Surge/ClashX Pro 中开启增强模式
### 方案 2：验证 Cookie 有效性
确认 Cookie 没过期：
1. 在浏览器里正常登录 x.com
2. 用 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 重新导出 Header String
3. 重新配置：`agent-reach configure twitter-cookies "新的Cookie"`
### 方案 3：不用 bird，用 Exa 搜索替代
bird 不可用时，可以直接用 Exa 搜索 Twitter 内容：
```bash
mcporter call 'exa.web_search_exa(query: "site:x.com query", numResults: 10)'
```
### 方案 4：配置 Node.js 全局代理（高级）
安装 `global-agent` 让 Node.js 的 fetch 走代理：
```bash
npm install -g global-agent
```
然后在运行 bird 前设置环境变量：
```bash
# Linux / macOS
export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:7890
export NODE_OPTIONS="--require global-agent/bootstrap"
bird search "test"
# Windows (PowerShell)
$env:GLOBAL_AGENT_HTTP_PROXY = "http://127.0.0.1:7890"
$env:NODE_OPTIONS = "--require global-agent/bootstrap"
bird search "test"
```
> ⚠️ 注意：这个方案需要每次运行 bird 前都设置环境变量，不太方便。推荐用方案 1。
---
## Boss直聘: "访问行为异常"
**症状：** mcp-bosszp 登录成功，但 API 请求返回"您的访问行为异常"
**原因：** Boss直聘的反爬机制会检测请求指纹（不只是 IP），Python requests 库的特征与真实浏览器不同。
**原因：** xreach CLI 使用 Node.js 的 `undici` 库发请求。如果你的网络环境需要代理才能访问 x.com，需要明确传入代理参数。
**解决方案：**
- **本地电脑：** 正常使用，一般不会被拦
- **服务器：** 使用 Jina Reader 读取职位页面 + Exa 搜索职位信息作为替代
### 方案 1：使用 --proxy 参数
```bash
xreach search "test" --auth-token "$AUTH_TOKEN" --ct0 "$CT0" --proxy "http://user:pass@host:port"
```
### 方案 2：使用全局代理工具
让代理工具接管所有网络流量，这样 xreach 的请求也会走代理：
```bash
# macOS — ClashX / Surge 开启"增强模式"
# Linux — proxychains 或 tun2socks
proxychains xreach search "test" -n 1
```
### 方案 3：不用 xreach，用 Exa 搜索替代
xreach 不可用时，可以直接用 Exa 搜索 Twitter 内容：
```bash
mcporter call 'exa.web_search_exa(query: "site:x.com 搜索词", numResults: 5)'
```
### 方案 4：设置 HTTP_PROXY 环境变量
```bash
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
xreach search "test"
```
> ⚠️ 注意：Node.js 原生 fetch 不一定读取这些环境变量，推荐用方案 1 的 --proxy 参数。