Agent Reach

What It Does

Agent Reach is a Python CLI and capability layer that gives any CLI-capable AI agent (Claude Code, OpenClaw, Cursor, Windsurf) the ability to read and search 15 internet platforms with zero API fees. The key distinction, stated in the README and CLAUDE.md and true in the code, is that it is a router, not a wrapper. It does not fetch content itself. Instead it installs the most reliable free backend per platform, health-checks each one with real probes, exposes a doctor command that reports which backend serves each platform right now, and registers a SKILL.md so the agent knows which upstream tool to call for which job. Each platform is an ordered list of candidate backends (Twitter: twitter-cli then OpenCLI then bird CLI), and switching backends means reordering the list, not rewriting code. It targets developers and operators who are tired of re-discovering, installing, and fixing a different scraping tool for every platform every few months.

The Good

The doctor command is the standout feature and it works. agent-reach doctor --json returns a structured object for all 15 channels, each with a status (ok, warn, off), a human-readable name, the ordered backend list, the currently active backend, and a concrete fix prescription. On my host it correctly reported web, RSS, Bilibili search, and V2EX as zero-config ok (active_backend set), GitHub and YouTube as warn (tool present but not fully verified, with the exact reason), and Reddit, Facebook, Instagram, XiaoHongShu, LinkedIn, Xiaoyuzhou, and Exa as off with the exact install command for each. The doctor deliberately avoids side effects: it will not run gh auth status (which writes a device id) and will not read browser cookies unprompted, so a health check cannot mutate your accounts. That is the right security posture for a diagnostics tool.

The multi-backend routing is honest about platform reality, not aspirational. The README and agent_reach/channels/ encode decisions earned from real breakage. Bilibili dropped yt-dlp entirely (blocked by 412 risk control as of June 2026) in favor of bili-cli with no login needed. Reddit has no zero-config path because anonymous .json endpoints are blocked and the official API needs human approval, so the doctor says so plainly instead of pretending. Instagram and Facebook route through OpenCLI reusing an existing Chrome session. Each channel file probes candidates in order and the first fully working one wins, with a fallback chain documented in the SKILL.md references.

The test suite is large and green, with a serious security section. 6,874 lines of Python source against 10,105 lines of tests across 36 test files, a roughly 1.5 to 1 ratio. All 586 tests passed in 16 seconds on my host with zero failures and zero skips needing attention. The security tests are not decorative: test_url_security, test_home_isolation, test_cookie_security, test_scrub_credentials, test_private_file_writes, test_doctor_credential_boundaries, and test_cookie_extract_perms all pass. The MCP error path even scrubs credentials out of exception text (verified by a test that asserts a URL like https://alice:password@example.test?token=secret becomes https://*@example.test?token=*), and the doctor confirms credentials without logging their values.

Documentation is multilingual, progressive, and unusually thorough for a single-author project. The repo ships a primary Chinese README plus English, Japanese, and Korean READMEs, an llms.txt, an install guide, an update guide, a troubleshooting guide, a cookie-export guide, and a dependency-locking note. The SKILL.md comes in both Chinese (SKILL.md) and English (SKILL_en.md), opens with a MUST-USE trigger description and an explicit NOT-for boundary (no report writing, no posting or liking), and routes through seven progressive reference files (search, social, career, dev, web, video, finance). All seven reference files exist and resolve. The SECURITY.md has a real scope list and a 48-hour acknowledgement timeline.

Chinese-platform coverage is a genuine differentiator no Western competitor matches. Bilibili, XiaoHongShu (RedNote), Xueqiu (stock quotes and community), V2EX, and Xiaoyuzhou (podcast transcription via Whisper) are first-class channels with dedicated backends and configuration flows. For anyone building agents that operate in the Chinese internet ecosystem, this is the only capability router that treats these platforms as equals rather than afterthoughts.

The Bad

The optional MCP server is runtime-broken against the current MCP SDK, and the test suite hides it. The pyproject declares mcp[cli]>=1.0, which resolves to MCP SDK 2.0.0. In 2.0.0 the mcp.server.Server class no longer has a list_tools() decorator, so create_server() in agent_reach/integrations/mcp_server.py raises AttributeError: 'Server' object has no attribute 'list_tools' the moment it is called. The 586-test suite still passes because tests/test_mcp_server.py monkeypatches the entire SDK with a hand-rolled _FakeServer that defines list_tools() and call_tool() as no-op decorators. The tests assert security properties of the handler logic, which is valuable, but they never instantiate the real SDK, so the version drift went undetected. This is the highest-yield failure pattern in the space: a loose dependency floor pulls a major version that broke the API. To be fair, the server only exposes a single get_status tool (the doctor report), so the core capability is unaffected, but the README and pyproject advertise an MCP integration that does not currently run.

The PyPI package name is a trap. pip install agent-reach does not install this project. The name agent-reach on PyPI belongs to an unrelated project by Jean Galea (v0.1.0, github.com/jgalea/agent-reach, a different per-channel install tool). The README does warn about this in Chinese, but the warning contradicts the rest of the packaging surface: pyproject.toml sets the project name to agent-reach, and llms.txt advertises a "PyPI Package: pip install agent-reach" link. A user who reads llms.txt or trusts the pyproject name will install the wrong software. The project does not own its distribution name and has not disambiguated consistently.

The CHANGELOG is stale and internally inconsistent. pyproject.toml and the CLI report version 1.5.0, but CHANGELOG.md stops at 1.3.1 (2026-03-27) and skips 1.4.0 and 1.5.0 entirely. The changelog dates also read 2025 where the repo was created in 2026, suggesting the entries were not updated during a rename or reset. Separately, CLAUDE.md describes "13 internet platforms" while the README, llms.txt, and the doctor all report 15. These are documentation nits, not functional bugs, but they undercut the otherwise careful engineering for a reader cross-checking the docs.

Reference docs are Chinese-primary even in the English SKILL. SKILL_en.md is in English, but it openly notes that the seven reference files (social.md, video.md, and so on) are written in Chinese and only the commands are universal. An English-only operator who needs the retry chains and caveats has to read Chinese. Given the multilingual effort elsewhere, leaving the deepest layer untranslated is a gap.

Smoke Test Results

Host test on macOS 26.5.2 aarch64, Python 3.12.13, in a fresh virtualenv with the project installed editable plus dev and mcp extras.

Run A. Fresh sandbox, base deps only

$ python3 -m venv /tmp/ar-venv && source /tmp/ar-venv/bin/activate
$ pip install -e .
Successfully installed agent-reach-1.5.0 ... ✅
$ agent-reach --version
Agent Reach v1.5.0 ✅
$ agent-reach doctor --json | head
{ "github": {...}, "twitter": {...}, ... } ✅ (15 channels)
$ agent-reach install --dry-run --env=auto
SAFE MODE: skipping automatic system changes ✅ (no writes)
$ agent-reach skill --help
usage: agent-reach skill [-h] (--install | --uninstall) ✅
$ agent-reach uninstall --dry-run
[dry-run] Would remove config directory ✅ (no writes)

Pass rate: 6 of 6. Base CLI, doctor, dry-run install, skill, and uninstall all behave correctly with no network credentials. The base install pulls only declared deps cleanly (requests, feedparser, python-dotenv, loguru, pyyaml, rich, yt-dlp).

Run B. Sandbox with dev and mcp extras preinstalled

$ pip install -e ".[dev]"
pytest>=8.0, ruff, mypy, types-* installed ✅
$ python -m pytest -q
586 passed, 16 subtests passed in 15.94s ✅
$ pip install "mcp[cli]>=1.0" → mcp 2.0.0 installed
$ python -c "from agent_reach.integrations.mcp_server import create_server; create_server()"
AttributeError: 'Server' object has no attribute 'list_tools' ❌

Pass rate: 2 of 3. The badge number the listing surfaces: the full test suite is green, but the optional MCP server fails to instantiate against the resolved MCP SDK. This is a dependency-resolution failure (declared >=1.0 pulls a breaking major), not a logic bug, but it is real and shipping.

Run C. Functional verification (does it do what it claims?)

$ agent-reach doctor --json (parsed)
channels: 15
 ok (4): web, rss, bilibili, v2ex ✅ active_backend set
 warn (4): github, twitter, youtube, xueqiu ✅ correct, with fix text
 off (7): reddit, facebook, instagram,
 xiaohongshu, linkedin,
 xiaoyuzhou, exa_search ✅ exact install cmds
$ # SKILL_en.md references
$ for r in search video dev career social finance web; do test -f .../$r.md && echo OK; done
OK x7 ✅ 7 of 7 resolve
$ # MCP server tools/list (real SDK)
$ create_server() ❌ AttributeError (see Run B)

Functional pass rate: 2 of 3. The doctor's status logic and the SKILL.md routing layer are verified. Live platform reads (Twitter, Reddit, XiaoHongShu) could not be exercised because they require login cookies and external upstream CLIs not present in the test environment. The MCP server is the one functional failure.

What the runs tell you

The core product (CLI, doctor, channel routing, SKILL.md, skill registration) is solid and honest. The two cracks are bounded and named: the MCP server extra is broken by unpinned dependency drift, and the PyPI name belongs to someone else. Neither touches the day-to-day value of routing agents to the right free backend, which is what the project is for.

Setup Walkthrough

1. Install from GitHub, not PyPI. The PyPI name is taken by another project: pip install "agent-reach @ https://github.com/Panniantong/agent-reach/archive/main.zip".
2. For the agent-guided path, paste the install guide URL to your agent and let it run the installer. By default it only checks the environment and lists missing pieces. It will not install system packages or write config files unless you pass --system.
3. Preview before any change: agent-reach install --env=auto --dry-run. Safe mode is the default.
4. Run the doctor to see what works: agent-reach doctor --json. The message field for each channel tells you the exact command to enable it.
5. Register the skill so your agent picks it up: agent-reach skill --install. To remove, agent-reach skill --uninstall then agent-reach uninstall.
6. Skip the mcp extra until the project pins mcp<2 or updates the server to the 2.0.0 API. If you installed it, the base CLI is unaffected.

Alternatives

1. Jina Reader (r.jina.ai) - read any single web page for free with one curl. Prefer it if you only ever need articles. Agent Reach uses it as the web backend.
2. Firecrawl / browser-based scraping MCPs - heavier, hosted, and general purpose. Prefer them for bulk structured extraction at scale. Agent Reach routes instead of scraping and stays free.
3. Per-platform CLIs directly (twitter-cli, rdt-cli, yt-dlp) - wire them up yourself. You get full control but lose the doctor, the failover chains, and the maintenance of swapping broken backends.