Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Python agent-infrastructureai-agentai-searchautomationbilibiliclaude-codeclicursorfree-apillm-toolsmcppythonreddit-scrapertwitter-scraperweb-scraperxiaohongshuyoutube-transcript
feat: add Agent-readable install guide (one URL to rule them all)
Panniantong33c7b773e0d9
diff --git a/README.md b/README.mdindex 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-# Installpip 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## Licensediff --git a/docs/install.md b/docs/install.mdnew file mode 100644index 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`) |