Panniantong 74c3df5c3d v2.0.0 — Pure glue architecture: zero copied code, pluggable channels
BREAKING: Complete architectural rewrite.

Before: Copied x-reader's fetcher code into readers/ (1205 lines of borrowed code)
After: Pluggable channel system where each channel is a thin wrapper (~50 lines)
       around the best external tool for that platform. Zero copied code.

Architecture:
- channels/base.py — Universal Channel interface (read, search, check)
- channels/web.py — Jina Reader API (swappable)
- channels/github.py — GitHub API (swappable)
- channels/twitter.py — birdx + Jina fallback (swappable)
- channels/youtube.py — yt-dlp (swappable)
- channels/reddit.py — Reddit JSON API + proxy (swappable)
- channels/rss.py — feedparser (swappable)
- channels/bilibili.py — Bilibili API (swappable)
- channels/exa_search.py — Exa semantic search (swappable)

Key design: every backend can be swapped by changing ONE file.
YouTube dies? Change youtube.py. Exa sucks? Swap exa_search.py for Tavily.
Nothing else changes.

Removed: reader.py, schema.py, readers/, search/, utils/ (all x-reader code)
Tests: 36/36 passing
2026-02-24 05:38:21 +01:00

👁️ Agent Eyes

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.

Built on top of x-reader by @runes_leo — thank you for the amazing open-source work. 🙏


Why Agent Eyes?

AI Agents are powerful, but blind. They can't browse Reddit, search Twitter, or read WeChat articles. Agent Eyes fixes that.

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

Quick Start

# Install
pip install git+https://github.com/Panniantong/agent-eyes.git

# Check what's available
agent-eyes doctor

# Read any URL (works immediately, no config needed)
agent-eyes read "https://github.com/openai/gpt-4"
agent-eyes read "https://www.bilibili.com/video/BV1xx411c7mD"

# Search GitHub (works immediately, no config needed)
agent-eyes search-github "LLM framework"

# Unlock search (one free API key)
agent-eyes setup
agent-eyes search "AI agent infrastructure 2025"
agent-eyes search-reddit "best self-hosted LLM" --sub LocalLLaMA
agent-eyes search-twitter "OpenClaw agent"

Platform Support

✅ Zero Config (works out of the box)

Platform Read Search Notes
Web Pages ✅ — Any URL via Jina Reader
GitHub ✅ ✅ Repos, issues, PRs, code
Bilibili ✅ — Videos with subtitles
YouTube ✅ — Videos with subtitles (needs yt-dlp)
RSS ✅ — Any RSS/Atom feed
Single Tweet ✅ — Via Jina Reader

🔑 One Free API Key (30 seconds to set up)

Platform Read Search Notes
Web (semantic) — ✅ Exa API (1000 free/month)
Reddit — ✅ Via Exa (site:reddit.com)
Twitter/X — ✅ Via Exa (site:x.com)

⚙️ Optional Setup

Platform Read Search What's Needed
Reddit (full) ✅ — ISP proxy (~$3-10/mo)
Twitter (advanced) ✅ ✅ birdx + browser cookies (free)
WeChat Articles ✅ — Playwright (free, auto-installed)
XiaoHongShu ✅ — Playwright + one-time login (free)
Video Transcription ✅ — Groq API key (free)

Three Ways to Use

1. Command Line (CLI)

agent-eyes read <url>                    # Read any URL
agent-eyes search "query"                # Search the web
agent-eyes search-reddit "query"         # Search Reddit
agent-eyes search-github "query"         # Search GitHub
agent-eyes search-twitter "query"        # Search Twitter
agent-eyes setup                         # Interactive setup wizard
agent-eyes doctor                        # Check platform status

2. MCP Server (for Claude Code, Cursor, etc.)

pip install agent-eyes[mcp]
python -m agent_eyes.integrations.mcp_server

Exposes 8 tools: read_url, read_batch, detect_platform, search, search_reddit, search_github, search_twitter, get_status

Add to your MCP config:

{
  "mcpServers": {
    "agent-eyes": {
      "command": "python",
      "args": ["-m", "agent_eyes.integrations.mcp_server"]
    }
  }
}

3. Python Library

from agent_eyes import AgentEyes
import asyncio

eyes = AgentEyes()

# Read
result = asyncio.run(eyes.read("https://github.com/openai/gpt-4"))
print(result["title"])
print(result["content"])

# Search
results = asyncio.run(eyes.search("AI agent framework"))
for r in results:
    print(f"{r['title']} — {r['url']}")

# Search Reddit
results = asyncio.run(eyes.search_reddit("best LLM", subreddit="LocalLLaMA"))

# Health check
print(eyes.doctor_report())

Configuration

Interactive Setup

agent-eyes setup

Walks you through configuring each platform step by step. Only asks for what you want to set up.

Agent-Readable Guides

Each platform has a detailed setup guide in agent_eyes/guides/. These are designed for AI Agents to read and follow — the Agent handles the technical steps, and only asks the user for things that require human action (logging in, copying API keys, buying proxies).

Guide What It Configures
setup-exa.md Exa search API key (free)
setup-reddit.md Reddit ISP proxy
setup-twitter.md Twitter birdx cookies
setup-xiaohongshu.md XiaoHongShu login
setup-wechat.md WeChat Playwright
setup-groq.md Groq Whisper API key (free)

Manual Config

Config file: ~/.agent-eyes/config.yaml

exa_api_key: "exa-..."
github_token: "ghp_..."
reddit_proxy: "http://user:pass@ip:port"
groq_api_key: "gsk_..."

Environment variables also work (uppercase): EXA_API_KEY, GITHUB_TOKEN, etc.


Health Check

$ agent-eyes doctor

👁️  Agent Eyes Status
========================================

✅ Ready (no setup needed):
  ✅ Web Pages
  ✅ GitHub
  ✅ Bilibili
  ✅ RSS
  ✅ Tweet (single)
  ✅ GitHub Search

🔍 Search (need free Exa API key):
  ⬜ Web Search
  ⬜ Reddit Search
  ⬜ Twitter Search

🔧 Optional (advanced setup):
  ⬜ Twitter Advanced — Install birdx for timeline/deep search
  ⬜ Reddit Reader — Need proxy for full post reading
  ⬜ WeChat — pip install agent-eyes[browser]
  ⬜ XiaoHongShu — pip install agent-eyes[browser]

Status: 7/13 platforms active
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                    │
│  ┌──────────┐  ┌──────────────────┐  │
│  │  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│
│  └──────────────────────────────────┘│
└──────────────────────────────────────┘
  • 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)

Credits

  • x-reader by @runes_leo — the URL-to-content extraction engine that Agent Eyes is built upon. MIT License.
  • Exa — semantic search API powering web/Reddit/Twitter search.
  • birdx — Twitter CLI tool for advanced Twitter features.

License

MIT

S
Description
No description provided
Readme
1.9 MiB
Languages
Python 95%
Shell 5%