πŸ‘οΈ Agent Reach

Give your AI Agent one-click access to the entire internet

MIT License Python 3.10+ GitHub Stars

Quick Start Β· δΈ­ζ–‡ Β· Platforms Β· Philosophy

--- ## Why Agent Reach? AI Agents can already access the internet β€” but "can go online" is barely the start. The most valuable information lives across social and niche platforms: Twitter discussions, Reddit feedback, YouTube tutorials, XiaoHongShu reviews, Bilibili videos, GitHub activity… **These are where information density is highest**, but each platform has its own barriers: | Pain Point | Reality | |------------|---------| | Twitter API | Starts at $100/month | | Reddit | Server IPs get 403'd | | XiaoHongShu | Login required to browse | | Bilibili | Blocks overseas/server IPs | To connect your Agent to these platforms, you'd have to find tools, install dependencies, and debug configs β€” one by one. **Agent Reach turns this into one command:** ``` Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md ``` Copy that to your Agent. 30 seconds later, it can read tweets, search Reddit, and watch Bilibili. ### βœ… Before you start, you might want to know | | | |---|---| | πŸ’° **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, birdx, 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 | --- ## Supported Platforms | 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 ([birdx](https://github.com/runesleo/birdx)) | | πŸ“• **XiaoHongShu** | Read Β· Search Β· **Post Β· Comment Β· Like** | mcporter | Via [xiaohongshu-mcp](https://github.com/user/xiaohongshu-mcp) internal API, install and go | | πŸ” **Web Search** | Search | Auto-configured | Auto-configured during install, free, no API key ([Exa](https://exa.ai) via [mcporter](https://github.com/nicepkg/mcporter)) | | πŸ“¦ **GitHub** | Read Β· Search | Zero config | [gh CLI](https://cli.github.com) powered. Public repos work immediately. `gh auth login` unlocks Fork, Issue, PR | | πŸ“Ί **YouTube** | Read Β· **Search** | Zero config | Subtitles + search across 1800+ video sites ([yt-dlp](https://github.com/yt-dlp/yt-dlp) ⭐148K) | | πŸ“Ί **Bilibili** | Read Β· **Search** | Zero config / Proxy | Video info + subtitles + search. Local works directly, servers need a proxy ([yt-dlp](https://github.com/yt-dlp/yt-dlp)) | | πŸ“‘ **RSS** | Read | Zero config | Any RSS/Atom feed ([feedparser](https://github.com/kurtmckee/feedparser) ⭐2.3K) | | πŸ“– **Reddit** | Search Β· Read | Free / Proxy | Search via Exa (free). Reading posts needs a proxy on servers | > **Setup levels:** Zero config = install and go Β· Auto-configured = handled during install Β· mcporter = needs MCP service Β· Cookie = export from browser Β· Proxy = $1/month --- ## Get Started in 30 Seconds Copy this to your AI Agent (Claude Code, OpenClaw, Cursor, etc.): ``` Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md ``` The Agent auto-installs, detects your environment, and tells you what's ready.
Manual install ```bash pip install https://github.com/Panniantong/agent-reach/archive/main.zip agent-reach install --env=auto ```
--- ## Works Out of the Box No configuration needed β€” just tell your Agent: - "Read this link" β†’ any web page - "What's this GitHub repo about?" β†’ repos, issues, code - "What does this video cover?" β†’ YouTube / Bilibili subtitles - "Read this tweet" β†’ Twitter posts - "Subscribe to this RSS" β†’ RSS / Atom feeds - "Search GitHub for LLM frameworks" β†’ GitHub search **No commands to remember.** The Agent knows what to call. --- ## Unlock on Demand Don't use it? Don't configure it. Every step is optional. ### πŸͺ Cookies β€” Free, 2 minutes Tell your Agent "help me configure Twitter cookies" β€” it'll guide you through exporting from your browser. Local computers can auto-import. ### 🌐 Proxy β€” $1/month, servers only Reddit and Bilibili block server IPs. Get a proxy ([Webshare](https://webshare.io) recommended, $1/month) and send the address to your Agent. > Local computers don't need a proxy. Reddit search works free via Exa even without one. --- ## Status at a Glance ``` $ agent-reach doctor πŸ‘οΈ Agent Reach Status ======================================== βœ… Ready to use: βœ… GitHub repos and code β€” public repos readable and searchable βœ… Twitter/X tweets β€” readable. Cookie unlocks search and posting βœ… YouTube video subtitles β€” yt-dlp ⚠️ Bilibili video info β€” server IPs may be blocked, configure proxy βœ… RSS/Atom feeds β€” feedparser βœ… Web pages (any URL) β€” Jina Reader API πŸ” Search (free Exa key to unlock): ⬜ Web semantic search β€” sign up at exa.ai for free key πŸ”§ Configurable: ⬜ Reddit posts and comments β€” search via Exa (free). Reading needs proxy ⬜ XiaoHongShu notes β€” needs cookie. Export from browser Status: 6/9 channels available ``` --- ## Design Philosophy **Agent Reach is a scaffolding tool, not a framework.** Every time you spin up a new Agent, you spend time finding tools, installing deps, and debugging configs β€” what reads Twitter? How do you bypass Reddit blocks? How do you extract YouTube subtitles? Every time, you re-do the same work. Agent Reach does one simple thing: **it makes those tool selection and configuration decisions for you.** ### πŸ”Œ Every Channel is Pluggable Each platform is a single Python file (~50–100 lines) implementing a unified interface. **Backends can be swapped anytime** β€” when a better tool comes along, change one file and nothing else breaks. ``` channels/ β”œβ”€β”€ base.py β†’ Unified interface (Channel base class) β”œβ”€β”€ web.py β†’ Jina Reader ← swap to Firecrawl, Crawl4AI… β”œβ”€β”€ twitter.py β†’ birdx ← 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… β”œβ”€β”€ reddit.py β†’ JSON API + Exa ← swap to PRAW, Pushshift… β”œβ”€β”€ xiaohongshu.py β†’ mcporter MCP ← swap to other XHS tools… β”œβ”€β”€ rss.py β†’ feedparser ← swap to atoma… β”œβ”€β”€ exa_search.py β†’ mcporter MCP ← swap to Tavily, SerpAPI… └── __init__.py β†’ Channel registry (one line to register a new channel) ``` Want to swap a backend? Open the file, change the `read()` / `search()` implementation. Interface stays the same, nothing else needs to change. ### 🧩 Adding a New Channel (3 Steps) **Step 1:** Create `channels/your_channel.py` ```python from .base import Channel, ReadResult, SearchResult class YourChannel(Channel): name = "your_channel" description = "One-line description" backends = ["tool-name"] def can_handle(self, url: str) -> bool: return "yourdomain.com" in url async def read(self, url: str, config=None) -> ReadResult: # Fetch content, return ReadResult return ReadResult(title="...", content="...", url=url, platform=self.name) def check(self, config=None): return "ok", "All good" # Optional: implement search() for search support ``` **Step 2:** Register in `channels/__init__.py` ```python from .your_channel import YourChannel ALL_CHANNELS: List[Channel] = [ ... YourChannel(), # add this line WebChannel(), ] ``` **Step 3:** Done. `agent-reach doctor` auto-detects it, `agent-reach read` auto-routes to it. > πŸ’‘ **Reference examples:** `rss.py` (30 lines, simplest) β†’ `web.py` (50 lines) β†’ `youtube.py` (100 lines, with search) ### Current Tool Choices | Scenario | Tool | Why | |----------|------|-----| | Read web pages | [Jina Reader](https://github.com/jina-ai/reader) | 9.8K stars, free, no API key needed | | Read tweets | [birdx](https://github.com/runesleo/birdx) | Cookie auth, no $100/month official API | | 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 | | Read RSS | [feedparser](https://github.com/kurtmckee/feedparser) | Python ecosystem standard, 2.3K stars | | XiaoHongShu | [xiaohongshu-mcp](https://github.com/user/xiaohongshu-mcp) | Internal API, bypasses anti-bot | > πŸ“Œ These are the *current* choices. Don't like one? Swap out the file. That's the whole point of scaffolding. --- ## Contributing [Issues](https://github.com/Panniantong/agent-reach/issues) and [PRs](https://github.com/Panniantong/agent-reach/pulls) welcome. ### πŸ†• Want to Add a New Channel? 1. Copy `agent_reach/channels/rss.py` (simplest reference) 2. Implement `can_handle()` + `read()`, optionally `search()` and `check()` 3. Register in `__init__.py` That's it. No framework code to modify, no need to understand other channels. **Channels we'd love to see (PRs welcome):** - πŸ“° Hacker News β€” tech news - 🐘 Mastodon / Fediverse β€” decentralized social - πŸ“± Telegram β€” channels and groups - 🎡 Spotify / Apple Podcasts β€” podcast transcripts - πŸ“ Medium / Substack β€” paywalled articles - πŸ”¬ arXiv / Semantic Scholar β€” academic papers - πŸ’¬ Discord β€” server messages - πŸ“Œ Pinterest β€” image search - … anything you find useful! ## Credits [Jina Reader](https://github.com/jina-ai/reader) Β· [yt-dlp](https://github.com/yt-dlp/yt-dlp) Β· [birdx](https://github.com/runesleo/birdx) Β· [Exa](https://exa.ai) Β· [feedparser](https://github.com/kurtmckee/feedparser) ## License [MIT](../LICENSE)