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
polish: Steve Jobs pass — simplify install to near-zero friction
Panniantong1d1484fc161b
diff --git a/agent_eyes/cli.py b/agent_eyes/cli.pyindex f87f4541..fe24ccd7 100644--- a/agent_eyes/cli.py+++ b/agent_eyes/cli.py@@ -70,8 +70,8 @@ def main():# ── install ──p_install = sub.add_parser("install", help="One-shot installer with flags")- p_install.add_argument("--env", choices=["local", "server"], default="local",- help="Environment: local computer or server/VPS")+ p_install.add_argument("--env", choices=["local", "server", "auto"], default="auto",+ help="Environment: local, server, or auto-detect")p_install.add_argument("--search", choices=["yes", "no"], default="yes",help="Enable web search (needs free Exa API key)")p_install.add_argument("--proxy", default="",@@ -132,6 +132,16 @@ def _cmd_install(args):print("👁️ Agent Eyes Installer")print("=" * 40)+ # Auto-detect environment+ env = args.env+ if env == "auto":+ env = _detect_environment()++ if env == "server":+ print(f"📡 Environment: Server/VPS (auto-detected)")+ else:+ print(f"💻 Environment: Local computer (auto-detected)")+# Apply flagsif args.exa_key:config.set("exa_api_key", args.exa_key)@@ -143,16 +153,14 @@ def _cmd_install(args):print(f"✅ Proxy configured for Reddit + Bilibili")# Environment-specific advice- if args.env == "server":- print(f"📡 Environment: Server/VPS")- if not args.proxy:- print(f"⚠️ Reddit and Bilibili block server IPs.")- print(f" To unlock: agent-eyes configure proxy http://user:pass@ip:port")- print(f" Recommend: https://www.webshare.io ($1/month)")- else:- print(f"💻 Environment: Local computer")+ if env == "server" and not args.proxy:+ print()+ print("💡 Tip: Reddit and Bilibili block server IPs.")+ print(" Reddit search still works via Exa (free).")+ print(" For full access: agent-eyes configure proxy http://user:pass@ip:port")+ print(" Cheap option: https://www.webshare.io ($1/month)")- # Test zero-config features+ # Test channelsprint()print("Testing channels...")results = check_all(config)@@ -161,19 +169,58 @@ def _cmd_install(args):print(f"✅ {ok}/{total} channels active")# What's missing- if args.search == "yes" and not args.exa_key:+ if args.search == "yes" and not args.exa_key and not config.get("exa_api_key"):print()- print("🔍 Search not yet configured. Run:")+ print("🔍 Recommended: unlock search with a free Exa API key")print(" agent-eyes configure exa-key YOUR_KEY")- print(" (Get free key: https://exa.ai)")+ print(" Get free key: https://exa.ai")# Final statusprint()print(format_report(results))print()print("✅ Installation complete!")- if ok < total:- print(f" Run `agent-eyes configure` to unlock remaining channels.")+++def _detect_environment():+ """Auto-detect if running on local computer or server."""+ import os++ # Check common server indicators+ indicators = 0++ # SSH session+ if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"):+ indicators += 2++ # Docker / container+ if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):+ indicators += 2++ # No display (headless)+ if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):+ indicators += 1++ # Cloud VM identifiers+ for cloud_file in ["/sys/hypervisor/uuid", "/sys/class/dmi/id/product_name"]:+ if os.path.exists(cloud_file):+ try:+ content = open(cloud_file).read().lower()+ if any(x in content for x in ["amazon", "google", "microsoft", "digitalocean", "linode", "vultr", "hetzner"]):+ indicators += 2+ except:+ pass++ # systemd-detect-virt+ try:+ import subprocess+ result = subprocess.run(["systemd-detect-virt"], capture_output=True, text=True, timeout=3)+ if result.returncode == 0 and result.stdout.strip() != "none":+ indicators += 1+ except:+ pass++ return "server" if indicators >= 2 else "local"def _cmd_configure(args):diff --git a/docs/install.md b/docs/install.mdindex 19d39edf..c2c40b5b 100644--- a/docs/install.md+++ b/docs/install.md@@ -2,243 +2,129 @@## For Humans-Copy and paste this to your AI Agent (Claude Code, OpenClaw, Cursor, etc.):+Copy this to your AI Agent:```-Install and configure Agent Eyes by following the instructions here:-https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md+Install and configure Agent Eyes: https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md```-Your Agent will handle everything. You just answer a few questions.----## For AI Agents-You are installing Agent Eyes — giving yourself eyes to see the entire internet.-Follow this guide step by step. Do not improvise.+Follow these steps exactly. Minimize questions to the user.-### Step 1: Install+### Step 1: Install + auto-detect```bash-pip install git+https://github.com/Panniantong/agent-eyes.git+pip install git+https://github.com/Panniantong/agent-eyes.git || pip3 install git+https://github.com/Panniantong/agent-eyes.git+agent-eyes doctor```-If fails: try `pip3`, or add `--user`, or `--break-system-packages`.+Read the doctor output. It tells you:+- What's already working (zero-config channels)+- What needs a key/cookie/proxy-Verify:+Also auto-detect the environment:```bash-agent-eyes version+agent-eyes install --env=auto```+This command auto-detects local vs server (checks if running in SSH, Docker, or cloud VM).-### Step 2: Detect environment--Ask the user:--> "First question: are you running on a **local computer** or a **server/VPS**?"--This determines what works out of the box and what needs extra setup.+### Step 2: Show ONE simple summary to user-### Step 3: Show channel menu--Present this menu to the user. Adjust the details based on their environment (local vs server).--**IMPORTANT**: Make sure the user understands what each tier means and what they get/miss.-----+Based on doctor output, tell the user what's already working and what ONE thing you recommend:-> **Agent Eyes supports these channels. Let me help you choose what to set up.**->-> ---->-> **🟢 Already active — works right now, nothing needed:**->-> | Channel | What it does |-> |---------|-------------|-> | ✅ Web pages | Read any URL on the internet |-> | ✅ GitHub | Read repos, issues, PRs + search repositories |-> | ✅ RSS | Read any RSS/Atom feed |->-> These 3 channels are always available. No setup needed.->-> ---->-> **🔵 Cookie-based — free, just need to export cookies from your browser (~2 min each):**->-> | Channel | What it does | Without cookies |-> |---------|-------------|-----------------|-> | 🐦 Twitter/X | Read tweets, search timelines, read threads | Can still read individual tweet URLs (basic mode) |-> | 📺 YouTube | Video transcripts (public + age-restricted) | Public videos work without cookies; age-restricted/member-only videos need cookies |-> | 📺 Bilibili | Video info + subtitles | [LOCAL: works without cookies ✅] [SERVER: ⚠️ blocked — needs proxy, see below] |-> | 📕 XiaoHongShu | Read XHS notes + comments | Falls back to basic web reading (less content) |->-> **How to export cookies**: open the site in Chrome → F12 → Application → Cookies → copy the values. I'll walk you through it for each one you choose.+> "✅ Agent Eyes installed! You already have: web pages, GitHub, RSS, YouTube.>-> ---+> **One recommendation**: get a free Exa API key to unlock web search + Reddit search + Twitter search.+> → Go to https://exa.ai, sign up (free), and send me the API key.>-> **🟡 Free API key — one key unlocks 3 search capabilities (~30 seconds):**->-> | Channel | What it unlocks |-> |---------|----------------|-> | 🔍 Exa Search (RECOMMENDED) | **Web search + Reddit search + Twitter search** — one free key powers all three |->-> Without Exa: I can read URLs you give me, but I cannot search the internet for you.-> With Exa: I can find information across the entire web, Reddit, and Twitter.->-> Free tier: 1000 searches/month at https://exa.ai — more than enough for most users.->-> ---->-> **🟠 Proxy-based — needed only on servers, $1/month shared across channels:**->-> | Channel | Why proxy needed | Without proxy |-> |---------|-----------------|---------------|-> | 📖 Reddit | Reddit blocks server IPs | **Reddit search still works via Exa (free!)** — you just can't read full posts with all comments |-> | 📺 Bilibili | Bilibili blocks server IPs | Won't work from server |->-> [ONLY SHOW THIS SECTION IF USER SAID "SERVER"]-> [IF LOCAL: Skip this section — Reddit and Bilibili work directly on local computers]->-> One proxy works for both. Recommend: https://www.webshare.io ($1/month residential proxy).-> Same proxy also works for Bilibili cookies-based access.->-> ---->-> **Which channels do you want me to set up?**-> (I recommend: **Exa Search** for sure, plus any cookie-based channels you actually use)-----+> (I can also set up Twitter, Bilibili, XiaoHongShu, and Reddit later — just ask anytime.)"-Wait for the user to choose. Then go to Step 4.+**Key principle**: only ask for ONE thing now. Don't overwhelm with choices.-### Step 4: Run base installer+### Step 3: Configure Exa (if user provides key)```bash-agent-eyes install --env=<local|server>+agent-eyes configure exa-key THE_KEY```-### Step 5: Configure each selected channel+After success, tell user:-Run the corresponding command for each channel the user chose.-Every configure command auto-tests and gives instant feedback (✅ or ❌).-----+> "✅ Done! I can now search the web, Reddit, and Twitter for you.+>+> Want me to set up any of these too? (just say which ones)+> - 🐦 Twitter deep search (need browser cookies, 2 min)+> - 📕 XiaoHongShu (need browser cookies, 2 min)+> - 📺 Bilibili (need browser cookies, 2 min)+> - 📖 Reddit full reader (need $1/month proxy — search already works via Exa!)+>+> Or just say 'all' and I'll walk you through each one."-#### Exa Search+### Step 4: Configure additional channels (only if user asks)-Tell user: "Go to https://exa.ai, sign up (free), copy your API Key, and send it to me."+For each channel the user asks for, use the appropriate command:+**Twitter:**+Ask: "Open x.com in Chrome → F12 → Application → Cookies → copy **auth_token** and **ct0**"```bash-agent-eyes configure exa-key THE_KEY+agent-eyes configure twitter-cookies AUTH_TOKEN CT0```------#### Twitter/X--Tell user:-> "Open https://x.com in Chrome (make sure you're logged in).-> Press F12 → Application → Cookies → https://x.com-> Find these two values: **auth_token** and **ct0**-> Copy both and send them to me."-+**XiaoHongShu:**+Ask: "Open xiaohongshu.com in Chrome → F12 → Network → click any request → copy the Cookie header value"```bash-agent-eyes configure twitter-cookies AUTH_TOKEN CT0+agent-eyes configure xhs-cookie COOKIE_STRING```------#### YouTube (cookies for age-restricted videos)--Tell user:-> "Most YouTube videos work without any setup. If you want access to age-restricted or member-only videos:-> Which browser do you use? (chrome/firefox/edge/safari)"-+**YouTube (age-restricted only):**+Ask: "Which browser do you use?"```bashagent-eyes configure youtube-cookies chrome```-(replace `chrome` with whatever browser they use — yt-dlp reads cookies directly from the browser)-------#### Bilibili--**If local**: Already works. No setup needed.--**If server**: Needs proxy (same proxy as Reddit, see Proxy section below).--If user also wants cookies for member-only content:-> "Open https://bilibili.com in Chrome (logged in).-> F12 → Application → Cookies → find **SESSDATA**-> Send it to me."-(For now, Bilibili public API works without cookies. Cookie support is for future member-only content.)-------#### XiaoHongShu--Tell user:-> "Open https://www.xiaohongshu.com in Chrome (make sure you're logged in).-> Press F12 → Application → Cookies → https://www.xiaohongshu.com-> Select all cookies, right-click → Copy All-> Or just copy the full cookie string from a network request header.-> Send it to me."+**Bilibili:**+- Auto-detected as local → already works, nothing needed+- Auto-detected as server → needs proxy (same as Reddit, see below)+**Reddit full reader + Bilibili (server only):**+Ask: "Reddit/Bilibili block server IPs. Get a $1/month residential proxy at webshare.io, then send me the proxy address."```bash-agent-eyes configure xhs-cookie THE_COOKIE_STRING+agent-eyes configure proxy http://user:pass@ip:port```------#### Proxy (Reddit + Bilibili on server)--Tell user:-> "Reddit and Bilibili block server IPs. You need a residential proxy to access them.-> 1. Go to https://www.webshare.io-> 2. Sign up and get a residential proxy ($1/month is enough)-> 3. Copy your proxy address (format: http://username:password@ip:port)-> 4. Send it to me"+### Step 5: Final status```bash-agent-eyes configure proxy THE_PROXY_URL+agent-eyes doctor```-This configures the proxy for both Reddit and Bilibili at once.+> "✅ All set! Here's what I can do:+> [list active channels]+>+> Try: 'search Reddit for ...' or 'read this URL: ...'"----### Step 6: Final health check+## Configure anything later-```bash-agent-eyes doctor-```--Summarize what's working for the user. Example:+Users can ask their Agent to configure new channels anytime:+- "Help me set up Twitter for Agent Eyes"+- "I got a proxy, configure it for Agent Eyes"+- "Add my XiaoHongShu cookies"-> "✅ All done! Here's what I can do now:->-> 📖 **Read**: Web, GitHub, YouTube, Bilibili, Twitter, XiaoHongShu, RSS-> 🔍 **Search**: Web, GitHub, Reddit, Twitter->-> Try it out — ask me to search or read anything!"-----+The Agent runs `agent-eyes configure <channel> <value>` — each command auto-tests.## Quick Reference-| Action | Command |-|--------|---------|-| Install | `pip install git+https://github.com/Panniantong/agent-eyes.git` |-| Base setup | `agent-eyes install --env=<local\|server>` |-| Add Exa key | `agent-eyes configure exa-key YOUR_KEY` |-| Add Twitter | `agent-eyes configure twitter-cookies AUTH_TOKEN CT0` |-| Add YouTube | `agent-eyes configure youtube-cookies chrome` |-| Add XiaoHongShu | `agent-eyes configure xhs-cookie COOKIE_STRING` |-| Add proxy | `agent-eyes configure proxy http://user:pass@ip:port` |-| Health check | `agent-eyes doctor` |-| Read URL | `agent-eyes read <url>` |-| Search web | `agent-eyes search "query"` |-| Search GitHub | `agent-eyes search-github "query"` |-| Search Reddit | `agent-eyes search-reddit "query"` |-| Search Twitter | `agent-eyes search-twitter "query"` |+| Command | What it does |+|---------|-------------|+| `agent-eyes doctor` | Show what's working |+| `agent-eyes configure exa-key KEY` | Unlock web/Reddit/Twitter search |+| `agent-eyes configure twitter-cookies TOKEN CT0` | Unlock Twitter deep search |+| `agent-eyes configure xhs-cookie COOKIE` | Unlock XiaoHongShu |+| `agent-eyes configure youtube-cookies chrome` | Unlock age-restricted YouTube |+| `agent-eyes configure proxy URL` | Unlock Reddit + Bilibili (server) |+| `agent-eyes read <url>` | Read any URL |+| `agent-eyes search "query"` | Search the web |