🃏 Subterranean

Give your AI agent internet access — in one command.

The most reliable way in, right now: chosen, installed, and health-checked for you. Routers change over time — you don't have to care.

Quick Start · Supported Platforms · Design · Security

Why Subterranean?

AI agents can write code, edit docs, and manage projects — but ask one to look something up online and it falls apart:

• 📺 "Watch this YouTube tutorial and tell me what it says" → can't, no transcript access
• 🐦 "Search Twitter for what people say about this product" → can't, the Twitter API costs money
• 📖 "Check Reddit for anyone with the same bug" → 403, server IP blocked
• 📕 "Look up reviews of this product on Xiaohongshu" → won't open, login required
• 📺 "Summarize this Bilibili tech video" → can't, generic downloaders are blocked by Bilibili's risk controls
• 🔍 "Find a comparison of the latest LLM frameworks" → no good search, either paid or low quality
• 🌐 "What does this webpage say?" → raw HTML soup, unreadable
• 📦 "What's this GitHub repo about? What did the issues say?" → possible, but auth setup is painful
• 📡 "Subscribe to these RSS feeds and tell me when they update" → requires writing your own code

None of this is hard — it's just tedious to set up.

Every platform has its own gate: paid APIs, blocks to dodge, accounts to log into, data to clean. You fight them one by one. Subterranean turns it into one sentence:

Install Subterranean for me: pip install subterranean && subterranean install

Paste that to your agent. In a few minutes it can read tweets, search Reddit, watch YouTube, and browse Xiaohongshu.

Already installed? Updating is one sentence too:

Update Subterranean for me: pip install --upgrade subterranean

✅ Before you use it, you should know

Supported Platforms

Don't know how to configure it? Skip the docs. Just tell your agent "set up XXX" — it knows what's needed and will walk you through it.

🍪 Twitter accepts only cookies you export manually via Cookie-Editor. Subterranean does not perform Xiaohongshu logins on your behalf or read Xiaohongshu browser cookies; OpenCLI only uses Chrome sessions you already created and control. subterranean configure xhs-cookies does not inject cookies into OpenCLI / Chrome — without an existing session, export via Cookie-Editor and configure xiaohongshu-mcp / legacy tools instead.

Twitter cookies saved via Subterranean are only used by subterranean doctor to verify your setup; before running the upstream twitter command directly, set TWITTER_AUTH_TOKEN and TWITTER_CT0 explicitly in your process environment.

🔒 Cookies stay local — never uploaded, never shared. 💻 No proxy needed on a local machine. Proxies are only for server deployments (~$1/month).

Quick Start

⚠️ OpenClaw users: enable exec permissions first

Subterranean needs your agent to run shell commands (pip install, mcporter, twitter, etc.). If your OpenClaw uses the default messaging tool profile, the agent cannot execute commands. Enable exec permissions before installing:

openclaw config set tools.profile "coding"

Or set "tools": { "profile": "coding" } in ~/.openclaw/openclaw.json. Restart the gateway (openclaw gateway restart) and start a new conversation. Other platforms (Claude Code, Cursor, Windsurf, etc.) are not affected.

Paste this to your AI agent (Claude Code, OpenClaw, Cursor, etc.):

Install Subterranean for me: pip install subterranean && subterranean install

That's it — your agent handles the rest.

🔄 Already installed? Updating is one sentence:

Update Subterranean for me: pip install --upgrade subterranean

🛡️ Safe by default: subterranean install only inspects your environment — it never installs system packages or writes config on its own:

Check my environment and install Subterranean safely: pip install subterranean && subterranean install

Use subterranean install --system only when you explicitly allow system changes.

Works Right After Install

No configuration needed — just ask your agent:

• "Read this link" → curl https://r.jina.ai/URL reads any webpage
• "What's this GitHub repo about?" → gh repo view owner/repo
• "What does this YouTube video say?" → yt-dlp extracts transcripts
• "Search Bilibili for AI tutorials" → bili search (no login)
• "Compare the latest LLM frameworks" → Exa semantic search
• "Subscribe to this RSS feed" → feedparser parses it

No commands to memorize. Your agent reads SKILL.md and knows what to call. For login-gated platforms (Xiaohongshu, Twitter, Reddit, Facebook, Instagram), just say "set up XXX" to unlock them.

Design Philosophy

Subterranean is a capability layer — not another tool.

It sits one level above any specific implementation, handling selection, installation, health checks, and routing — not the reading itself. Actual reading is done by your agent calling upstream tools directly. No wrapper layer.

When you set up an agent from scratch, you always burn time hunting tools and fighting config — what reads Twitter? How does Reddit login work? That CLI for Xiaohongshu got abandoned, what now? You re-tread the same path every time. Subterranean does one thing: the most reliable route in, right now — chosen, installed, and health-checked for you. Routes change over time (in March 2026 a batch of single-platform CLIs was abandoned and we swapped the routing); you don't have to care.

🔌 Every platform = an ordered list of primary + fallback backends

Swapping access methods = reordering the list, not rewriting code. subterranean doctor tells you which backend each platform is using right now.

channels/
├── web.py          → Jina Reader
├── twitter.py      → twitter-cli ▸ OpenCLI ▸ bird
├── youtube.py      → yt-dlp
├── github.py       → gh CLI
├── bilibili.py     → bili-cli ▸ OpenCLI ▸ search API (yt-dlp blocked by Bilibili risk controls, retired)
├── reddit.py       → OpenCLI ▸ rdt-cli (no zero-config path, login required)
├── facebook.py     → OpenCLI (desktop browser session)
├── instagram.py    → OpenCLI (desktop browser session)
├── xiaohongshu.py  → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
├── linkedin.py     → mcp-server-linkedin ▸ Jina Reader
├── rss.py          → feedparser
├── exa_search.py   → Exa via mcporter
└── __init__.py     → channel registry (for doctor checks)

Each channel file actually probes its candidate backends in order (not just checking whether a command exists) — the first fully working one wins, and a broken one prints a fix recipe. The agent then calls the upstream tools directly.

Current Selections

📌 These are current selections, re-verified periodically on real machines. When a route dies, we move to the next — subterranean doctor always tells you which one you're on.

Security

🍪 Cookie Safety

⚠️ Ban risk: platforms where you log in with cookies (Twitter, Xiaohongshu, etc.) may detect scripted/API access and restrict or ban the account. Always use a dedicated secondary account, never your main.

Two reasons for a burner account on cookie/login-gated platforms (Twitter, Xiaohongshu, Reddit, Facebook, Instagram, etc.):

1. Ban risk — platforms can flag API calls that don't look like a normal browser
2. Security risk — a cookie equals full login rights; a secondary account caps the blast radius if credentials leak

📦 Install Options

🗑️ Uninstall

subterranean uninstall

Removes: ~/.subterranean/ (all tokens/cookies), agent skill files, MCP config in mcporter.

# Preview only, delete nothing
subterranean uninstall --dry-run

# Remove skill files only, keep token config (for reinstall)
subterranean uninstall --keep-config

Uninstall the Python package itself: pip uninstall subterranean

⭐ Why Star This

I use this project every day, so I keep maintaining it:

• New channel requests get added over time
• Every channel stays working, pleasant, and free where possible
• When platforms change their anti-bot rules or APIs, I fix the routing

Star it so you can find it next time you need it. ⭐

Acknowledgments

OpenCLI · twitter-cli · rdt-cli · xiaohongshu-mcp · xhs-cli · bili-cli · yt-dlp · Jina Reader · Exa · mcporter · feedparser · mcp-server-linkedin

Contact

• 📧 Email: jetbrathna@gmail.com
• 🐛 Bugs and feature requests: open an issue on the PyPI project page or email

License

MIT