Documentation Index
Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
Use this file to discover all available pages before exploring further.
MonoSurf
MonoSurf gives AI the ability to browse the web like a human. It drives a real Chrome browser, navigates to sites, extracts content, and performs actions — all through a CLI.
No API keys. No rate limits. No reverse engineering. Just a browser.
┌──────────────────────────────────────────────────────────────────┐
│ MonoSurf v0.4 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ AI (Claude, Codex, etc.) │
│ ↓ CLI command │
│ monosurf x.com search "rust programming" --profile work │
│ ↓ │
│ MonoSurf Engine (Rust binary, ~13MB) │
│ ↓ chromiumoxide (Rust-native CDP client) │
│ Chrome DevTools Protocol — direct, no subprocess │
│ ↓ │
│ Chrome / Playwright Chromium / Puppeteer Chrome │
│ ↓ navigates, waits, extracts │
│ Structured text / JSON output │
│ ↓ │
│ AI reads the result │
│ │
└──────────────────────────────────────────────────────────────────┘
Why Not APIs?
| Approach | Cost | Auth | JS Sites | Rate Limits |
|---|
| Official APIs | $100-5,000/mo | OAuth, API keys | N/A | Strict |
| Scraper libs | Free | Fragile | Fails | Ban risk |
| MonoSurf | Free | Browser session | Works | Human speed |
Core Ideas
1. JSON Site Plugins
Each website is defined by a JSON file. No code changes to add a new site:
sites/
├── x.com.json → X (Twitter)
├── news.ycombinator.com.json → Hacker News
├── github.com.json → GitHub
├── reddit.com.json → Reddit
└── producthunt.com.json → Product Hunt
2. Profiles — Isolated Browser Sessions
Each profile is an independent Chrome instance with its own login sessions:
monosurf start --profile work # Chrome window opens → log in to X
monosurf start --profile personal # Another Chrome → different X account
monosurf x.com trending --profile work
3. Browser Discovery
MonoSurf auto-detects all available browsers on the system:
monosurf browsers
1. Google Chrome 146.0 (system)
2. Playwright chromium 145.0 (playwright) ← stealth, recommended for headless
3. Puppeteer Chrome 146.0 (puppeteer)
4. Time-Gated Access
All access is time-limited. A human physically runs monosurf auth grant to open a time window. When it expires, the browser has no credentials — even reading is blocked.
5. Read/Write Intent
Every command declares its intent:
- read — extracts content, no side effects
- write — posts, replies, modifies state
Write operations require a separate, higher-privilege grant.
Two Modes
| Mode | Command | Browser | Login | Use Case |
|---|
| surf | monosurf x.com trending | Profile Chrome | Yes | Social platforms, authenticated sites |
| browse | monosurf browse <url> | Temp headless | No | Public page crawling, QA |
monofetch → Static HTTP fetch (docs, APIs, llms.txt)
monosurf → Browser-based fetch (JS-heavy sites, login-required)
monogit → Git repository docs
monorss → RSS/Atom feeds
monomento → Search index for all of the above
Version History
| Version | Browser Backend | Key Change |
|---|
| v0.1 | headless_chrome (Rust crate) | Initial — direct CDP |
| v0.2 | Playwright MCP (Microsoft) | Subprocess via OpenCLIs |
| v0.3 | chromiumoxide (Rust-native) | Direct CDP, profiles, browser discovery, cross-platform |
| v0.4 | chromiumoxide (Rust-native) | Multiline posts, batch posting, auth gate, site plugin registry |
