MonoSurf

Browser-based platform access for AI. Read and write any website through Chrome DevTools Protocol.

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

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

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

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

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