Skip to main content

​
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?

ApproachCostAuthJS SitesRate Limits
Official APIs$100-5,000/moOAuth, API keysN/AStrict
Scraper libsFreeFragileFailsBan risk
MonoSurfFreeBrowser sessionWorksHuman speed
APIs are expensive, locked down, or don’t exist. Scrapers break when sites change. MonoSurf uses a real Chrome browser with real login sessions.

​
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
A site plugin defines: where to navigate, what to wait for, how to extract content, and how to display it.

​
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
Sessions persist across restarts. Each profile gets its own data directory and CDP port.

​
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)
System Chrome works for visible mode. Playwright/Puppeteer Chromium is recommended for headless — it has stealth built in to avoid bot detection.

​
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

ModeCommandBrowserLoginUse Case
surfmonosurf x.com trendingProfile ChromeYesSocial platforms, authenticated sites
browsemonosurf browse <url>Temp headlessNoPublic page crawling, QA

​
Relationship to Other Tools

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
MonoSurf handles what MonoFetch cannot: JavaScript-rendered content and authenticated sessions.

​
Version History

VersionBrowser BackendKey Change
v0.1headless_chrome (Rust crate)Initial — direct CDP
v0.2Playwright MCP (Microsoft)Subprocess via OpenCLIs
v0.3chromiumoxide (Rust-native)Direct CDP, profiles, browser discovery, cross-platform
v0.4chromiumoxide (Rust-native)Multiline posts, batch posting, auth gate, site plugin registry