Skip to content

Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.

feat: add Agent-readable install guide (one URL to rule them all)

Panniantong33c7b773e0d9
diff --git a/README.md b/README.md
index c72a77ab..8844ee54 100644
--- a/README.md
+++ b/README.md
@@ -2,31 +2,30 @@
**Give your AI Agent eyes to see the entire internet.**
-Agent Eyes is infrastructure for the Agent world — install once, and your AI Agent can search and read content across 10+ platforms. Zero to minimal configuration.
+Agent Eyes is an open-source Agent capability aggregator. It combines the best free tools into one install, so any AI Agent can search and read the entire internet.
-> *Built on top of [x-reader](https://github.com/runesleo/x-reader) by [@runes_leo](https://x.com/runes_leo) — thank you for the amazing open-source work. 🙏*
+> Not a framework. Not a library. Just glue — beautifully simple glue that gives your Agent superpowers.
---
-## Why Agent Eyes?
+## Install (One Line)
-AI Agents are powerful, but blind. They can't browse Reddit, search Twitter, or read WeChat articles. Agent Eyes fixes that.
+**Copy this to your AI Agent** (Claude Code, OpenClaw, Cursor, ChatGPT, etc.):
-- **One install, 10+ platforms** — web pages, GitHub, Reddit, Twitter, YouTube, Bilibili, WeChat, XiaoHongShu, RSS, Telegram
-- **Search + Read** — not just URL extraction, but actual search capability (find, then read)
-- **Agent-native design** — CLI, MCP Server, Python API — works with any AI Agent platform
-- **Mostly free** — 99% of features cost nothing. One free API key unlocks full search.
+```
+Install and configure Agent Eyes by following the instructions here:
+https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
+```
----
+Your Agent reads the guide, installs everything, and configures itself. You just watch.
-## Quick Start
+**Or install manually:**
```bash
-# Install
pip install git+https://github.com/Panniantong/agent-eyes.git
-
-# Check what's available
-agent-eyes doctor
+agent-eyes doctor # See what's available
+agent-eyes setup # Unlock more (optional)
+```
# Read any URL (works immediately, no config needed)
agent-eyes read "https://github.com/openai/gpt-4"
@@ -213,43 +212,48 @@ Run `agent-eyes setup` to unlock more!
## Architecture
-Agent Eyes is **not** a fork of x-reader. It's a layer built on top of it.
+Agent Eyes is pure glue. Every channel is a thin wrapper (~50 lines) around an external tool. **Swap any backend by changing one file.**
```
-┌──────────────────────────────────────┐
-│ Agent Eyes │
-│ ┌──────────┐ ┌──────────────────┐ │
-│ │ Search │ │ Config + Doctor │ │
-│ │ Exa │ │ Setup Wizard │ │
-│ │ Reddit │ │ Health Check │ │
-│ │ GitHub │ │ │ │
-│ │ Twitter │ │ Agent Guides │ │
-│ └──────────┘ └──────────────────┘ │
-│ ┌──────────────────────────────────┐│
-│ │ Readers (based on x-reader) ││
-│ │ Web · GitHub · Reddit · Twitter ││
-│ │ YouTube · Bilibili · WeChat ││
-│ │ XHS · RSS · Telegram ││
-│ └──────────────────────────────────┘│
-│ ┌──────────────────────────────────┐│
-│ │ Integrations ││
-│ │ CLI · MCP Server · OpenClaw Skill│
-│ └──────────────────────────────────┘│
-└──────────────────────────────────────┘
+┌─────────────────────────────────────────┐
+│ Agent Eyes (pure glue) │
+│ │
+│ ┌─────────────────────────────────────┐│
+│ │ Pluggable Channels ││
+│ │ ││
+│ │ web.py → Jina Reader API ││
+│ │ github.py → GitHub API ││
+│ │ twitter.py → birdx + Jina ││
+│ │ youtube.py → yt-dlp ││
+│ │ reddit.py → Reddit JSON API ││
+│ │ bilibili.py → Bilibili API ││
+│ │ rss.py → feedparser ││
+│ │ exa.py → Exa Search API ││
+│ │ ││
+│ │ ↑ Swap any backend, nothing else ││
+│ │ changes. Just edit one file. ││
+│ └─────────────────────────────────────┘│
+│ ┌──────────┐ ┌──────────────────────┐ │
+│ │ Config │ │ Integrations │ │
+│ │ Doctor │ │ CLI · MCP · Skill │ │
+│ │ Guides │ │ Python API │ │
+│ └──────────┘ └──────────────────────┘ │
+└─────────────────────────────────────────┘
```
-- **Readers**: Content extraction from URLs (internalized from x-reader, MIT license)
-- **Search**: Semantic search across platforms (Agent Eyes original)
-- **Config + Doctor**: Configuration management and health checks (Agent Eyes original)
-- **Integrations**: CLI, MCP Server, OpenClaw Skill (Agent Eyes original)
+**Design principle**: Agent Eyes doesn't reinvent wheels. It aggregates the best free tools and makes them accessible to any AI Agent with one install.
---
## Credits
-- **[x-reader](https://github.com/runesleo/x-reader)** by [@runes_leo](https://x.com/runes_leo) — the URL-to-content extraction engine that Agent Eyes is built upon. MIT License.
-- **[Exa](https://exa.ai)** — semantic search API powering web/Reddit/Twitter search.
-- **[birdx](https://github.com/runesleo/birdx)** — Twitter CLI tool for advanced Twitter features.
+Agent Eyes stands on the shoulders of these amazing open-source projects:
+
+- **[Jina Reader](https://r.jina.ai)** — web page reading
+- **[birdx](https://github.com/runesleo/birdx)** by [@runes_leo](https://x.com/runes_leo) — Twitter access
+- **[Exa](https://exa.ai)** — semantic search
+- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — YouTube transcripts
+- **[feedparser](https://github.com/kurtmckee/feedparser)** — RSS/Atom feeds
## License
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 00000000..6462b3cb
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,201 @@
+# Agent Eyes — Installation Guide
+
+## For Humans
+
+Copy and paste this to your AI Agent (Claude Code, OpenClaw, Cursor, ChatGPT, etc.):
+
+```
+Install and configure Agent Eyes by following the instructions here:
+https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
+```
+
+That's it. Your Agent will handle the rest.
+
+---
+
+## For AI Agents
+
+Welcome! You're about to give your user's Agent (that's you!) eyes to see the entire internet.
+Agent Eyes lets you search and read content across 10+ platforms with one install.
+
+### Step 1: Install Agent Eyes
+
+```bash
+pip install git+https://github.com/Panniantong/agent-eyes.git
+```
+
+If `pip` fails, try:
+```bash
+pip3 install git+https://github.com/Panniantong/agent-eyes.git
+```
+
+If permission error, try:
+```bash
+pip install --user git+https://github.com/Panniantong/agent-eyes.git
+```
+
+### Step 2: Verify Installation
+
+```bash
+agent-eyes version
+```
+
+Expected output: `Agent Eyes v1.0.0` (or higher)
+
+If this works, run a health check:
+
+```bash
+agent-eyes doctor
+```
+
+This shows which platforms are already available (many work with zero configuration).
+
+### Step 3: Test Zero-Config Features
+
+These work immediately without any setup:
+
+```bash
+# Read a web page
+agent-eyes read "https://example.com"
+
+# Read a GitHub repo
+agent-eyes read "https://github.com/Panniantong/agent-eyes"
+
+# Search GitHub
+agent-eyes search-github "AI agent framework" -n 3
+```
+
+Tell the user: "✅ Agent Eyes installed! I can now read web pages, GitHub, YouTube, Bilibili, RSS, and tweets. Want me to unlock search too? (free, takes 30 seconds)"
+
+### Step 4: Unlock Search (Optional, Recommended)
+
+Ask the user:
+
+> "I can unlock full web search, Reddit search, and Twitter search with one free API key. Want to set it up? It takes 30 seconds."
+
+If the user says yes:
+
+> "Please go to https://exa.ai, sign up (free), and copy your API key. Then send it to me."
+
+When the user provides the key:
+
+```bash
+# Write the key to config
+python3 -c "
+from agent_eyes.config import Config
+c = Config()
+c.set('exa_api_key', 'THE_KEY_USER_PROVIDED')
+print('✅ Exa API key saved!')
+"
+```
+
+Test it:
+```bash
+agent-eyes search "AI agent infrastructure" -n 3
+```
+
+Tell the user: "✅ Search unlocked! I can now search the entire web, Reddit, and Twitter for you."
+
+### Step 5: Optional — Advanced Channels
+
+Only offer these if the user asks or if relevant to their needs.
+
+#### Twitter Advanced (search timelines, read threads)
+
+Check if birdx is available:
+```bash
+which birdx && echo "already installed" || pip install birdx
+```
+
+If birdx is installed, it works automatically. If the user wants to configure cookie auth for deeper access, read the guide:
+`agent_eyes/guides/setup-twitter.md`
+
+#### Reddit Full Reader (read complete posts + comments)
+
+Reddit blocks many server IPs. Full reading requires a proxy.
+Read the guide: `agent_eyes/guides/setup-reddit.md`
+
+Without a proxy, you can still SEARCH Reddit content via Exa (Step 4).
+
+#### WeChat / XiaoHongShu (Chinese platforms)
+
+```bash
+pip install agent-eyes[browser]
+playwright install chromium
+```
+
+For XiaoHongShu, the user needs to log in once. Read: `agent_eyes/guides/setup-xiaohongshu.md`
+
+### Step 6: Final Health Check
+
+```bash
+agent-eyes doctor
+```
+
+Report the results to the user in a friendly way. Example:
+
+> "Here's what I can do now:
+> ✅ Read: Web, GitHub, YouTube, Bilibili, RSS, Tweets
+> ✅ Search: Web, GitHub, Reddit, Twitter
+> ⬜ Not configured: Reddit full reader, WeChat, XiaoHongShu
+>
+> I'm ready to help! Ask me to search or read anything."
+
+### Using Agent Eyes
+
+After installation, you can use these commands anytime:
+
+```bash
+# Read any URL
+agent-eyes read "<url>"
+
+# Search the web
+agent-eyes search "<query>"
+
+# Search specific platforms
+agent-eyes search-github "<query>"
+agent-eyes search-reddit "<query>" --sub "<subreddit>"
+agent-eyes search-twitter "<query>"
+
+# Check status
+agent-eyes doctor
+```
+
+Or use the Python API:
+```python
+from agent_eyes import AgentEyes
+import asyncio
+
+eyes = AgentEyes()
+result = asyncio.run(eyes.read("https://any-url.com"))
+results = asyncio.run(eyes.search("any query"))
+```
+
+### MCP Server (for Claude Code, Cursor, etc.)
+
+If your platform supports MCP:
+```bash
+pip install agent-eyes[mcp]
+```
+
+Add to MCP config:
+```json
+{
+ "mcpServers": {
+ "agent-eyes": {
+ "command": "python3",
+ "args": ["-m", "agent_eyes.integrations.mcp_server"]
+ }
+ }
+}
+```
+
+### Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `pip: command not found` | Try `pip3` instead |
+| `Permission denied` | Add `--user` flag or use `sudo` |
+| `agent-eyes: command not found` | Run `python3 -m agent_eyes.cli doctor` instead |
+| Search returns "Exa API key not configured" | Run Step 4 above |
+| Reddit returns 403 | Need proxy (see `guides/setup-reddit.md`) |