Agent-Reach/docs

👁️ Agent Reach

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

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 ⭐9.8K)
🐦 Twitter/X	Read · Search	Zero config / Cookie	Single tweets readable out of the box. Cookie unlocks search, timeline, posting (birdx)
📕 XiaoHongShu	Read · Search · Post · Comment · Like	mcporter	Via xiaohongshu-mcp internal API, install and go
🔍 Web Search	Search	Auto-configured	Auto-configured during install, free, no API key (Exa via mcporter)
📦 GitHub	Read · Search	Zero config	gh CLI 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 ⭐148K)
📺 Bilibili	Read · Search	Zero config / Proxy	Video info + subtitles + search. Local works directly, servers need a proxy (yt-dlp)
📡 RSS	Read	Zero config	Any RSS/Atom feed (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

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 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

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

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	9.8K stars, free, no API key needed
Read tweets	birdx	Cookie auth, no $100/month official API
Video subtitles + search	yt-dlp	148K stars, YouTube + Bilibili + 1800 sites
Search the web	Exa via mcporter	AI semantic search, MCP integration, no API key
GitHub	gh CLI	Official tool, full API after auth
Read RSS	feedparser	Python ecosystem standard, 2.3K stars
XiaoHongShu	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 and PRs 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 · yt-dlp · birdx · Exa · feedparser

License

MIT